Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 610 insertions, 0 deletions

diff --git a/man3/xdr.3 b/man3/xdr.3
new file mode 100644
index 0000000..a3f9a02
--- /dev/null
+++ b/man3/xdr.3
@@ -0,0 +1,610 @@
+'\" t
+.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
+.\"
+.\" %%%LICENSE_START(BSD_ONELINE_CDROM)
+.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
+.\" %%%LICENSE_END
+.\"
+.\" @(#)xdr.3n	2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
+.\"
+.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
+.\"
+.TH xdr 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+xdr \- library routines for external data representation
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS AND DESCRIPTION
+These routines allow C programmers to describe
+arbitrary data structures in a machine-independent fashion.
+Data for remote procedure calls are transmitted using these
+routines.
+.PP
+The prototypes below are declared in
+.I <rpc/xdr.h>
+and make use of the following types:
+.PP
+.RS 4
+.EX
+.BI "typedef int " bool_t ;
+.PP
+.BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *,...);"
+.EE
+.RE
+.PP
+For the declaration of the
+.I XDR
+type, see
+.IR <rpc/xdr.h> .
+.PP
+.nf
+.BI "bool_t xdr_array(XDR *" xdrs ", char **" arrp ", unsigned int *" sizep ,
+.BI "                 unsigned int " maxsize ", unsigned int " elsize ,
+.BI "                 xdrproc_t " elproc );
+.fi
+.IP
+A filter primitive that translates between variable-length arrays
+and their corresponding external representations.
+The argument
+.I arrp
+is the address of the pointer to the array, while
+.I sizep
+is the address of the element count of the array;
+this element count cannot exceed
+.IR maxsize .
+The argument
+.I elsize
+is the
+.I sizeof
+each of the array's elements, and
+.I elproc
+is an XDR filter that translates between
+the array elements' C form, and their external
+representation.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_bool(XDR *" xdrs ", bool_t *" bp );
+.fi
+.IP
+A filter primitive that translates between booleans (C
+integers)
+and their external representations.
+When encoding data, this
+filter produces values of either one or zero.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_bytes(XDR *" xdrs ", char **" sp ", unsigned int *" sizep ,
+.BI "                 unsigned int " maxsize );
+.fi
+.IP
+A filter primitive that translates between counted byte
+strings and their external representations.
+The argument
+.I sp
+is the address of the string pointer.
+The length of the
+string is located at address
+.IR sizep ;
+strings cannot be longer than
+.IR maxsize .
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_char(XDR *" xdrs ", char *" cp );
+.fi
+.IP
+A filter primitive that translates between C characters
+and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+Note: encoded characters are not packed, and occupy 4 bytes each.
+For arrays of characters, it is worthwhile to
+consider
+.BR xdr_bytes (),
+.BR xdr_opaque (),
+or
+.BR xdr_string ().
+.PP
+.nf
+.BI "void xdr_destroy(XDR *" xdrs );
+.fi
+.IP
+A macro that invokes the destroy routine associated with the XDR stream,
+.IR xdrs .
+Destruction usually involves freeing private data structures
+associated with the stream.
+Using
+.I xdrs
+after invoking
+.BR xdr_destroy ()
+is undefined.
+.PP
+.nf
+.BI "bool_t xdr_double(XDR *" xdrs ", double *" dp );
+.fi
+.IP
+A filter primitive that translates between C
+.I double
+precision numbers and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_enum(XDR *" xdrs ", enum_t *" ep );
+.fi
+.IP
+A filter primitive that translates between C
+.IR enum s
+(actually integers) and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_float(XDR *" xdrs ", float *" fp );
+.fi
+.IP
+A filter primitive that translates between C
+.IR float s
+and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "void xdr_free(xdrproc_t " proc ", char *" objp );
+.fi
+.IP
+Generic freeing routine.
+The first argument is the XDR routine for the object being freed.
+The second argument is a pointer to the object itself.
+Note: the pointer passed to this routine is
+.I not
+freed, but what it points to
+.I is
+freed (recursively).
+.PP
+.nf
+.BI "unsigned int xdr_getpos(XDR *" xdrs );
+.fi
+.IP
+A macro that invokes the get-position routine
+associated with the XDR stream,
+.IR xdrs .
+The routine returns an unsigned integer,
+which indicates the position of the XDR byte stream.
+A desirable feature of XDR
+streams is that simple arithmetic works with this number,
+although the XDR stream instances need not guarantee this.
+.PP
+.nf
+.BI "long *xdr_inline(XDR *" xdrs ", int " len );
+.fi
+.IP
+A macro that invokes the inline routine associated with the XDR stream,
+.IR xdrs .
+The routine returns a pointer
+to a contiguous piece of the stream's buffer;
+.I len
+is the byte length of the desired buffer.
+Note: pointer is cast to
+.IR "long\ *" .
+.IP
+Warning:
+.BR xdr_inline ()
+may return NULL (0)
+if it cannot allocate a contiguous piece of a buffer.
+Therefore the behavior may vary among stream instances;
+it exists for the sake of efficiency.
+.PP
+.nf
+.BI "bool_t xdr_int(XDR *" xdrs ", int *" ip );
+.fi
+.IP
+A filter primitive that translates between C integers
+and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_long(XDR *" xdrs ", long *" lp );
+.fi
+.IP
+A filter primitive that translates between C
+.I long
+integers and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "void xdrmem_create(XDR *" xdrs ", char *" addr ", unsigned int " size ,
+.BI "                   enum xdr_op " op );
+.fi
+.IP
+This routine initializes the XDR stream object pointed to by
+.IR xdrs .
+The stream's data is written to, or read from,
+a chunk of memory at location
+.I addr
+whose length is no more than
+.I size
+bytes long.
+The
+.I op
+determines the direction of the XDR stream (either
+.BR XDR_ENCODE ,
+.BR XDR_DECODE ,
+or
+.BR XDR_FREE ).
+.PP
+.nf
+.BI "bool_t xdr_opaque(XDR *" xdrs ", char *" cp ", unsigned int " cnt );
+.fi
+.IP
+A filter primitive that translates between fixed size opaque data
+and its external representation.
+The argument
+.I cp
+is the address of the opaque object, and
+.I cnt
+is its size in bytes.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_pointer(XDR *" xdrs ", char **" objpp ,
+.BI "                   unsigned int " objsize ", xdrproc_t " xdrobj );
+.fi
+.IP
+Like
+.BR xdr_reference ()
+except that it serializes null pointers, whereas
+.BR xdr_reference ()
+does not.
+Thus,
+.BR xdr_pointer ()
+can represent
+recursive data structures, such as binary trees or
+linked lists.
+.PP
+.nf
+.BI "void xdrrec_create(XDR *" xdrs ", unsigned int " sendsize ,
+.BI "                   unsigned int " recvsize ", char *" handle ,
+.BI "                   int (*" readit ")(char *, char *, int),"
+.BI "                   int (*" writeit ")(char *, char *, int));"
+.fi
+.IP
+This routine initializes the XDR stream object pointed to by
+.IR xdrs .
+The stream's data is written to a buffer of size
+.IR sendsize ;
+a value of zero indicates the system should use a suitable default.
+The stream's data is read from a buffer of size
+.IR recvsize ;
+it too can be set to a suitable default by passing a zero value.
+When a stream's output buffer is full,
+.I writeit
+is called.
+Similarly, when a stream's input buffer is empty,
+.I readit
+is called.
+The behavior of these two routines is similar to
+the system calls
+.BR read (2)
+and
+.BR write (2),
+except that
+.I handle
+is passed to the former routines as the first argument.
+Note: the XDR stream's
+.I op
+field must be set by the caller.
+.IP
+Warning: to read from an XDR stream created by this API,
+you'll need to call
+.BR xdrrec_skiprecord ()
+first before calling any other XDR APIs.
+This inserts additional bytes in the stream to provide
+record boundary information.
+Also, XDR streams created with different
+.B xdr*_create
+APIs are not compatible for the same reason.
+.PP
+.nf
+.BI "bool_t xdrrec_endofrecord(XDR *" xdrs ", int " sendnow );
+.fi
+.IP
+This routine can be invoked only on streams created by
+.BR xdrrec_create ().
+The data in the output buffer is marked as a completed record,
+and the output buffer is optionally written out if
+.I sendnow
+is nonzero.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdrrec_eof(XDR *" xdrs );
+.fi
+.IP
+This routine can be invoked only on streams created by
+.BR xdrrec_create ().
+After consuming the rest of the current record in the stream,
+this routine returns one if the stream has no more input,
+zero otherwise.
+.PP
+.nf
+.BI "bool_t xdrrec_skiprecord(XDR *" xdrs );
+.fi
+.IP
+This routine can be invoked only on
+streams created by
+.BR xdrrec_create ().
+It tells the XDR implementation that the rest of the current record
+in the stream's input buffer should be discarded.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_reference(XDR *" xdrs ", char **" pp ", unsigned int " size ,
+.BI "                     xdrproc_t " proc );
+.fi
+.IP
+A primitive that provides pointer chasing within structures.
+The argument
+.I pp
+is the address of the pointer;
+.I size
+is the
+.I sizeof
+the structure that
+.I *pp
+points to; and
+.I proc
+is an XDR procedure that filters the structure
+between its C form and its external representation.
+This routine returns one if it succeeds, zero otherwise.
+.IP
+Warning: this routine does not understand null pointers.
+Use
+.BR xdr_pointer ()
+instead.
+.PP
+.nf
+.BI "xdr_setpos(XDR *" xdrs ", unsigned int " pos );
+.fi
+.IP
+A macro that invokes the set position routine associated with
+the XDR stream
+.IR xdrs .
+The argument
+.I pos
+is a position value obtained from
+.BR xdr_getpos ().
+This routine returns one if the XDR stream could be repositioned,
+and zero otherwise.
+.IP
+Warning: it is difficult to reposition some types of XDR
+streams, so this routine may fail with one
+type of stream and succeed with another.
+.PP
+.nf
+.BI "bool_t xdr_short(XDR *" xdrs ", short *" sp );
+.fi
+.IP
+A filter primitive that translates between C
+.I short
+integers and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "void xdrstdio_create(XDR *" xdrs ", FILE *" file ", enum xdr_op " op );
+.fi
+.IP
+This routine initializes the XDR stream object pointed to by
+.IR xdrs .
+The XDR stream data is written to, or read from, the
+.I stdio
+stream
+.IR file .
+The argument
+.I op
+determines the direction of the XDR stream (either
+.BR XDR_ENCODE ,
+.BR XDR_DECODE ,
+or
+.BR XDR_FREE ).
+.IP
+Warning: the destroy routine associated with such XDR streams calls
+.BR fflush (3)
+on the
+.I file
+stream, but never
+.BR fclose (3).
+.PP
+.nf
+.BI "bool_t xdr_string(XDR *" xdrs ", char **" sp ", unsigned int " maxsize );
+.fi
+.IP
+A filter primitive that translates between C strings and
+their corresponding external representations.
+Strings cannot be longer than
+.IR maxsize .
+Note:
+.I sp
+is the address of the string's pointer.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_u_char(XDR *" xdrs ", unsigned char *" ucp );
+.fi
+.IP
+A filter primitive that translates between
+.I unsigned
+C characters and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned int *" up );
+.fi
+.IP
+A filter primitive that translates between C
+.I unsigned
+integers and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_u_long(XDR *" xdrs ", unsigned long *" ulp );
+.fi
+.IP
+A filter primitive that translates between C
+.I "unsigned long"
+integers and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_u_short(XDR *" xdrs ", unsigned short *" usp );
+.fi
+.IP
+A filter primitive that translates between C
+.I "unsigned short"
+integers and their external representations.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_union(XDR *" xdrs ", enum_t *" dscmp ", char *" unp ,
+.BI "                 const struct xdr_discrim *" choices ,
+.BI "                 xdrproc_t " defaultarm ");     /* may equal NULL */"
+.fi
+.IP
+A filter primitive that translates between a discriminated C
+.I union
+and its corresponding external representation.
+It first
+translates the discriminant of the union located at
+.IR dscmp .
+This discriminant is always an
+.IR enum_t .
+Next the union located at
+.I unp
+is translated.
+The argument
+.I choices
+is a pointer to an array of
+.BR xdr_discrim ()
+structures.
+Each structure contains an ordered pair of
+.RI [ value , proc ].
+If the union's discriminant is equal to the associated
+.IR value ,
+then the
+.I proc
+is called to translate the union.
+The end of the
+.BR xdr_discrim ()
+structure array is denoted by a routine of value NULL.
+If the discriminant is not found in the
+.I choices
+array, then the
+.I defaultarm
+procedure is called (if it is not NULL).
+Returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.BI "bool_t xdr_vector(XDR *" xdrs ", char *" arrp ", unsigned int " size ,
+.BI "                  unsigned int " elsize ", xdrproc_t " elproc );
+.fi
+.IP
+A filter primitive that translates between fixed-length arrays
+and their corresponding external representations.
+The argument
+.I arrp
+is the address of the pointer to the array, while
+.I size
+is the element count of the array.
+The argument
+.I elsize
+is the
+.I sizeof
+each of the array's elements, and
+.I elproc
+is an XDR filter that translates between
+the array elements' C form, and their external
+representation.
+This routine returns one if it succeeds, zero otherwise.
+.PP
+.nf
+.B bool_t xdr_void(void);
+.fi
+.IP
+This routine always returns one.
+It may be passed to RPC routines that require a function argument,
+where nothing is to be done.
+.PP
+.nf
+.BI "bool_t xdr_wrapstring(XDR *" xdrs ", char **" sp );
+.fi
+.IP
+A primitive that calls
+.B "xdr_string(xdrs, sp,MAXUN.UNSIGNED );"
+where
+.B MAXUN.UNSIGNED
+is the maximum value of an unsigned integer.
+.BR xdr_wrapstring ()
+is handy because the RPC package passes a maximum of two XDR
+routines as arguments, and
+.BR xdr_string (),
+one of the most frequently used primitives, requires three.
+Returns one if it succeeds, zero otherwise.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR xdr_array (),
+.BR xdr_bool (),
+.BR xdr_bytes (),
+.BR xdr_char (),
+.BR xdr_destroy (),
+.BR xdr_double (),
+.BR xdr_enum (),
+.BR xdr_float (),
+.BR xdr_free (),
+.BR xdr_getpos (),
+.BR xdr_inline (),
+.BR xdr_int (),
+.BR xdr_long (),
+.BR xdrmem_create (),
+.BR xdr_opaque (),
+.BR xdr_pointer (),
+.BR xdrrec_create (),
+.BR xdrrec_eof (),
+.BR xdrrec_endofrecord (),
+.BR xdrrec_skiprecord (),
+.BR xdr_reference (),
+.BR xdr_setpos (),
+.BR xdr_short (),
+.BR xdrstdio_create (),
+.BR xdr_string (),
+.BR xdr_u_char (),
+.BR xdr_u_int (),
+.BR xdr_u_long (),
+.BR xdr_u_short (),
+.BR xdr_union (),
+.BR xdr_vector (),
+.BR xdr_void (),
+.BR xdr_wrapstring ()
+T}	Thread safety	MT-Safe
+.TE
+.sp 1
+.SH SEE ALSO
+.BR rpc (3)
+.PP
+The following manuals:
+.RS
+eXternal Data Representation Standard: Protocol Specification
+.br
+eXternal Data Representation: Sun Technical Notes
+.br
+.IR "XDR: External Data Representation Standard" ,
+RFC\ 1014, Sun Microsystems, Inc.,
+USC-ISI.
+.RE