diff options
-rw-r--r-- | lib/libc/rpc/rpc_svc_create.3 | 311 |
1 files changed, 0 insertions, 311 deletions
diff --git a/lib/libc/rpc/rpc_svc_create.3 b/lib/libc/rpc/rpc_svc_create.3 index b9788b2..f2d7b2d 100644 --- a/lib/libc/rpc/rpc_svc_create.3 +++ b/lib/libc/rpc/rpc_svc_create.3 @@ -309,314 +309,3 @@ service. .Xr rpc_svc_err 3 , .Xr rpc_svc_reg 3 , .Xr rpcbind 8 -.\" @(#)rpc_svc_create.3n 1.26 93/08/26 SMI; from SVr4 -.\" Copyright 1989 AT&T -.\" @(#)rpc_svc_create 1.3 89/06/28 SMI; -.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. -.\" $FreeBSD$ -.Dd May 3, 1993 -.Dt RPC_SVC_CREATE 3 -.Os -.Sh NAME -.Nm rpc_svc_create , -.Nm svc_control , -.Nm svc_create , -.Nm svc_destroy , -.Nm svc_dg_create , -.Nm svc_fd_create , -.Nm svc_raw_create , -.Nm svc_tli_create , -.Nm svc_tp_create , -.Nm svc_vc_create -.Nd library routines for the creation of server handles -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.Fd #include <rpc/rpc.h> -.Ft bool_t -.Fn svc_control "SVCXPRT *svc" "const u_int req" "void *info" -.Ft int -.Fn svc_create "const void (*dispatch)(struct svc_req *, SVCXPRT *)" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype" -.Ft SVCXPRT *" -.Fn svc_dg_create "const int fildes" "const u_int sendsz" "const u_int recvsz" -.Ft void -.Fn svc_destroy "SVCXPRT *xprt" -.Ft "SVCXPRT *" -.Fn svc_fd_create "const int fildes" "const u_int sendsz" "const u_int recvsz" -.Ft "SVCXPRT *" -.Fn svc_raw_create "void" -.Ft "SVCXPRT *" -.Fn svc_tli_create "const int fildes" "const struct netconfig *netconf" "const struct t_bind *bindaddr" "const u_int sendsz" "const u_int recvsz" -.Ft "SVCXPRT *" -.Fn svc_tp_create "const void (*dispatch)(const struct svc_reg *, const SVCXPRT *)" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" -.Ft "SVCXPRT *" -.Fn svc_vc_create "const int fildes" "const u_int sendsz" "const u_int recvsz" -.Sh DESCRIPTION -These routines are part of the RPC -library which allows C language programs to make procedure -calls on servers across the network. -These routines deal with the creation of service handles. -Once the handle is created, the server can be invoked by calling -.Fn svc_run . -.Sh Routines -See -.Xr rpc 3 -for the definition of the -.Vt SVCXPRT -data structure. -.Bl -tag -width XXXXX -.It Fn svc_control -A function to change or retrieve various information -about a service object. -.Fa req -indicates the type of operation and -.Fa info -is a pointer to the information. -The supported values of -.Fa req , -their argument types, and what they do are: -.Bl -tag -width SVCGET_XID -.It Dv SVCGET_VERSQUIET -If a request is received for a program number -served by this server but the version number -is outside the range registered with the server, -an -.Dv RPC_PROGVERSMISMATCH -error will normally -be returned. -.Fa info -should be a pointer to an -integer. -Upon successful completion of the -.Dv SVCGET_VERSQUIET -request, -.Fa *info -contains an -integer which describes the server's current -behavior: 0 indicates normal server behavior -(that is, an -.Dv RPC_PROGVERSMISMATCH -error -will be returned); 1 indicates that the out of -range request will be silently ignored. -.It Dv SVCSET_VERSQUIET -If a request is received for a program number -served by this server but the version number -is outside the range registered with the server, -an -.Dv RPC_PROGVERSMISMATCH -error will normally -be returned. -It is sometimes desirable to -change this behavior. -.Fa info -should be a -pointer to an integer which is either 0 -(indicating normal server behavior - an -.Dv RPC_PROGVERSMISMATCH -error will be returned), -or 1 (indicating that the out of range request -should be silently ignored). -.El -.It Fn svc_create -.Fn svc_create -creates server handles for all the transports -belonging to the class -.Fa nettype . -.Fa nettype -defines a class of transports which can be used -for a particular application. -The transports are tried in left to right order in -.Ev NETPATH -variable or in top to bottom order in the netconfig database. -If -.Fa nettype -is -.Dv NULL , -it defaults to -.Qq netpath . -.Pp -.Fn svc_create -registers itself with the rpcbind -service (see -.Xr rpcbind 8 ) . -.Fa dispatch -is called when there is a remote procedure call for the given -.Fa prognum -and -.Fa versnum ; -this requires calling -.Fn svc_run -(see -.Fn svc_run -in -.Xr rpc_svc_reg 3 ) . -If -.Fn svc_create -succeeds, it returns the number of server -handles it created, -otherwise it returns 0 and an error message is logged. -.It Fn svc_destroy -A function macro that destroys the RPC -service 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. -.It Fn svc_dg_create -This routine creates a connectionless RPC -service handle, and returns a pointer to it. -This routine returns -.Dv NULL -if it fails, and an error message is logged. -.Fa sendsz -and -.Fa recvsz -are parameters used to specify the size of the buffers. -If they are 0, suitable defaults are chosen. -The file descriptor -.Fa fildes -should be open and bound. -The server is not registered with -.Xr rpcbind 8 . -.Pp -Warning: -since connectionless-based RPC -messages can only hold limited amount of encoded data, -this transport cannot be used for procedures -that take large arguments or return huge results. -.It Fn svc_fd_create -This routine creates a service on top of an open and bound file descriptor, -and returns the handle to it. -Typically, this descriptor is a connected file descriptor for a -connection-oriented transport. -.Fa sendsz -and -.Fa recvsz -indicate sizes for the send and receive buffers. -If they are 0, reasonable defaults are chosen. -This routine returns -.Dv NULL -if it fails, and an error message is logged. -.It Fn svc_raw_create -This routine creates an RPC -service handle and returns a pointer to it. -The transport is really a buffer within the process's -address space, so the corresponding RPC -client should live in the same address space; -(see -.Fn clnt_raw_create -in -.Xr rpc_clnt_create 3 ) . -This routine allows simulation of RPC and acquisition of -RPC overheads (such as round trip times), -without any kernel and networking interference. -This routine returns -.Dv NULL -if it fails, and an error message is logged. -.Pp -Note: -.Fn svc_run -should not be called when the raw interface is being used. -.It Fn svc_tli_create -This routine creates an RPC -server handle, and returns a pointer to it. -.Fa fildes -is the file descriptor on which the service is listening. -If -.Fa fildes -is -.Dv RPC_ANYFD , -it opens a file descriptor on the transport specified by -.Fa netconf . -If the file descriptor is unbound and -.Fa bindaddr -is not -.Dv NULL , -.Fa fildes -is bound to the address specified by -.Fa bindaddr , -otherwise -.Fa fildes -is bound to a default address chosen by the transport. -.Pp -Note: the -.Vt t_bind -structure comes from the TLI/XTI SysV interface, which -.Nx -does not use. -The structure is defined in -.Aq Pa rpc/types.h -for compatibility as: -.Bd -literal -struct t_bind { - struct netbuf addr; /* network address, see rpc(3) */ - unsigned int qlen; /* queue length (for listen(2)) */ -}; -.Ed -.Pp -In the case where the default address is chosen, -the number of outstanding connect requests is set to 8 -for connection-oriented transports. -The user may specify the size of the send and receive buffers -with the parameters -.Fa sendsz -and -.Fa recvsz ; -values of 0 choose suitable defaults. -This routine returns -.Dv NULL -if it fails, -and an error message is logged. -The server is not registered with the -.Xr rpcbind 8 -service. -.It Fn svc_tp_create -.Fn svc_tp_create -creates a server handle for the network -specified by -.Fa netconf , -and registers itself with the rpcbind service. -.Fa dispatch -is called when there is a remote procedure call -for the given -.Fa prognum -and -.Fa versnum ; -this requires calling -.Fn svc_run . -.Fn svc_tp_create -returns the service handle if it succeeds, -otherwise a -.Dv NULL -is returned and an error message is logged. -.It Fn svc_vc_create -This routine creates a connection-oriented RPC -service and returns a pointer to it. -This routine returns -.Dv NULL -if it fails, and an error message is logged. -The users may specify the size of the send and receive buffers -with the parameters -.Fa sendsz -and -.Fa recvsz ; -values of 0 choose suitable defaults. -The file descriptor -.Fa fildes -should be open and bound. -The server is not registered with the -.Xr rpcbind 8 -service. -.El -.Sh SEE ALSO -.Xr rpc 3 , -.Xr rpc_svc_calls 3 , -.Xr rpc_svc_err 3 , -.Xr rpc_svc_reg 3 , -.Xr rpcbind 8 |