.\" @(#)rpc_svc_reg.3n 1.32 93/08/31 SMI; from SVr4

.\" Copyright 1989 AT&T

.\" @(#)rpc_svc_call 1.6 89/07/20 SMI;

.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.

.\"	$NetBSD: rpc_svc_reg.3,v 1.1 2000/06/02 23:11:14 fvdl Exp $

.\"	$FreeBSD: src/lib/libc/rpc/rpc_svc_reg.3,v 1.5 2002/12/19 09:40:23 ru Exp $

.Dd May 3, 1993

.Dt RPC_SVC_REG 3

.Os

.Sh NAME

.Nm rpc_svc_reg ,

.Nm rpc_reg ,

.Nm svc_reg ,

.Nm svc_unreg ,

.Nm svc_auth_reg ,

.Nm xprt_register ,

.Nm xprt_unregister

.Nd library routines for registering servers

.Sh SYNOPSIS

.In rpc/rpc.h

.Ft int

.Fn rpc_reg "rpcprog_t prognum" "rpcvers_t versnum" "rpcproc_t procnum" "char *(*procname)()" "xdrproc_t inproc" "xdrproc_t outproc" "char *nettype"

.Ft bool_t

.Fn svc_reg "SVCXPRT *xprt" "const rpcprog_t prognum" "const rpcvers_t versnum" "void (*dispatch)(struct svc_req *, SVCXPRT *)" "const struct netconfig *netconf"

.Ft void

.Fn svc_unreg "const rpcprog_t prognum" "const rpcvers_t versnum"

.Ft int

.Fn svc_auth_reg "int cred_flavor" "enum auth_stat (*handler)(struct svc_req *, struct rpc_msg *)"

.Ft void

.Fn xprt_register "SVCXPRT *xprt"

.Ft void

.Fn xprt_unregister "SVCXPRT *xprt"

.Sh DESCRIPTION

These routines are a part of the RPC

library which allows the RPC

servers to register themselves with rpcbind

(see

.Xr rpcbind 8 ) ,

and associate the given program and version

number with the dispatch function.

When the RPC server receives a RPC request, the library invokes the

dispatch routine with the appropriate arguments.

.Sh Routines

See

.Xr rpc 3

for the definition of the

.Vt SVCXPRT

data structure.

.Bl -tag -width XXXXX

.It Fn rpc_reg

Register program

.Fa prognum ,

procedure

.Fa procname ,

and version

.Fa versnum

with the RPC

service package.

If a request arrives for program

.Fa prognum ,

version

.Fa versnum ,

and procedure

.Fa procnum ,

.Fa procname

is called with a pointer to its argument(s);

.Fa procname

should return a pointer to its static result(s);

.Fa inproc

is the XDR function used to decode the arguments while

.Fa outproc

is the XDR function used to encode the results.

Procedures are registered on all available transports of the class

.Fa nettype .

See

.Xr rpc 3 .

This routine returns 0 if the registration succeeded,

\-1 otherwise.

.It Fn svc_reg

Associates

.Fa prognum

and

.Fa versnum

with the service dispatch procedure,

.Fa dispatch .

If

.Fa netconf

is

.Dv NULL ,

the service is not registered with the

.Xr rpcbind 8

service.

If

.Fa netconf

is non-zero,

then a mapping of the triple

.Bq Fa prognum , versnum , netconf->nc_netid

to

.Fa xprt->xp_ltaddr

is established with the local rpcbind

service.

.Pp

The

.Fn svc_reg

routine returns 1 if it succeeds,

and 0 otherwise.

.It Fn svc_unreg

Remove from the rpcbind

service, all mappings of the triple

.Bq Fa prognum , versnum , No all-transports

to network address

and all mappings within the RPC service package

of the double

.Bq Fa prognum , versnum

to dispatch routines.

.It Fn svc_auth_reg

Registers the service authentication routine

.Fa handler

with the dispatch mechanism so that it can be

invoked to authenticate RPC requests received

with authentication type

.Fa cred_flavor .

This interface allows developers to add new authentication

types to their RPC applications without needing to modify

the libraries.

Service implementors usually do not need this routine.

.Pp

Typical service application would call

.Fn svc_auth_reg

after registering the service and prior to calling

.Fn svc_run .

When needed to process an RPC credential of type

.Fa cred_flavor ,

the

.Fa handler

procedure will be called with two arguments,

.Fa "struct svc_req *rqst"

and

.Fa "struct rpc_msg *msg" ,

and is expected to return a valid

.Vt "enum auth_stat"

value.

There is no provision to change or delete an authentication handler

once registered.

.Pp

The

.Fn svc_auth_reg

routine returns 0 if the registration is successful,

1 if

.Fa cred_flavor

already has an authentication handler registered for it,

and \-1 otherwise.

.It Fn xprt_register

After RPC service transport handle

.Fa xprt

is created, it is registered with the RPC

service package.

This routine modifies the global variable

.Va svc_fdset

(see

.Xr rpc_svc_calls 3 ) .

Service implementors usually do not need this routine.

.It Fn xprt_unregister

Before an RPC service transport handle

.Fa xprt

is destroyed, it unregisters itself with the

RPC service package.

This routine modifies the global variable

.Va svc_fdset

(see

.Xr rpc_svc_calls 3 ) .

Service implementors usually do not need this routine.

.El

.Sh AVAILABILITY

These functions are part of libtirpc.

.Sh SEE ALSO

.Xr select 2 ,

.Xr rpc 3 ,

.Xr rpcbind 3 ,

.Xr rpc_svc_calls 3 ,

.Xr rpc_svc_create 3 ,

.Xr rpc_svc_err 3 ,

.Xr rpcbind 8