rpc_soc.3t

.\" @(#)rpc.3n	2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI
.\" $NetBSD: rpc_soc.3,v 1.2 2000/06/07 13:39:43 simonb Exp $
.\" $FreeBSD: src/lib/libc/rpc/rpc_soc.3,v 1.12 2003/02/06 11:04:47 charnier Exp $
.\"
.Dd February 16, 1988
.Dt RPC_SOC 3
.Os
.Sh NAME
.Nm rpc_soc ,
.Nm auth_destroy ,
.Nm authnone_create ,
.Nm authunix_create ,
.Nm authunix_create_default ,
.Nm clnt_call ,
.Nm clnt_control ,
.Nm clnt_create ,
.Nm clnt_destroy ,
.Nm clnt_freeres ,
.Nm clnt_perrno ,
.Nm clnt_sperrno ,
.Nm rpc_perror ,
.Nm rpc_sperror ,
.Nm SVC_DESTROY ,
.Nm svc_sendreply ,
.Nm svcerr_auth ,
.Nm svcerr_decode ,
.Nm svcerr_noproc ,
.Nm svcerr_noprog ,
.Nm svcerr_progvers ,
.Nm svcerr_systemerr ,
.Nm svcerr_weakauth ,
.Nm xdr_accepted_reply ,
.Nm xdr_authunix_parms ,
.Nm xdr_callhdr ,
.Nm xdr_callmsg ,
.Nm xdr_opaque_auth ,
.Nm xdr_pmap ,
.Nm xdr_pmaplist ,
.Nm xdr_rejected_reply ,
.Nm xdr_replymsg
.Nd "library routines for remote procedure calls"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/rpc.h
.Pp
See
.Sx DESCRIPTION
for function declarations.
.Sh DESCRIPTION
.Bf -symbolic
The
.Fn svc_*
and
.Fn clnt_*
functions described in this page are the old, TS-RPC
interface to the XDR and RPC library, and exist for backward compatibility.
The new interface is described in the pages
referenced from
.Xr rpc 3 .
.Ef
.Pp
These routines allow C programs to make procedure
calls on other machines across the network.
First, the client calls a procedure to send a
data packet to the server.
Upon receipt of the packet, the server calls a dispatch routine
to perform the requested service, and then sends back a
reply.
Finally, the procedure call returns to the client.
.Pp
Routines that are used for Secure
.Tn RPC ( DES
authentication) are described in
.Xr rpc_secure 3 .
Secure
.Tn RPC
can be used only if
.Tn DES
encryption is available.
.Bl -tag -width indent -compact
.Pp
.It Xo
.Ft void
.Xc
.It Xo
.Fn auth_destroy "AUTH *auth"
.Xc
.Pp
A macro that destroys the authentication information associated with
.Fa auth .
Destruction usually involves deallocation of private data
structures.
The use of
.Fa auth
is undefined after calling
.Fn auth_destroy .
.Pp
.It Xo
.Ft "AUTH *"
.Xc
.It Xo
.Fn authnone_create
.Xc
.Pp
Create and return an
.Tn RPC
authentication handle that passes nonusable authentication
information with each remote procedure call.
This is the
default authentication used by
.Tn RPC .
.Pp
.It Xo
.Ft "AUTH *"
.Xc
.It Xo
.Fn authunix_create "char *host" "int uid" "int gid" "int len" "int *aup_gids"
.Xc
.Pp
Create and return an
.Tn RPC
authentication handle that contains
.Ux
authentication information.
The
.Fa host
argument
is the name of the machine on which the information was
created;
.Fa uid
is the user's user ID;
.Fa gid
is the user's current group ID;
.Fa len
and
.Fa aup_gids
refer to a counted array of groups to which the user belongs.
It is easy to impersonate a user.
.Pp
.It Xo
.Ft "AUTH *"
.Xc
.It Xo
.Fn authunix_create_default
.Xc
.Pp
Calls
.Fn authunix_create
with the appropriate arguments.
.Pp
.It Xo
.Ft "enum clnt_stat"
.Xc
.It Xo
.Fo clnt_call
.Fa "CLIENT *clnt"
.Fa "u_long procnum"
.Fa "xdrproc_t inproc"
.Fa "char *in"
.Fa "xdrproc_t outproc"
.Fa "char *out"
.Fa "struct timeval tout"
.Fc
.Xc
.Pp
A macro that calls the remote procedure
.Fa procnum
associated with the client handle,
.Fa clnt ,
which is obtained with an
.Tn RPC
client creation routine such as
.Fn clnt_create .
The
.Fa in
argument
is the address of the procedure's argument(s), and
.Fa out
is the address of where to place the result(s);
.Fa inproc
is used to encode the procedure's arguments, and
.Fa outproc
is used to decode the procedure's results;
.Fa tout
is the time allowed for results to come back.
.Pp
.It Xo
.Ft void
.Fn CLNT_DESTROY "CLIENT *clnt"
.Xc
.Pp
A macro that destroys the client's
.Tn RPC
handle.
Destruction usually involves deallocation
of private data structures, including
.Fa clnt
itself.
Use of
.Fa clnt
is undefined after calling
.Fn CLNT_DESTROY .
If the
.Tn RPC
library opened the associated socket, it will close it also.
Otherwise, the socket remains open.
.Pp
.It Xo
.Ft CLIENT *
.Xc
.It Xo
.Fn clnt_create "char *host" "u_long prog" "u_long vers" "char *proto"
.Xc
.Pp
Generic client creation routine.
The
.Fa host
argument
identifies the name of the remote host where the server
is located.
The
.Fa proto
argument
indicates which kind of transport protocol to use.
The
currently supported values for this field are
.Qq Li udp
and
.Qq Li tcp .
Default timeouts are set, but can be modified using
.Fn clnt_control .
.Pp
Warning: Using
.Tn UDP
has its shortcomings.
Since
.Tn UDP Ns \-based
.Tn RPC
messages can only hold up to 8 Kbytes of encoded data,
this transport cannot be used for procedures that take
large arguments or return huge results.
.Pp
.It Xo
.Ft bool_t
.Xc
.It Xo
.Fn clnt_control "CLIENT *cl" "u_int req" "char *info"
.Xc
.Pp
A macro used to change or retrieve various information
about a client object.
The
.Fa req
argument
indicates the type of operation, and
.Fa info
is a pointer to the information.
For both
.Tn UDP
and
.Tn TCP ,
the supported values of
.Fa req
and their argument types and what they do are:
.Bl -column "CLGET_SERVER_ADDR" "struct sockaddr_in"
.It Dv CLGET_SERVER_ADDR Ta Xo
.Vt "struct sockaddr_in" Ta "get server's address"
.Xc
.El
.Pp
.It Xo
.Ft bool_t
.Fn clnt_freeres "CLIENT *clnt" "xdrproc_t outproc" "char *out"
.Xc
.Pp
A macro that frees any data allocated by the
.Tn RPC/XDR
system when it decoded the results of an
.Tn RPC
call.
The
.Fa out
argument
is the address of the results, and
.Fa outproc
is the
.Tn XDR
routine describing the results.
This routine returns one if the results were successfully
freed,
and zero otherwise.
.Pp
.It Xo
.Ft void
.Xc
.It Xo
.Fn clnt_perrno "enum clnt_stat stat"
.Xc
.Pp
Print a message to standard error corresponding
to the condition indicated by
.Fa stat .
A newline is appended at the end of the message.
.Pp
.It Xo
.Ft "char *"
.Xc
.It Xo
.Fn clnt_sperrno "enum clnt_stat stat"
.Xc
.Pp
Take the same arguments as
.Fn clnt_perrno ,
but instead of sending a message to the standard error
indicating why an
.Tn RPC
call failed, return a pointer to a string which contains
the message.
.Pp
The
.Fn clnt_sperrno
function
is used instead of
.Fn clnt_perrno
if the program does not have a standard error (as a program
running as a server quite likely does not), or if the
programmer
does not want the message to be output with
.Fn printf ,
or if a message format different from that supported by
.Fn clnt_perrno
is to be used.
.Pp
Note:
.Fn clnt_sperrno
returns pointer to static data, but the
result will not get overwritten on each call.
.Pp
.It Xo
.Ft void
.Fn rpc_perror "const struct rpc_err *e" "const char *s"
.Xc
.Pp
Print a message to standard error indicating why an
.Tn RPC
call failed;
.Tn struct rpc_err
.Fa e
is the error value.
The message is prepended with string
.Fa s
and a colon.
A newline is appended at the end of the message.
.Pp
.It Xo
.Ft "char *"
.Xc
.It Xo
.Fn rpc_sperror "const struct rpc_err *e" "const char *s"
.Xc
.Pp
Like
.Fn rpc_perror ,
except that (like
.Fn clnt_sperrno )
it returns a string instead of printing to standard error.
This string must be freed after use.
.Pp
.It Xo
.Ft bool_t
.Fn SVC_DESTROY "SVCXPRT * xprt"
.Xc
.Pp
A macro that destroys the
.Tn RPC
service transport handle,
.Fa xprt .
Destruction usually involves deallocation
of private data structures, including
.Fa xprt
itself.
Use of
.Fa xprt
is undefined after calling this routine.
.Pp
.It Xo
.Ft enum xprt_stat
.Fn svc_sendreply "struct svc_req *request"
.Xc
.Pp
Called by an
.Tn RPC
service's dispatch routine to send the results of a
remote procedure call.
The
.Fa request
argument
is the request.
Its
.Tn struct rpc_msg
.Fa ar_results
fields must be set:
.Fa proc
is the
.Tn XDR
routine which is used to encode the results; and
.Fa where
is the address of the results.
This routine returns
.Dv XPRT_IDLE (0)
for success,
.Dv XPRT_DIED
or greater otherwise.
.Pp
.It Xo
.Ft enum xprt_stat
.Xc
.It Xo
.Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why"
.Xc
.Pp
Called by a service dispatch routine that refuses to perform
a remote procedure call due to an authentication error.
.Pp
.It Xo
.Ft enum xprt_stat
.Xc
.It Xo
.Fn svcerr_decode "SVCXPRT *xprt"
.Xc
.Pp
Called by a service dispatch routine that cannot successfully
decode its arguments.
.Pp
.It Xo
.Ft enum xprt_stat
.Xc
.It Xo
.Fn svcerr_noproc "SVCXPRT *xprt"
.Xc
.Pp
Called by a service dispatch routine that does not implement
the procedure number that the caller requests.
.Pp
.It Xo
.Ft enum xprt_stat
.Xc
.It Xo
.Fn svcerr_noprog "SVCXPRT *xprt"
.Xc
.Pp
Called when the desired program is not registered with the
.Tn RPC
package.
Service implementors usually do not need this routine.
.Pp
.It Xo
.Ft enum xprt_stat
.Xc
.It Xo
.Fn svcerr_progvers "SVCXPRT *xprt" "u_long low_vers" "u_long high_vers"
.Xc
.Pp
Called when the desired version of a program is not registered
with the
.Tn RPC
package.
Service implementors usually do not need this routine.
.Pp
.It Xo
.Ft enum xprt_stat
.Xc
.It Xo
.Fn svcerr_systemerr "SVCXPRT *xprt"
.Xc
.Pp
Called by a service dispatch routine when it detects a system
error
not covered by any particular protocol.
For example, if a service can no longer allocate storage,
it may call this routine.
.Pp
.It Xo
.Ft enum xprt_stat
.Xc
.It Xo
.Fn svcerr_weakauth "SVCXPRT *xprt"
.Xc
.Pp
Called by a service dispatch routine that refuses to perform
a remote procedure call due to insufficient
authentication arguments.
The routine calls
.Fn svcerr_auth xprt AUTH_TOOWEAK .
.Pp
.It Xo
.Ft bool_t
.Fn xdr_authunix_parms "XDR *xdrs" "struct authunix_parms *aupp"
.Xc
.Pp
Used for describing
.Ux
credentials.
This routine is useful for users
who wish to generate these credentials without using the
.Tn RPC
authentication package.
.Pp
.It Xo
.Ft void
.Xc
.It Xo
.Ft bool_t
.Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr"
.Xc
.Pp
Used for describing
.Tn RPC
call header messages.
This routine is useful for users who wish to generate
.Tn RPC Ns \-style
messages without using the
.Tn RPC
package.
.Pp
.It Xo
.Ft bool_t
.Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg"
.Xc
.Pp
Used for describing
.Tn RPC
call messages.
This routine is useful for users who wish to generate
.Tn RPC Ns \-style
messages without using the
.Tn RPC
package.
.Pp
.It Xo
.Ft bool_t
.Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap"
.Xc
.Pp
Used for describing
.Tn RPC
authentication information messages.
This routine is useful for users who wish to generate
.Tn RPC Ns \-style
messages without using the
.Tn RPC
package.
.Pp
.It Xo
.Vt struct pmap ;
.Xc
.It Xo
.Ft bool_t
.Fn xdr_pmap "XDR *xdrs" "struct pmap *regs"
.Xc
.Pp
Used for describing arguments to various
.Xr rpcbind 8
procedures, externally.
This routine is useful for users who wish to generate
these arguments without using the
.Fn pmap_*
interface.
.Pp
.It Xo
.Ft bool_t
.Fn xdr_pmaplist "XDR *xdrs" "struct pmaplist **rp"
.Xc
.Pp
Used for describing a list of port mappings, externally.
This routine is useful for users who wish to generate
these arguments without using the
.Fn pmap_*
interface.
.Pp
.It Xo
.Ft bool_t
.Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr"
.Xc
.Pp
Used for describing
.Tn RPC
reply messages.
This routine is useful for users who wish to generate
.Tn RPC Ns \-style
messages without using the
.Tn RPC
package.
.Pp
.It Xo
.Ft bool_t
.Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg"
.Xc
.Pp
Used for describing
.Tn RPC
reply messages.
This routine is useful for users who wish to generate
.Tn RPC
style messages without using the
.Tn RPC
package.
.El
.Sh SEE ALSO
.Xr rpc_secure 3 ,
.Xr xdr 3
.Rs
.%T "Remote Procedure Calls: Protocol Specification"
.Re
.Rs
.%T "Remote Procedure Call Programming Guide"
.Re
.Rs
.%T "rpcgen Programming Guide"
.Re
.Rs
.%T "RPC: Remote Procedure Call Protocol Specification"
.%O RFC1050
.%Q "Sun Microsystems, Inc., USC-ISI"
.Re