AutoXDR - NFSv4 Example Definitions

Top level definitions

program

This names the program. It must be formed with valid syntax for a "C" identifier. This must be provided and there may be only one.

prog_id

Program identifying number. For example, NFS is 100003. This must be provided and there may be only one.

prog_version

This defines a version number and the collection of procedures that are supported for the version of the program. See below for further details.

enum

These are used to define enumerations for which it is desired to have translation routines generated. Each enum must have one en_name that contains the enumeration name and prefix for each enumeration value, and one or more en_ent entries that define each enumeration value. The en_ent must have a name (ename) and a description (etype).

status_enum

This must name the enumeration type that is used to return the status of a request. It must define an OK value and, if there are carrier procedures, then it must define an OMITTED value as well. If there are carrier procedures that you wish to allow to continue processing when there are warnings, then the warnings must be lower-valued than the error codes. The default is to stop processing queued procedures when a non-OK result is noted.

xdr_data

These merely contain text that gets passed through to the XDR file. It is not interpreted in any other way by the AutoXDR templates. You may use as many as you need.

Program Versions

version

This is the version number of the program.

status_enum

Each version of the program may have its own enumeration. If they all have unique enumerations, then the global one is not necessary.

procedure

This is used to define each procedure defined for the particular version of the program. The index of the procedure definition will specify the procedure number. Its definition must encompass:

p_name

This specifies the procedure name.

minorversion

If it is a carrier procedure, this may be used to indicate changes in the procedure version within the version of the program.

p_arg

Arguments to the procedure. Zero, one or more of these may be specified. See below for what they must contain.

p_op

If any of these are present, then this is a carrier procedure. Each one specifies the nature of a queueing procedure that is "carried" by this procedure. See the next section.

Queueing Procedures

op_name

This specifies the name of the procedure.

op_arg

Arguments to the procedure. Zero, one or more may be specified. See below for what they must contain.

Argument Definitions

def_name

This specifies the name of the argument.

def_type

This specifies the type of the argument.

in, out, i_o

This specifies whether the argument is for input, output (results), or both.

val, ref, array

This specifies the methods used to pass the value.

• val means the argument is a simple value that is normally passed by value in an argument list.
• ref means the argument is a compound value that is normally passed by address (reference).
• array means that the value is passed by address, but that the address reference is implicit in the C language.

status_union

This specifies several things:

• That this is the only output argument.
  
• The string assigned to it is the type of the argument. That is, it must match the def_type attribute.
  
• The status code is the first field of this structure. Often, this will be the discriminator of a discriminating union.

Example Definition

Below is a brief example extracted from a prototype implementation for NFSv4.

/* -*- Mode: C -*- */

AutoGen Definitions autoxdr.tpl;

/*
 *
 *  $Id: nfsv4-def.html,v 1.15 2006/10/01 20:02:11 bkorb Exp $
 */

program     = nfs;
prog_id     = 100003;
status_enum = "nfs4_status";

/*
 * Remote file service routines, by version
 */
prog_version = {
  version = 4;

  procedure[0] = {
    p_name = NULL;
  };

  procedure[1] = {
    p_name   = COMPOUND;
    minorversion  = 0;

    p_arg = { def_type = utf8string;  def_name = tag_in;       in;  ref; };
    p_arg = { def_type = uint32_t;    def_name = minorversion; in;  val; };
    p_arg = { def_type = utf8string;  def_name = tag_out;     out;  ref; };

    /*
     *  Queued Procedures:
     */
    p_op[ 3] = { op_name = ACCESS4;
      op_arg = { def_name = requested;
                 def_type = uint32_t;    in; val; };
      op_arg = { def_name = access_res; status_union = ACCESS4res;
                 def_type = ACCESS4res; out; ref; };
    };
  };
};
/*
 * Error status
 */
enum = {
  en_name = status;
  en_ent[    0] = { ename = OK;
                    etype = "successful completion"; };
  en_ent[    1] = { ename = PERM;
                    etype = "caller is either not privileged or not owner"; };
  en_ent[    2] = { ename = NOENT;
                    etype = "No such file or directory"; };
  en_ent[  256] = { ename = OMITTED;
                    etype = "operation omitted"; };
};

xdr_data = <<END_XDR_DATA

/*
 * Basic typedefs for RFC 1832 data type definitions
 */
#if defined( RPC_HDR )
%#ifdef NEED_INT32_T
typedef int             int32_t;
%#endif
%#ifdef NEED_UINT32_T
typedef unsigned int    uint32_t;
%#endif
%#ifdef NEED_INT64_T
typedef hyper           int64_t;
%#endif
%#ifdef NEED_UINT64_T
typedef hyper           uint64_t;
%#endif
#else
typedef int             int32_t;
typedef unsigned int    uint32_t;
typedef hyper           int64_t;
typedef hyper           uint64_t;
#endif

/*
 * Sizes
 */
const NFS4_FHSIZE               = 128;

/*
 * Basic data types
 */
typedef uint32_t        bitmap4<>;
typedef char            data<>;
typedef uint64_t        offset4;
typedef uint32_t        count4;
typedef uint64_t        length4;
typedef uint64_t        clientid4;
typedef uint64_t        stateid4;
typedef uint32_t        seqid4;
typedef opaque          utf8string<>;
typedef utf8string      component4;
typedef component4      pathname4<>;
typedef uint64_t        nfs_lockid4;
typedef uint64_t        nfs_cookie4;
typedef utf8string      linktext4;
typedef opaque          sec_oid4<>;
typedef uint32_t        qop4;
typedef uint32_t        mode4;
typedef uint64_t        changeid4;

/*
 * ACCESS: Check access permission
 */
const ACCESS4_READ      = 0x00000001;
const ACCESS4_LOOKUP    = 0x00000002;
const ACCESS4_MODIFY    = 0x00000004;
const ACCESS4_EXTEND    = 0x00000008;
const ACCESS4_DELETE    = 0x00000010;
const ACCESS4_EXECUTE   = 0x00000020;

struct ACCESS4resok {
        uint32_t        supported;
        uint32_t        access;
};

union ACCESS4res switch (nfs4_status status) {
 case NFS4_STATUS_OK:
         ACCESS4resok   resok4;
 default:
         void;
};

END_XDR_DATA;