usr/src/man/man3nsl/xdr_create.3nsl

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (C) 2000, Sun Microsystems, Inc. All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH XDR_CREATE 3NSL "Sep 26, 2000"
   8 .SH NAME
   9 xdr_create, xdr_destroy, xdrmem_create, xdrrec_create, xdrstdio_create \-
  10 library routines for external data representation stream creation
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <rpc/xdr.h>
  15
  16 \fBvoid\fR \fBxdr_destroy\fR(\fBXDR *\fR\fIxdrs\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBxdrmem_create\fR(\fBXDR *\fR\fIxdrs\fR, \fBconst caddr_t\fR \fIaddr\fR, \fBconst uint_t\fR \fIsize\fR,
  22      \fBconst enum xdr_op\fR \fIop\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBvoid\fR \fBxdrrec_create\fR(\fBXDR *\fR\fIxdrs\fR, \fBconst uint_t\fR \fIsendsz\fR, \fBconst uint_t\fR \fIrecvsz\fR,
  28      \fBconst caddr_t\fR \fIhandle\fR, \fBconst int (*\fR\fIreadit\fR)const void *\fIread_handle\fR,
  29      char *\fIbuf\fR, const int \fIlen\fR, \fBconst int (*\fR\fIwriteit\fR)
  30      const void *\fIwrite_handle\fR, const char *\fIbuf\fR, const int \fIlen\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBvoid\fR \fBxdrstdio_create\fR(\fBXDR *\fR\fIxdrs\fR, \fBFILE *\fR
  36      \fIfile\fR, \fBconst enum xdr_op\fR \fIop\fR);
  37 .fi
  38
  39 .SH DESCRIPTION
  40 .sp
  41 .LP
  42 The \fBXDR\fR library routines allow C programmers to describe arbitrary data
  43 structures in a machine-independent fashion. Protocols such as remote procedure
  44 calls (RPC) use these routines to describe the format of the data.
  45 .sp
  46 .LP
  47 These routines deal with the creation of  \fBXDR\fR streams, which must be
  48 created before any data can be translated into \fBXDR\fR format.
  49 .SS "Routines"
  50 .sp
  51 .LP
  52 See \fBrpc\fR(3NSL) for the definition of the \fBXDR\fR \fBCLIENT\fR and
  53 \fBSVCXPRT\fR data structures. Any buffers passed to the \fBXDR\fR routines
  54 must be properly aligned. Use \fBmalloc\fR(3C) to allocate these buffers or be
  55 sure that the buffer address is divisible evenly by four.
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fBxdr_destroy()\fR\fR
  60 .ad
  61 .RS 21n
  62 A macro that invokes the destroy routine associated with the \fBXDR\fR stream,
  63 \fIxdrs\fR. Private data structures associated with the stream are freed.
  64 Using \fIxdrs\fR after \fBxdr_destroy()\fR is invoked is undefined.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBxdrmem_create()\fR\fR
  71 .ad
  72 .RS 21n
  73 This routine initializes the \fBXDR\fR stream object pointed to by \fIxdrs\fR.
  74 The stream's data is written to or read from a chunk of memory at location
  75 \fIaddr\fR whose length is no less than \fIsize\fR bytes long.  The \fIop\fR
  76 determines the direction of the \fBXDR\fR stream. The value of \fIop\fR can be
  77 either \fBXDR_ENCODE\fR, \fBXDR_DECODE\fR, or \fBXDR_FREE\fR.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBxdrrec_create()\fR\fR
  84 .ad
  85 .RS 21n
  86 This routine initializes the read-oriented \fBXDR\fR stream object pointed to
  87 by \fIxdrs\fR. The stream's data is written to a buffer of size \fIsendsz\fR. A
  88 value of \fB0\fR indicates the system should use a suitable default.  The
  89 stream's data is read from a buffer of size \fIrecvsz\fR. It too can be set to
  90 a suitable default by passing a \fB0\fR value.  When a stream's output buffer
  91 is full, \fIwriteit\fR is called.  Similarly, when a stream's input buffer is
  92 empty, \fBxdrrec_create()\fR calls \fIreadit\fR. The behavior of these two
  93 routines is similar to the system calls \fBread()\fR and \fBwrite()\fR,  except
  94 that an appropriate handle, \fIread_handle\fR or \fIwrite_handle\fR, is passed
  95 to the former routines as the first parameter instead of a file descriptor. See
  96 \fBread\fR(2) and \fBwrite\fR(2), respectively. The \fBXDR\fR stream's \fIop\fR
  97 field must be set by the caller.
  98 .sp
  99 This \fBXDR\fR stream implements an intermediate record stream. Therefore,
 100 additional bytes in the stream are provided for record boundary information.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBxdrstdio_create()\fR\fR
 107 .ad
 108 .RS 21n
 109 This routine initializes the \fBXDR\fR stream object pointed to by \fIxdrs\fR.
 110 The \fBXDR\fR stream data is written to or read from the standard \fBI/O\fR
 111 stream \fBfile\fR. The parameter \fIop\fR determines the direction of the
 112 \fBXDR\fR stream. The value of \fIop\fR can be either \fBXDR_ENCODE\fR,
 113 \fBXDR_DECODE\fR, or \fBXDR_FREE\fR.
 114 .sp
 115 The destroy routine associated with \fBXDR\fR streams calls \fBfflush()\fR on
 116 the \fIfile\fR stream, but never \fBfclose()\fR. See \fBfclose\fR(3C).
 117 .RE
 118
 119 .sp
 120 .LP
 121 A failure of any of these functions can be detected by first initializing  the
 122 \fIx_ops\fR field in the \fBXDR\fR structure (\fIxdrs\fR-> \fIx_ops\fR) to
 123 \fINULL\fR before calling the  \fBxdr*_create()\fR function.  If the
 124 \fIx_ops\fR field is still  \fINULL,\fR after the return from the
 125 \fBxdr*_create()\fR function, the call has failed.  If the \fIx_ops\fR field
 126 contains some other value, assume that the call has succeeded.
 127 .SH ATTRIBUTES
 128 .sp
 129 .LP
 130 See \fBattributes\fR(5) for descriptions of the following attributes:
 131 .sp
 132
 133 .sp
 134 .TS
 135 box;
 136 c | c
 137 l | l .
 138 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 139 _
 140 MT-Level        MT-Safe
 141 .TE
 142
 143 .SH SEE ALSO
 144 .sp
 145 .LP
 146 \fBread\fR(2), \fBwrite\fR(2), \fBfclose\fR(3C), \fBmalloc\fR(3C),
 147 \fBrpc\fR(3NSL), \fBxdr_admin\fR(3NSL), \fBxdr_complex\fR(3NSL),
 148 \fBxdr_simple\fR(3NSL), \fBattributes\fR(5)