261 lines
6.6 KiB
Groff
261 lines
6.6 KiB
Groff
.\" @(#)rpc_svc_calls.3n 1.28 93/05/10 SMI; from SVr4
|
|
.\" Copyright 1989 AT&T
|
|
.\" @(#)rpc_svc_calls 1.5 89/07/25 SMI;
|
|
.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
|
|
.\" $NetBSD: rpc_svc_calls.3,v 1.4 2002/02/07 07:00:23 ross Exp $
|
|
.Dd May 3, 1993
|
|
.Dt RPC_SVC_CALLS 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm svc_dg_enablecache ,
|
|
.Nm svc_exit ,
|
|
.Nm svc_fdset ,
|
|
.Nm svc_freeargs ,
|
|
.Nm svc_getargs ,
|
|
.Nm svc_getreq_common ,
|
|
.Nm svc_getreq_poll ,
|
|
.Nm svc_getreqset ,
|
|
.Nm svc_getrpccaller ,
|
|
.Nm svc_pollset ,
|
|
.Nm svc_run ,
|
|
.Nm svc_sendreply
|
|
.Nd library routines for RPC servers
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.Fd #include \*[Lt]rpc/rpc.h\*[Gt]
|
|
.Ft int
|
|
.Fn svc_dg_enablecache "SVCXPRT *xprt" "const unsigned cache_size"
|
|
.Ft void
|
|
.Fn svc_exit "void"
|
|
.Ft bool_t
|
|
.Fn svc_freeargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in"
|
|
.Ft bool_t
|
|
.Fn svc_getargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in"
|
|
.Ft void
|
|
.Fn svc_getreq_common "const int fd"
|
|
.Ft void
|
|
.Fn svc_getreq_poll "struct pollfd *pfdp" "const int pollretval"
|
|
.Ft void
|
|
.Fn svc_getreqset "fd_set * rdfds"
|
|
.Ft "struct netbuf *"
|
|
.Fn svc_getrpccaller "const SVCXPRT *xprt"
|
|
.Ft "struct sockcred *"
|
|
.Fn __svc_getcallercreds "const SVCXPRT *xprt"
|
|
.Vt struct pollfd svc_pollset[FD_SETSIZE];
|
|
.Ft void
|
|
.Fn svc_run "void"
|
|
.Ft bool_t
|
|
.Fn svc_sendreply "const SVCXPRT *xprt" "const xdrproc_t outproc" "const caddr_t *out"
|
|
.Sh DESCRIPTION
|
|
These routines are part of the
|
|
RPC
|
|
library which allows C language programs to make procedure
|
|
calls on other machines across the network.
|
|
.Pp
|
|
These routines are associated with the server side of the
|
|
RPC mechanism.
|
|
Some of them are called by the server side dispatch function,
|
|
while others
|
|
(such as
|
|
.Fn svc_run )
|
|
are called when the server is initiated.
|
|
.\" .Pp
|
|
.\" In the current implementation, the service transport handle,
|
|
.\" .Dv SVCXPRT ,
|
|
.\" contains a single data area for decoding arguments and encoding results.
|
|
.\" Therefore, this structure cannot be freely shared between threads that call
|
|
.\" functions that do this. Routines on this page that are affected by this
|
|
.\" restriction are marked as unsafe for MT applications.
|
|
.Sh ROUTINES
|
|
See
|
|
.Xr rpc 3
|
|
for the definition of the
|
|
.Dv SVCXPRT
|
|
data structure.
|
|
.Pp
|
|
.Bl -tag -width __svc_getcallercreds()
|
|
.It Fn svc_dg_enablecache
|
|
This function allocates a duplicate request cache for the
|
|
service endpoint
|
|
.Fa xprt ,
|
|
large enough to hold
|
|
.Fa cache_size
|
|
entries.
|
|
Once enabled, there is no way to disable caching.
|
|
This routine returns 0 if space necessary for a cache of the given size
|
|
was successfully allocated, and 1 otherwise.
|
|
.It Fn svc_exit
|
|
This function when called by any of the RPC server procedure or
|
|
otherwise, causes
|
|
.Fn svc_run
|
|
to return.
|
|
.Pp
|
|
As currently implemented,
|
|
.Fn svc_exit
|
|
zeroes the
|
|
.Dv svc_fdset
|
|
global variable. If RPC server activity is to be resumed,
|
|
services must be reregistered with the RPC library
|
|
either through one of the
|
|
.Fn rpc_svc_create
|
|
functions, or using
|
|
.Fn xprt_register .
|
|
.Fn svc_exit
|
|
has global scope and ends all RPC server activity.
|
|
.Ft "fd_set svc_fdset"
|
|
A global variable reflecting the
|
|
RPC server's read file descriptor bit mask; it is suitable as a parameter
|
|
to the
|
|
.Xr select 2
|
|
system call.
|
|
This is only of interest
|
|
if service implementors do not call
|
|
.Fn svc_run ,
|
|
but rather do their own asynchronous event processing.
|
|
This variable is read-only (do not pass its address to
|
|
.Xr select 2 ! ) ,
|
|
yet it may change after calls to
|
|
.Fn svc_getreqset
|
|
or any creation routines.
|
|
.Pp
|
|
.It Fn svc_freeargs
|
|
A function macro that frees any data allocated by the
|
|
RPC/XDR system when it decoded the arguments to a service procedure
|
|
using
|
|
.Fn svc_getargs .
|
|
This routine returns
|
|
.Dv TRUE
|
|
if the results were successfully
|
|
freed, and
|
|
.Dv FALSE
|
|
otherwise.
|
|
.Pp
|
|
.It Fn svc_getargs
|
|
A function macro that decodes the arguments of an
|
|
RPC request associated with the RPC
|
|
service transport handle
|
|
.Fa xprt .
|
|
The parameter
|
|
.Fa in
|
|
is the address where the arguments will be placed;
|
|
.Fa inproc
|
|
is the XDR
|
|
routine used to decode the arguments.
|
|
This routine returns
|
|
.Dv TRUE
|
|
if decoding succeeds, and
|
|
.Dv FALSE
|
|
otherwise.
|
|
.It Fn svc_getreq_common
|
|
This routine is called to handle a request on the given
|
|
file descriptor.
|
|
.Pp
|
|
.It Fn svc_getreq_poll
|
|
This routine is only of interest if a service implementor
|
|
does not call
|
|
.Fn svc_run ,
|
|
but instead implements custom asynchronous event processing.
|
|
It is called when
|
|
.Xr poll 2
|
|
has determined that an RPC request has arrived on some RPC
|
|
file descriptors;
|
|
.Fn pollretval
|
|
is the return value from
|
|
.Xr poll 2
|
|
and
|
|
.Fa pfdp
|
|
is the array of
|
|
.Fa pollfd
|
|
structures on which the
|
|
.Xr poll 2
|
|
was done.
|
|
It is assumed to be an array large enough to
|
|
contain the maximal number of descriptors allowed.
|
|
.Pp
|
|
.Fn svc_getreqset
|
|
This routine is only of interest if a service implementor
|
|
does not call
|
|
.Fn svc_run ,
|
|
but instead implements custom asynchronous event processing.
|
|
It is called when
|
|
.Xr poll 2
|
|
has determined that an RPC
|
|
request has arrived on some RPC file descriptors;
|
|
.Fa rdfds
|
|
is the resultant read file descriptor bit mask.
|
|
The routine returns when all file descriptors
|
|
associated with the value of
|
|
.Fa rdfds
|
|
have been serviced.
|
|
.Pp
|
|
.It Fn svc_getrpccaller
|
|
The approved way of getting the network address of the caller
|
|
of a procedure associated with the
|
|
RPC service transport handle
|
|
.Fa xprt .
|
|
.Pp
|
|
.It Fn __svc_getcallercreds
|
|
.Bf Warning: this macro is specific to
|
|
.Nx
|
|
and thus not portable.
|
|
This macro returns a pointer to a sockcred structure, defined in
|
|
.Fd \*[Lt]sys/socket.h\*[Gt] ,
|
|
identifying the calling client. This only works if the client is
|
|
calling the server over an
|
|
.Dv AF_LOCAL
|
|
socket.
|
|
.It Fa struct pollfd svc_pollset[FD_SETSIZE];
|
|
.Va svc_pollset
|
|
is an array of
|
|
.Vt pollfd
|
|
structures derived from
|
|
.Va svc_fdset[] .
|
|
It is suitable as a parameter to the
|
|
.Xr poll 2
|
|
system call.
|
|
The derivation of
|
|
.Va svc_pollset
|
|
from
|
|
.Va svc_fdset
|
|
is made in the current implementation in
|
|
.Fn svc_run .
|
|
Service implementors who do not call
|
|
.Fn svc_run
|
|
and who wish to use this array must perform this derivation themselves.
|
|
.Pp
|
|
.It Fn svc_run
|
|
.IP
|
|
This routine never returns.
|
|
It waits for RPC
|
|
requests to arrive, and calls the appropriate service
|
|
procedure using
|
|
.Fn svc_getreq_poll
|
|
when one arrives.
|
|
This procedure is usually waiting for the
|
|
.Xr poll 2
|
|
system call to return.
|
|
.Pp
|
|
.It Fn svc_sendreply
|
|
Called by an RPC service's dispatch routine to send the results of a
|
|
remote procedure call. The parameter
|
|
.Fa xprt
|
|
is the request's associated transport handle;
|
|
.Fa outproc
|
|
is the XDR
|
|
routine which is used to encode the results; and
|
|
.Fa out
|
|
is the address of the results.
|
|
This routine returns
|
|
.Dv TRUE
|
|
if it succeeds,
|
|
.Dv FALSE
|
|
otherwise.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr poll 2 ,
|
|
.Xr rpc 3 ,
|
|
.Xr rpc_svc_create 3 ,
|
|
.Xr rpc_svc_err 3 ,
|
|
.Xr rpc_svc_reg 3
|