RPC_SVC_CREATE(3NSL) Networking Services Library Functions NNAAMMEE rpc_svc_create, svc_control, svc_create, svc_destroy, svc_dg_create, svc_fd_create, svc_raw_create, svc_tli_create, svc_tp_create, svc_tp_create_addr, svc_vc_create, svc_door_create - server handle creation routines SSYYNNOOPPSSIISS #include bbooooll__tt ssvvcc__ccoonnttrrooll(SSVVCCXXPPRRTT **_s_v_c, ccoonnsstt uuiinntt__tt _r_e_q, vvooiidd **_i_n_f_o); iinntt ssvvcc__ccrreeaattee(ccoonnsstt vvooiidd ((**_d_i_s_p_a_t_c_h)(const struct svc_req *, const SVCXPRT *), ccoonnsstt rrppccpprroogg__tt _p_r_o_g_n_u_m, ccoonnsstt rrppccvveerrss__tt _v_e_r_s_n_u_m, ccoonnsstt cchhaarr **_n_e_t_t_y_p_e); vvooiidd ssvvcc__ddeessttrrooyy(SSVVCCXXPPRRTT **_x_p_r_t); SSVVCCXXPPRRTT **ssvvcc__ddgg__ccrreeaattee(ccoonnsstt iinntt _f_i_l_d_e_s, ccoonnsstt uuiinntt__tt _s_e_n_d_s_z, ccoonnsstt uuiinntt__tt _r_e_c_v_s_z); SSVVCCXXPPRRTT **ssvvcc__ffdd__ccrreeaattee(ccoonnsstt iinntt _f_i_l_d_e_s, ccoonnsstt uuiinntt__tt _s_e_n_d_s_z, ccoonnsstt uuiinntt__tt _r_e_c_v_s_z); SSVVCCXXPPRRTT **ssvvcc__rraaww__ccrreeaattee(void); SSVVCCXXPPRRTT **ssvvcc__ttllii__ccrreeaattee(ccoonnsstt iinntt _f_i_l_d_e_s, ccoonnsstt ssttrruucctt nneettccoonnffiigg **_n_e_t_c_o_n_f, ccoonnsstt ssttrruucctt tt__bbiinndd **_b_i_n_d___i_n_f_o, ccoonnsstt uuiinntt__tt _s_e_n_d_s_z, ccoonnsstt uuiinntt__tt _r_e_c_v_s_z); SSVVCCXXPPRRTT **ssvvcc__ttpp__ccrreeaattee(ccoonnsstt vvooiidd ((**_d_i_s_p_a_t_c_h) (const struct svc_req *, const SVCXPRT *), ccoonnsstt rrppccpprroogg__tt _p_r_o_g_n_u_m, ccoonnsstt rrppccvveerrss__tt _v_e_r_s_n_u_m, ccoonnsstt ssttrruucctt nneettccoonnffiigg **_n_e_t_c_o_n_f); SSVVCCXXPPRRTT **ssvvcc__ttpp__ccrreeaattee__aaddddrr(ccoonnsstt vvooiidd ((**_d_i_s_p_a_t_c_h) (const struct svc_req *, const SVCXPRT *), ccoonnsstt rrppccpprroogg__tt _p_r_o_g_n_u_m, ccoonnsstt rrppccvveerrss__tt _v_e_r_s_n_u_m, ccoonnsstt ssttrruucctt nneettccoonnffiigg **_n_e_t_c_o_n_f, ccoonnsstt ssttrruucctt nneettbbuuff **_b_i_n_d___a_d_d_r) ); SSVVCCXXPPRRTT **ssvvcc__vvcc__ccrreeaattee(ccoonnsstt iinntt _f_i_l_d_e_s, ccoonnsstt uuiinntt__tt _s_e_n_d_s_z, ccoonnsstt uuiinntt__tt _r_e_c_v_s_z); SSVVCCXXPPRRTT **ssvvcc__ddoooorr__ccrreeaattee(vvooiidd ((**_d_i_s_p_a_t_c_h)(struct svc_req *, SVCXPRT *), ccoonnsstt rrppccpprroogg__tt _p_r_o_g_n_u_m, ccoonnsstt rrppccvveerrss__tt _v_e_r_s_n_u_m, ccoonnsstt uuiinntt__tt _s_e_n_d_s_z); DDEESSCCRRIIPPTTIIOONN These routines are part of the RRPPCC 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 ssvvcc__rruunn(()). RRoouuttiinneess See rrppcc(3NSL) for the definition of the SSVVCCXXPPRRTT data structure. ssvvcc__ccoonnttrrooll(()) A function to change or retrieve information about a service object. _r_e_q indicates the type of operation and _i_n_f_o is a pointer to the information. The supported values of _r_e_q, their argument types, and what they do are: SSVVCCGGEETT__VVEERRSSQQUUIIEETT 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 RRPPCC__PPRROOGGVVEERRSSMMIISSMMAATTCCHH error will normally be returned. _i_n_f_o should be a pointer to an integer. Upon successful completion of the SSVVCCGGEETT__VVEERRSSQQUUIIEETT request, *_i_n_f_o contains an integer which describes the server's current behavior: 00 indicates normal server behavior, that is, an RRPPCC__PPRROOGGVVEERRSSMMIISSMMAATTCCHH error will be returned. 11 indicates that the out of range request will be silently ignored. SSVVCCSSEETT__VVEERRSSQQUUIIEETT 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 RRPPCC__PPRROOGGVVEERRSSMMIISSMMAATTCCHH error will normally be returned. It is sometimes desirable to change this behavior. _i_n_f_o should be a pointer to an integer which is either 00, indicating normal server behavior and an RRPPCC__PPRROOGGVVEERRSSMMIISSMMAATTCCHH error will be returned, or 11, indicating that the out of range request should be silently ignored. SSVVCCGGEETT__XXIIDD Returns the transaction IIDD of connection-oriented and connectionless transport service calls. The transaction IIDD assists in uniquely identifying client requests for a given RRPPCC version, program number, procedure, and client. The transaction IIDD is extracted from the service transport handle _s_v_c. _i_n_f_o must be a pointer to an unsigned long. Upon successful completion of the SSVVCCGGEETT__XXIIDD request, *_i_n_f_o contains the transaction IIDD. Note that rendezvous and raw service handles do not define a transaction IIDD. Thus, if the service handle is of rendezvous or raw type, and the request is of type SSVVCCGGEETT__XXIIDD,, ssvvcc__ccoonnttrrooll(()) will return FFAALLSSEE. Note also that the transaction IIDD read by the server can be set by the client through the suboption CCLLSSEETT__XXIIDD in ccllnntt__ccoonnttrrooll(()). See ccllnntt__ccrreeaattee(3NSL) SSVVCCSSEETT__RREECCVVEERRRRHHAANNDDLLEERR Attaches or detaches a disconnection handler to the service handle, _s_v_c, that will be called when a transport error arrives during the reception of a request or when the server is waiting for a request and the connection shuts down. This handler is only useful for a connection oriented service handle. _*_i_n_f_o contains the address of the error handler to attach, or _N_U_L_L to detach a previously defined one. The error handler has two arguments. It has a pointer to the erroneous service handle. It also has an integer that indicates if the full service is closed (when equal to zero), or that only one connection on this service is closed (when not equal to zero). void handler (const SVCXPRT *svc, const bool_t isAConnection); With the service handle address, _s_v_c, the error handler is able to detect which connection has failed and to begin an error recovery process. The error handler can be called by multiple threads and should be implemented in an MT-safe way. SSVVCCGGEETT__RREECCVVEERRRRHHAANNDDLLEERR Upon successful completion of the SSVVCCGGEETT__RREECCVVEERRRRHHAANNDDLLEERR request, _*_i_n_f_o contains the address of the handler for receiving errors. Upon failure, _*_i_n_f_o contains _N_U_L_L. SSVVCCSSEETT__CCOONNNNMMAAXXRREECC Set the maximum record size (in bytes) and enable non-blocking mode for this service handle. Value can be set and read for both connection and non-connection oriented transports, but is silently ignored for the non-connection oriented case. The _i_n_f_o argument should be a pointer to an iinntt. SSVVCCGGEETT__CCOONNNNMMAAXXRREECC Get the maximum record size for this service handle. Zero means no maximum in effect and the connection is in blocking mode. The result is not significant for non-connection oriented transports. The _i_n_f_o argument should be a pointer to an iinntt. This routine returns TRUE if the operation was successful. Otherwise, it returns false. ssvvcc__ccrreeaattee(()) ssvvcc__ccrreeaattee(()) creates server handles for all the transports belonging to the class _n_e_t_t_y_p_e. _n_e_t_t_y_p_e defines a class of transports which can be used for a particular application. The transports are tried in left to right order in NNEETTPPAATTHH variable or in top to bottom order in the netconfig database. If _n_e_t_t_y_p_e is _N_U_L_L_, it defaults to nneettppaatthh. ssvvcc__ccrreeaattee(()) registers itself with the rrppccbbiinndd service (see rrppccbbiinndd(1M)). _d_i_s_p_a_t_c_h is called when there is a remote procedure call for the given _p_r_o_g_n_u_m and _v_e_r_s_n_u_m; this requires calling ssvvcc__rruunn(()) (see ssvvcc__rruunn(()) in rrppcc__ssvvcc__ccaallllss(3NSL)). If ssvvcc__ccrreeaattee(()) succeeds, it returns the number of server handles it created, otherwise it returns 00 and an error message is logged. ssvvcc__ddeessttrrooyy(()) A function macro that destroys the RRPPCC service handle _x_p_r_t. Destruction usually involves deallocation of private data structures, including _x_p_r_t itself. Use of _x_p_r_t is undefined after calling this routine. ssvvcc__ddgg__ccrreeaattee(()) This routine creates a connectionless RRPPCC service handle, and returns a pointer to it. This routine returns _N_U_L_L if it fails, and an error message is logged. _s_e_n_d_s_z and _r_e_c_v_s_z are parameters used to specify the size of the buffers. If they are 00, suitable defaults are chosen. The file descriptor _f_i_l_d_e_s should be open and bound. The server is not registered with rrppccbbiinndd(1M). Warning: since connectionless-based RRPPCC messages can only hold limited amount of encoded data, this transport cannot be used for procedures that take large arguments or return huge results. ssvvcc__ffdd__ccrreeaattee(()) 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. _s_e_n_d_s_z and _r_e_c_v_s_z indicate sizes for the send and receive buffers. If they are 00, reasonable defaults are chosen. This routine returns _N_U_L_L if it fails, and an error message is logged. ssvvcc__rraaww__ccrreeaattee(()) This routine creates an RRPPCC service handle and returns a pointer to it. The transport is really a buffer within the process's address space, so the corresponding RRPPCC client should live in the same address space; (see ccllnntt__rraaww__ccrreeaattee(()) in rrppcc__ccllnntt__ccrreeaattee(3NSL)). This routine allows simulation of RRPPCC and acquisition of RRPPCC overheads (such as round trip times), without any kernel and networking interference. This routine returns _N_U_L_L if it fails, and an error message is logged. Note: ssvvcc__rruunn(()) should not be called when the raw interface is being used. ssvvcc__ttllii__ccrreeaattee(()) This routine creates an RRPPCC server handle, and returns a pointer to it. _f_i_l_d_e_s is the file descriptor on which the service is listening. If _f_i_l_d_e_s is RRPPCC__AANNYYFFDD, it opens a file descriptor on the transport specified by _n_e_t_c_o_n_f. If the file descriptor is unbound and _b_i_n_d___i_n_f_o is non-null _f_i_l_d_e_s is bound to the address specified by _b_i_n_d___i_n_f_o, otherwise _f_i_l_d_e_s is bound to a default address chosen by the transport. 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 _s_e_n_d_s_z and _r_e_c_v_s_z _; values of 00 choose suitable defaults. This routine returns _N_U_L_L if it fails, and an error message is logged. The server is not registered with the rrppccbbiinndd(1M) service. ssvvcc__ttpp__ccrreeaattee(()) ssvvcc__ttpp__ccrreeaattee(()) creates a server handle for the network specified by _n_e_t_c_o_n_f, and registers itself with the rrppccbbiinndd service. _d_i_s_p_a_t_c_h is called when there is a remote procedure call for the given _p_r_o_g_n_u_m and _v_e_r_s_n_u_m; this requires calling ssvvcc__rruunn(()). ssvvcc__ttpp__ccrreeaattee(()) returns the service handle if it succeeds, otherwise a _N_U_L_L is returned and an error message is logged. ssvvcc__ttpp__ccrreeaattee__aaddddrr(()) ssvvcc__ttpp__ccrreeaattee__aaddddrr(()) creates a server handle for the network specified by _n_e_t_c_o_n_f, and registers itself with the rrppccbbiinndd service. If _b_i_n_d___a_d_d_r is non-NULL, that address is used for the listener binding. If _b_i_n_d___a_d_d_r is NULL, this call is the same as ssvvcc__ttpp__ccrreeaattee(()). _d_i_s_p_a_t_c_h is called when there is a remote procedure call for the given _p_r_o_g_n_u_m and _v_e_r_s_n_u_m; this requires calling ssvvcc__rruunn(()). ssvvcc__ttpp__ccrreeaattee__aaddddrr(()) returns the service handle if it succeeds, otherwise a _N_U_L_L is returned and an error message is logged. ssvvcc__vvcc__ccrreeaattee(()) This routine creates a connection-oriented RRPPCC service and returns a pointer to it. This routine returns _N_U_L_L if it fails, and an error message is logged. The users may specify the size of the send and receive buffers with the parameters _s_e_n_d_s_z and _r_e_c_v_s_z; values of 00 choose suitable defaults. The file descriptor _f_i_l_d_e_s should be open and bound. The server is not registered with the rrppccbbiinndd(1M) service. ssvvcc__ddoooorr__ccrreeaattee(()) This routine creates an RPC server handle over doors for the given program _p_r_o_g_n_u_m and version _v_e_r_s_n_u_m and returns a pointer to it. Doors is a transport mechanism that facilitates fast data transfer between processes on the same machine. The user may set the size of the send buffer with the parameter _s_e_n_d_s_z. If _s_e_n_d_s_z is 0, the corresponding default buffer size is 16 Kbyte. If successful, the ssvvcc__ddoooorr__ccrreeaattee(()) routine returns the service handle. Otherwise it returns _N_U_L_L and sets a value for rrppcc__ccrreeaatteeeerrrr. The server is not registered with rrppccbbiinndd(1M). The SSVVCCSSEETT__CCOONNNNMMAAXXRREECC and SSVVCCGGEETT__CCOONNNNMMAAXXRREECC ssvvcc__ccoonnttrrooll(()) requests can be used to set and change the maximum allowed request size for the doors transport. AATTTTRRIIBBUUTTEESS See aattttrriibbuutteess(5) for descriptions of the following attributes: +--------------------+-----------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +--------------------+-----------------+ |Architecture | All | +--------------------+-----------------+ |Interface Stability | Evolving | +--------------------+-----------------+ |MT-Level | MT-Safe | +--------------------+-----------------+ SSEEEE AALLSSOO rrppccbbiinndd(1M), rrppcc(3NSL), rrppcc__ccllnntt__ccrreeaattee(3NSL), rrppcc__ssvvcc__ccaallllss(3NSL), rrppcc__ssvvcc__eerrrr(3NSL), rrppcc__ssvvcc__rreegg(3NSL), aattttrriibbuutteess(5) June 19, 2017 RPC_SVC_CREATE(3NSL)