evin/ms-nfs41-client
3
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

fresh git tree for public release

Browse source 
we regretfully had to remove our git history for licensing reasons

Signed-off-by: Casey Bodley <cbodley@citi.umich.edu>
This commit is contained in:
Casey Bodley 2010-10-11 14:59:26 -04:00
commit 0ad4db4fad
271 changed files with 71255 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

9
libtirpc/man/Makefile.am Normal file
View file

@ -0,0 +1,9 @@
man5_MANS = netconfig.5
man3_MANS = bindresvport.3t des_crypt.3t getnetconfig.3t getnetpath.3t \
getrpcent.3t getrpcport.3t rpc.3t rpc_clnt_auth.3t rpc_clnt_calls.3t \
rpc_clnt_create.3t rpc_secure.3t rpc_soc.3t rpc_svc_calls.3t \
rpc_svc_create.3t rpc_svc_err.3t rpc_svc_reg.3t rpc_xdr.3t rtime.3t
EXTRA_DIST = $(man5_MANS) $(man3_MANS)

101
libtirpc/man/bindresvport.3t Normal file
View file

@ -0,0 +1,101 @@
.\" @(#)bindresvport.3n 2.2 88/08/02 4.0 RPCSRC; from 1.7 88/03/14 SMI
.\"
.Dd November 22, 1987
.Dt BINDRESVPORT 3
.Os
.Sh NAME
.Nm bindresvport ,
.Nm bindresvport_sa
.Nd bind a socket to a privileged IP port
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/types.h
.In rpc/rpc.h
.Ft int
.Fn bindresvport "int sd" "struct sockaddr_in *sin"
.Ft int
.Fn bindresvport_sa "int sd" "struct sockaddr *sa"
.Sh DESCRIPTION
The
.Fn bindresvport
and
.Fn bindresvport_sa
functions
are used to bind a socket descriptor to a privileged
.Tn IP
port, that is, a
port number in the range 0-1023.
.Pp
If
.Fa sin
is a pointer to a
.Ft "struct sockaddr_in"
then the appropriate fields in the structure should be defined.
Note that
.Fa sin->sin_family
must be initialized to the address family of the socket, passed by
.Fa sd .
If
.Fa sin->sin_port
is
.Sq 0
then an anonymous port (in the range 600-1023) will be
chosen, and if
.Xr bind 2
is successful, the
.Fa sin->sin_port
will be updated to contain the allocated port.
.Pp
If
.Fa sin
is the
.Dv NULL
pointer,
an anonymous port will be allocated (as above).
However, there is no way for
.Fn bindresvport
to return the allocated port in this case.
.Pp
Only root can bind to a privileged port; this call will fail for any
other users.
.Pp
Function prototype of
.Fn bindresvport
is biased to
.Dv AF_INET
socket.
The
.Fn bindresvport_sa
function
acts exactly the same, with more neutral function prototype.
Note that both functions behave exactly the same, and
both support
.Dv AF_INET6
sockets as well as
.Dv AF_INET
sockets.
.Sh RETURN VALUES
.Rv -std bindresvport
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EPFNOSUPPORT
If second argument was supplied,
and address family did not match between arguments.
.El
.Pp
The
.Fn bindresvport
function
may also fail and set
.Va errno
for any of the errors specified for the calls
.Xr bind 2 ,
.Xr getsockopt 2 ,
or
.Xr setsockopt 2 .
.Sh SEE ALSO
.Xr bind 2 ,
.Xr getsockopt 2 ,
.Xr setsockopt 2 ,
.Xr ip 4

129
libtirpc/man/des_crypt.3t Normal file
View file

@ -0,0 +1,129 @@
.\" @(#)des_crypt.3 2.1 88/08/11 4.0 RPCSRC; from 1.16 88/03/02 SMI;
.\"
.Dd October 6, 1987
.Dt DES_CRYPT 3
.Os
.Sh NAME
.Nm des_crypt , ecb_crypt , cbc_crypt , des_setparity
.Nd "fast DES encryption"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/des_crypt.h
.Ft int
.Fn ecb_crypt "char *key" "char *data" "unsigned datalen" "unsigned mode"
.Ft int
.Fn cbc_crypt "char *key" "char *data" "unsigned datalen" "unsigned mode" "char *ivec"
.Ft void
.Fn des_setparity "char *key"
.Sh DESCRIPTION
The
.Fn ecb_crypt
and
.Fn cbc_crypt
functions
implement the
.Tn NBS
.Tn DES
(Data Encryption Standard).
These routines are faster and more general purpose than
.Xr crypt 3 .
They also are able to utilize
.Tn DES
hardware if it is available.
The
.Fn ecb_crypt
function
encrypts in
.Tn ECB
(Electronic Code Book)
mode, which encrypts blocks of data independently.
The
.Fn cbc_crypt
function
encrypts in
.Tn CBC
(Cipher Block Chaining)
mode, which chains together
successive blocks.
.Tn CBC
mode protects against insertions, deletions and
substitutions of blocks.
Also, regularities in the clear text will
not appear in the cipher text.
.Pp
Here is how to use these routines.
The first argument,
.Fa key ,
is the 8-byte encryption key with parity.
To set the key's parity, which for
.Tn DES
is in the low bit of each byte, use
.Fn des_setparity .
The second argument,
.Fa data ,
contains the data to be encrypted or decrypted.
The
third argument,
.Fa datalen ,
is the length in bytes of
.Fa data ,
which must be a multiple of 8.
The fourth argument,
.Fa mode ,
is formed by
.Em OR Ns 'ing
together some things.
For the encryption direction
.Em OR
in either
.Dv DES_ENCRYPT
or
.Dv DES_DECRYPT .
For software versus hardware
encryption,
.Em OR
in either
.Dv DES_HW
or
.Dv DES_SW .
If
.Dv DES_HW
is specified, and there is no hardware, then the encryption is performed
in software and the routine returns
.Er DESERR_NOHWDEVICE .
For
.Fn cbc_crypt ,
the
.Fa ivec
argument
is the 8-byte initialization
vector for the chaining.
It is updated to the next initialization
vector upon return.
.Sh ERRORS
.Bl -tag -width [DESERR_NOHWDEVICE] -compact
.It Bq Er DESERR_NONE
No error.
.It Bq Er DESERR_NOHWDEVICE
Encryption succeeded, but done in software instead of the requested hardware.
.It Bq Er DESERR_HWERR
An error occurred in the hardware or driver.
.It Bq Er DESERR_BADPARAM
Bad argument to routine.
.El
.Pp
Given a result status
.Va stat ,
the macro
.Fn DES_FAILED stat
is false only for the first two statuses.
.Sh SEE ALSO
.\" .Xr des 1 ,
.Xr crypt 3
.Sh RESTRICTIONS
These routines are not available in RPCSRC 4.0.
This information is provided to describe the
.Tn DES
interface expected by
Secure RPC.

220
libtirpc/man/getnetconfig.3t Normal file
View file

@ -0,0 +1,220 @@
.\" @(#)getnetconfig.3n 1.28 93/06/02 SMI; from SVr4
.\" Copyright 1989 AT&T
.Dd April 22, 2000
.Dt GETNETCONFIG 3
.Os
.Sh NAME
.Nm getnetconfig ,
.Nm setnetconfig ,
.Nm endnetconfig ,
.Nm getnetconfigent ,
.Nm freenetconfigent ,
.Nm nc_perror ,
.Nm nc_sperror
.Nd get network configuration database entry
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In netconfig.h
.Ft "struct netconfig *"
.Fn getnetconfig "void *handlep"
.Ft "void *"
.Fn setnetconfig "void"
.Ft int
.Fn endnetconfig "void *handlep"
.Ft "struct netconfig *"
.Fn getnetconfigent "const char *netid"
.Ft void
.Fn freenetconfigent "struct netconfig *netconfigp"
.Ft void
.Fn nc_perror "const char *msg"
.Ft "char *"
.Fn nc_sperror "void"
.Sh DESCRIPTION
The library routines described on this page
provide the application access to
the system network configuration database,
.Pa /etc/netconfig .
The
.Fn getnetconfig
function
returns a pointer to the
current entry in the
netconfig
database, formatted as a
.Ft "struct netconfig" .
Successive calls will return successive netconfig
entries in the netconfig database.
The
.Fn getnetconfig
function
can be used to search the entire netconfig
file.
The
.Fn getnetconfig
function
returns
.Dv NULL
at the end of the file.
The
.Fa handlep
argument
is the handle obtained through
.Fn setnetconfig .
.Pp
A call to
.Fn setnetconfig
has the effect of
.Dq binding
to or
.Dq rewinding
the netconfig database.
The
.Fn setnetconfig
function
must be called before the first call to
.Fn getnetconfig
and may be called at any other time.
The
.Fn setnetconfig
function
need not be called before a call to
.Fn getnetconfigent .
The
.Fn setnetconfig
function
returns a unique handle to be used by
.Fn getnetconfig .
.Pp
The
.Fn endnetconfig
function
should be called when processing is complete to release resources for reuse.
The
.Fa handlep
argument
is the handle obtained through
.Fn setnetconfig .
Programmers should be aware, however, that the last call to
.Fn endnetconfig
frees all memory allocated by
.Fn getnetconfig
for the
.Ft "struct netconfig"
data structure.
The
.Fn endnetconfig
function
may not be called before
.Fn setnetconfig .
.Pp
The
.Fn getnetconfigent
function
returns a pointer
to the netconfig structure corresponding
to
.Fa netid .
It returns
.Dv NULL
if
.Fa netid
is invalid
(that is, does not name an entry in the netconfig database).
.Pp
The
.Fn freenetconfigent
function
frees the netconfig structure pointed to by
.Fa netconfigp
(previously returned by
.Fn getnetconfigent ) .
.Pp
The
.Fn nc_perror
function
prints a message to the standard error indicating why any of the
above routines failed.
The message is prepended with the string
.Fa msg
and a colon.
A newline character is appended at the end of the message.
.Pp
The
.Fn nc_sperror
function
is similar to
.Fn nc_perror
but instead of sending the message
to the standard error, will return a pointer to a string that
contains the error message.
.Pp
The
.Fn nc_perror
and
.Fn nc_sperror
functions
can also be used with the
.Ev NETPATH
access routines defined in
.Xr getnetpath 3 .
.Sh RETURN VALUES
The
.Fn setnetconfig
function
returns a unique handle to be used by
.Fn getnetconfig .
In the case of an error,
.Fn setnetconfig
returns
.Dv NULL
and
.Fn nc_perror
or
.Fn nc_sperror
can be used to print the reason for failure.
.Pp
The
.Fn getnetconfig
function
returns a pointer to the current entry in the netconfig
database, formatted as a
.Ft "struct netconfig" .
The
.Fn getnetconfig
function
returns
.Dv NULL
at the end of the file, or upon failure.
.Pp
The
.Fn endnetconfig
function
returns 0 on success and \-1 on failure
(for example, if
.Fn setnetconfig
was not called previously).
.Pp
On success,
.Fn getnetconfigent
returns a pointer to the
.Ft "struct netconfig"
structure corresponding to
.Fa netid ;
otherwise it returns
.Dv NULL .
.Pp
The
.Fn nc_sperror
function
returns a pointer to a buffer which contains the error message string.
This buffer is overwritten on each call.
In multithreaded applications, this buffer is
implemented as thread-specific data.
.Sh FILES
.Bl -tag -width /etc/netconfig -compact
.It Pa /etc/netconfig
.El
.Sh SEE ALSO
.Xr getnetpath 3 ,
.Xr netconfig 5

168
libtirpc/man/getnetpath.3t Normal file
View file

@ -0,0 +1,168 @@
.\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4
.\" Copyright 1989 AT&T
.Dd April 22, 2000
.Dt GETNETPATH 3
.Os
.Sh NAME
.Nm getnetpath ,
.Nm setnetpath ,
.Nm endnetpath
.Nd get
.Pa /etc/netconfig
entry corresponding to
.Ev NETPATH
component
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In netconfig.h
.Ft "struct netconfig *"
.Fn getnetpath "void *handlep"
.Ft "void *"
.Fn setnetpath "void"
.Ft int
.Fn endnetpath "void *handlep"
.Sh DESCRIPTION
The routines described in this page provide the application access to the system
network configuration database,
.Pa /etc/netconfig ,
as it is
.Dq filtered
by the
.Ev NETPATH
environment variable (see
.Xr environ 7 ) .
See
.Xr getnetconfig 3
for other routines that also access the
network configuration database directly.
The
.Ev NETPATH
variable is a list of colon-separated network identifiers.
.Pp
The
.Fn getnetpath
function
returns a pointer to the
netconfig database entry corresponding to the first valid
.Ev NETPATH
component.
The netconfig entry is formatted as a
.Ft "struct netconfig" .
On each subsequent call,
.Fn getnetpath
returns a pointer to the netconfig entry that corresponds to the next
valid
.Ev NETPATH
component.
The
.Fn getnetpath
function
can thus be used to search the netconfig database for all networks
included in the
.Ev NETPATH
variable.
When
.Ev NETPATH
has been exhausted,
.Fn getnetpath
returns
.Dv NULL .
.Pp
A call to
.Fn setnetpath
.Dq binds
to or
.Dq rewinds
.Ev NETPATH .
The
.Fn setnetpath
function
must be called before the first call to
.Fn getnetpath
and may be called at any other time.
It returns a handle that is used by
.Fn getnetpath .
.Pp
The
.Fn getnetpath
function
silently ignores invalid
.Ev NETPATH
components.
A
.Ev NETPATH
component is invalid if there is no corresponding
entry in the netconfig database.
.Pp
If the
.Ev NETPATH
variable is unset,
.Fn getnetpath
behaves as if
.Ev NETPATH
were set to the sequence of
.Dq default
or
.Dq visible
networks in the netconfig database, in the
order in which they are listed.
.\"This proviso holds also for this
.\"whole manpage.
.Pp
The
.Fn endnetpath
function
may be called to
.Dq unbind
from
.Ev NETPATH
when processing is complete, releasing resources for reuse.
Programmers should be aware, however, that
.Fn endnetpath
frees all memory allocated by
.Fn getnetpath
for the struct netconfig data structure.
.Sh RETURN VALUES
The
.Fn setnetpath
function
returns a handle that is used by
.Fn getnetpath .
In case of an error,
.Fn setnetpath
returns
.Dv NULL .
.Pp
The
.Fn endnetpath
function
returns 0 on success and \-1 on failure
(for example, if
.Fn setnetpath
was not called previously).
The
.Fn nc_perror
or
.Fn nc_sperror
function
can be used to print out the reason for failure.
See
.Xr getnetconfig 3 .
.Pp
When first called,
.Fn getnetpath
returns a pointer to the netconfig database entry corresponding to the first
valid
.Ev NETPATH
component.
When
.Ev NETPATH
has been exhausted,
.Fn getnetpath
returns
.Dv NULL .
.Sh SEE ALSO
.Xr getnetconfig 3 ,
.Xr netconfig 5 ,
.Xr environ 7

106
libtirpc/man/getrpcent.3t Normal file
View file

@ -0,0 +1,106 @@
.\" @(#)getrpcent.3n 2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI
.\"
.Dd December 14, 1987
.Dt GETRPCENT 3
.Os
.Sh NAME
.Nm getrpcent ,
.Nm getrpcbyname ,
.Nm getrpcbynumber ,
.Nm endrpcent ,
.Nm setrpcent
.Nd get RPC entry
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/rpc.h
.Ft struct rpcent *
.Fn getrpcent void
.Ft struct rpcent *
.Fn getrpcbyname "char *name"
.Ft struct rpcent *
.Fn getrpcbynumber "int number"
.Ft void
.Fn setrpcent "int stayopen"
.Ft void
.Fn endrpcent void
.Sh DESCRIPTION
The
.Fn getrpcent ,
.Fn getrpcbyname ,
and
.Fn getrpcbynumber
functions
each return a pointer to an object with the
following structure
containing the broken-out
fields of a line in the rpc program number data base,
.Pa /etc/rpc :
.Bd -literal
struct rpcent {
char *r_name; /* name of server for this rpc program */
char **r_aliases; /* alias list */
long r_number; /* rpc program number */
};
.Ed
.Pp
The members of this structure are:
.Bl -tag -width r_aliases -offset indent
.It Va r_name
The name of the server for this rpc program.
.It Va r_aliases
A zero terminated list of alternate names for the rpc program.
.It Va r_number
The rpc program number for this service.
.El
.Pp
The
.Fn getrpcent
function
reads the next line of the file, opening the file if necessary.
.Pp
The
.Fn setrpcent
function
opens and rewinds the file. If the
.Fa stayopen
flag is non-zero,
the net data base will not be closed after each call to
.Fn getrpcent
(either directly, or indirectly through one of
the other
.Dq getrpc
calls).
.Pp
The
.Fn endrpcent
function
closes the file.
.Pp
The
.Fn getrpcbyname
and
.Fn getrpcbynumber
functions
sequentially search from the beginning
of the file until a matching rpc program name or
program number is found, or until end-of-file is encountered.
.Sh FILES
.Bl -tag -width /etc/rpc -compact
.It Pa /etc/rpc
.El
.Sh SEE ALSO
.Xr rpc 5 ,
.Xr rpcinfo 8 ,
.Xr ypserv 8
.Sh DIAGNOSTICS
A
.Dv NULL
pointer is returned on
.Dv EOF
or error.
.Sh BUGS
All information
is contained in a static area
so it must be copied if it is
to be saved.

34
libtirpc/man/getrpcport.3t Normal file
View file

@ -0,0 +1,34 @@
.\" @(#)getrpcport.3r 2.2 88/08/02 4.0 RPCSRC; from 1.12 88/02/26 SMI
.\"
.Dd October 6, 1987
.Dt GETRPCPORT 3
.Os
.Sh NAME
.Nm getrpcport
.Nd get RPC port number
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.Ft int
.Fn getrpcport "char *host" "int prognum" "int versnum" "int proto"
.Sh DESCRIPTION
The
.Fn getrpcport
function
returns the port number for version
.Fa versnum
of the RPC program
.Fa prognum
running on
.Fa host
and using protocol
.Fa proto .
It returns 0 if it cannot contact the portmapper, or if
.Fa prognum
is not registered. If
.Fa prognum
is registered but not with version
.Fa versnum ,
it will still return a port number (for some version of the program)
indicating that the program is indeed registered.
The version mismatch will be detected upon the first call to the service.

123
libtirpc/man/netconfig.5 Normal file
View file

@ -0,0 +1,123 @@
.Dd November 17, 2000
.Dt NETCONFIG 5
.Os
.Sh NAME
.Nm netconfig
.Nd network configuration data base
.Sh SYNOPSIS
.Pa /etc/netconfig
.Sh DESCRIPTION
The
.Nm
file defines a list of
.Dq transport names ,
describing their semantics and protocol.
In
.Fx ,
this file is only used by the RPC library code.
.Pp
Entries have the following format:
.Pp
.Ar network_id semantics flags family protoname device libraries
.Pp
Entries consist of the following fields:
.Bl -tag -width network_id
.It Ar network_id
The name of the transport described.
.It Ar semantics
Describes the semantics of the transport.
This can be one of:
.Bl -tag -width tpi_cots_ord -offset indent
.It Sy tpi_clts
Connectionless transport.
.It Sy tpi_cots
Connection-oriented transport
.It Sy tpi_cots_ord
Connection-oriented, ordered transport.
.It Sy tpi_raw
A raw connection.
.El
.It Ar flags
This field is either blank (specified by
.Dq Li - ) ,
or contains a
.Dq Li v ,
meaning visible to the
.Xr getnetconfig 3
function.
.It Ar family
The protocol family of the transport.
This is currently one of:
.Bl -tag -width loopback -offset indent
.It Sy inet6
The IPv6
.Pq Dv PF_INET6
family of protocols.
.It Sy inet
The IPv4
.Pq Dv PF_INET
family of protocols.
.It Sy loopback
The
.Dv PF_LOCAL
protocol family.
.El
.It Ar protoname
The name of the protocol used for this transport.
Can currently be either
.Sy udp ,
.Sy tcp
or empty.
.It Ar device
This field is always empty in
.Fx .
.It Ar libraries
This field is always empty in
.Fx .
.El
.Pp
The order of entries in this file will determine which transport will
be preferred by the RPC library code, given a match on a specified
network type.
For example, if a sample network config file would look like this:
.Bd -literal -offset indent
udp6 tpi_clts v inet6 udp - -
tcp6 tpi_cots_ord v inet6 tcp - -
udp tpi_clts v inet udp - -
tcp tpi_cots_ord v inet tcp - -
rawip tpi_raw - inet - - -
local tpi_cots_ord - loopback - - -
.Ed
.Pp
then using the network type
.Sy udp
in calls to the RPC library function (see
.Xr rpc 3 )
will make the code first try
.Sy udp6 ,
and then
.Sy udp .
.Pp
.Xr getnetconfig 3
and associated functions will parse this file and return structures of
the following format:
.Bd -literal
struct netconfig {
char *nc_netid; /* Network ID */
unsigned long nc_semantics; /* Semantics (see below) */
unsigned long nc_flag; /* Flags (see below) */
char *nc_protofmly; /* Protocol family */
char *nc_proto; /* Protocol name */
char *nc_device; /* Network device pathname (unused) */
unsigned long nc_nlookups; /* Number of lookup libs (unused) */
char **nc_lookups; /* Names of the libraries (unused) */
unsigned long nc_unused[9]; /* reserved */
};
.Ed
.Sh FILES
.Bl -tag -width /etc/netconfig -compact
.It Pa /etc/netconfig
.El
.Sh SEE ALSO
.Xr getnetconfig 3 ,
.Xr getnetpath 3

52
libtirpc/man/publickey.3t Normal file
View file

@ -0,0 +1,52 @@
.\" @(#)publickey.3r 2.1 88/08/07 4.0 RPCSRC
.\"
.Dd October 6, 1987
.Dt PUBLICKEY 3
.Os
.Sh NAME
.Nm publickey , getpublickey , getsecretkey
.Nd "get public or secret key"
.Sh LIBRARY
.Lb librpcsvc
.Sh SYNOPSIS
.In rpc/rpc.h
.In rpc/key_prot.h
.Ft int
.Fo getpublickey
.Fa "char netname[MAXNETNAMELEN+1]"
.Fa "char publickey[HEXKEYBYTES+1]"
.Fc
.Ft int
.Fo getsecretkey
.Fa "char netname[MAXNETNAMELEN+1]"
.Fa "char secretkey[HEXKEYBYTES+1]"
.Fa "char *passwd"
.Fc
.Sh DESCRIPTION
These routines are used to get public and secret keys from the
.Tn YP
database.
The
.Fn getsecretkey
function
has an extra argument,
.Fa passwd ,
which is used to decrypt the encrypted secret key stored in the database.
Both routines return 1 if they are successful in finding the key, 0 otherwise.
The keys are returned as
.Dv NULL Ns \-terminated ,
hexadecimal strings.
If the password supplied to
.Fn getsecretkey
fails to decrypt the secret key, the routine will return 1 but the
.Fa secretkey
argument will be a
.Dv NULL
string
.Pq Dq .
.Sh SEE ALSO
.Xr publickey 5
.Pp
.%T "RPC Programmer's Manual"
in
.Pa /usr/share/doc/psd/23.rpc .

41
libtirpc/man/publickey.5 Normal file
View file

@ -0,0 +1,41 @@
.\" @(#)publickey.5 2.1 88/08/07 4.0 RPCSRC; from 1.6 88/02/29 SMI;
.Dd October 19, 1987
.Dt PUBLICKEY 5
.Os
.Sh NAME
.Nm publickey
.Nd "public key database"
.Sh SYNOPSIS
.Pa /etc/publickey
.Sh DESCRIPTION
.Pa /etc/publickey
is the public key database used for secure
RPC (Remote Procedure Calls).
Each entry in
the database consists of a network user
name (which may either refer to
a user or a hostname), followed by the user's
public key (in hex
notation), a colon, and then the user's
secret key encrypted with
its login password (also in hex notation).
.Pp
This file is altered either by the user through the
.Xr chkey 1
command or by the system administrator through the
.Xr newkey 8
command.
The file
.Pa /etc/publickey
should only contain data on the
.Tn NIS
master machine, where it
is converted into the
.Tn NIS
database
.Pa publickey.byname .
.Sh SEE ALSO
.Xr chkey 1 ,
.Xr publickey 3 ,
.Xr newkey 8 ,
.Xr ypupdated 8

515
libtirpc/man/rpc.3t Normal file
View file

@ -0,0 +1,515 @@
.\" @(#)rpc.3n 1.31 93/08/31 SMI; from SVr4
.\" Copyright 1989 AT&T
.Dd May 7, 1993
.Dt RPC 3
.Os
.Sh NAME
.Nm rpc
.Nd library routines for remote procedure calls
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/rpc.h
.In netconfig.h
.Sh DESCRIPTION
These
routines allow C language programs to make procedure
calls on other machines across a network.
First, the client sends a request to the server.
On receipt of the request, the server calls a dispatch routine
to perform the requested service, and then sends back a reply.
.Pp
All
RPC routines require the header
.In rpc/rpc.h .
Routines that take a
.Vt "struct netconfig"
also require that
.In netconfig.h
be included.
.Sh Nettype
Some of the high-level
RPC interface routines take a
.Fa nettype
string as one of the arguments
(for example,
.Fn clnt_create ,
.Fn svc_create ,
.Fn rpc_reg ,
.Fn rpc_call ) .
This string defines a class of transports which can be used
for a particular application.
.Pp
The
.Fa nettype
argument
can be one of the following:
.Bl -tag -width datagram_v
.It netpath
Choose from the transports which have been
indicated by their token names in the
.Ev NETPATH
environment variable.
.Ev NETPATH
is unset or
.Dv NULL ,
it defaults to
.Qq visible .
.Qq netpath
is the default
.Fa nettype .
.It visible
Choose the transports which have the visible flag (v)
set in the
.Pa /etc/netconfig
file.
.It circuit_v
This is same as
.Qq visible
except that it chooses only the connection oriented transports
(semantics
.Qq tpi_cots
or
.Qq tpi_cots_ord )
from the entries in the
.Pa /etc/netconfig
file.
.It datagram_v
This is same as
.Qq visible
except that it chooses only the connectionless datagram transports
(semantics
.Qq tpi_clts )
from the entries in the
.Pa /etc/netconfig
file.
.It circuit_n
This is same as
.Qq netpath
except that it chooses only the connection oriented datagram transports
(semantics
.Qq tpi_cots
or
.Qq tpi_cots_ord ) .
.It datagram_n
This is same as
.Qq netpath
except that it chooses only the connectionless datagram transports
(semantics
.Qq tpi_clts ) .
.It udp
This refers to Internet UDP, both version 4 and 6.
.It tcp
This refers to Internet TCP, both version 4 and 6.
.El
.Pp
If
.Fa nettype
is
.Dv NULL ,
it defaults to
.Qq netpath .
The transports are tried in left to right order in the
.Ev NETPATH
variable or in top to down order in the
.Pa /etc/netconfig
file.
.Sh Derived Types
The derived types used in the RPC interfaces are defined as follows:
.Bd -literal
typedef u_int32_t rpcprog_t;
typedef u_int32_t rpcvers_t;
typedef u_int32_t rpcproc_t;
typedef u_int32_t rpcprot_t;
typedef u_int32_t rpcport_t;
typedef int32_t rpc_inline_t;
.Ed
.Sh "Data Structures"
Some of the data structures used by the
RPC package are shown below.
.Sh "The AUTH Structure"
.Bd -literal
/*
* Authentication info. Opaque to client.
*/
struct opaque_auth {
enum_t oa_flavor; /* flavor of auth */
caddr_t oa_base; /* address of more auth stuff */
u_int oa_length; /* not to exceed MAX_AUTH_BYTES */
};
/*
* Auth handle, interface to client side authenticators.
*/
typedef struct {
struct opaque_auth ah_cred;
struct opaque_auth ah_verf;
struct auth_ops {
void (*ah_nextverf)(\|);
int (*ah_marshal)(\|); /* nextverf & serialize */
int (*ah_validate)(\|); /* validate verifier */
int (*ah_refresh)(\|); /* refresh credentials */
void (*ah_destroy)(\|); /* destroy this structure */
} *ah_ops;
caddr_t ah_private;
} AUTH;
.Ed
.Sh "The CLIENT Structure"
.Bd -literal
/*
* Client rpc handle.
* Created by individual implementations.
* Client is responsible for initializing auth.
*/
typedef struct {
AUTH *cl_auth; /* authenticator */
struct clnt_ops {
enum clnt_stat (*cl_call)(); /* call remote procedure */
void (*cl_abort)(); /* abort a call */
void (*cl_geterr)(); /* get specific error code */
bool_t (*cl_freeres)(); /* frees results */
void (*cl_destroy)(); /* destroy this structure */
bool_t (*cl_control)(); /* the ioctl() of rpc */
} *cl_ops;
caddr_t cl_private; /* private stuff */
char *cl_netid; /* network identifier */
char *cl_tp; /* device name */
} CLIENT;
.Ed
.Sh "The SVCXPRT structure"
.Bd -literal
enum xprt_stat {
XPRT_DIED,
XPRT_MOREREQS,
XPRT_IDLE
};
/*
* Server side transport handle
*/
typedef struct {
int xp_fd; /* file descriptor for the server handle */
u_short xp_port; /* obsolete */
const struct xp_ops {
bool_t (*xp_recv)(); /* receive incoming requests */
enum xprt_stat (*xp_stat)(); /* get transport status */
bool_t (*xp_getargs)(); /* get arguments */
bool_t (*xp_reply)(); /* send reply */
bool_t (*xp_freeargs)(); /* free mem allocated for args */
void (*xp_destroy)(); /* destroy this struct */
} *xp_ops;
int xp_addrlen; /* length of remote addr. Obsolete */
struct sockaddr_in xp_raddr; /* Obsolete */
const struct xp_ops2 {
bool_t (*xp_control)(); /* catch-all function */
} *xp_ops2;
char *xp_tp; /* transport provider device name */
char *xp_netid; /* network identifier */
struct netbuf xp_ltaddr; /* local transport address */
struct netbuf xp_rtaddr; /* remote transport address */
struct opaque_auth xp_verf; /* raw response verifier */
caddr_t xp_p1; /* private: for use by svc ops */
caddr_t xp_p2; /* private: for use by svc ops */
caddr_t xp_p3; /* private: for use by svc lib */
int xp_type /* transport type */
} SVCXPRT;
.Ed
.Sh "The svc_reg structure"
.Bd -literal
struct svc_req {
rpcprog_t rq_prog; /* service program number */
rpcvers_t rq_vers; /* service protocol version */
rpcproc_t rq_proc; /* the desired procedure */
struct opaque_auth rq_cred; /* raw creds from the wire */
caddr_t rq_clntcred; /* read only cooked cred */
SVCXPRT *rq_xprt; /* associated transport */
};
.Ed
.Sh "The XDR structure"
.Bd -literal
/*
* XDR operations.
* XDR_ENCODE causes the type to be encoded into the stream.
* XDR_DECODE causes the type to be extracted from the stream.
* XDR_FREE can be used to release the space allocated by an XDR_DECODE
* request.
*/
enum xdr_op {
XDR_ENCODE=0,
XDR_DECODE=1,
XDR_FREE=2
};
/*
* This is the number of bytes per unit of external data.
*/
#define BYTES_PER_XDR_UNIT (4)
#define RNDUP(x) ((((x) + BYTES_PER_XDR_UNIT - 1) /
BYTES_PER_XDR_UNIT) \e * BYTES_PER_XDR_UNIT)
/*
* A xdrproc_t exists for each data type which is to be encoded or
* decoded. The second argument to the xdrproc_t is a pointer to
* an opaque pointer. The opaque pointer generally points to a
* structure of the data type to be decoded. If this points to 0,
* then the type routines should allocate dynamic storage of the
* appropriate size and return it.
* bool_t (*xdrproc_t)(XDR *, caddr_t *);
*/
typedef bool_t (*xdrproc_t)();
/*
* The XDR handle.
* Contains operation which is being applied to the stream,
* an operations vector for the particular implementation
*/
typedef struct {
enum xdr_op x_op; /* operation; fast additional param */
struct xdr_ops {
bool_t (*x_getlong)(); /* get a long from underlying stream */
bool_t (*x_putlong)(); /* put a long to underlying stream */
bool_t (*x_getbytes)(); /* get bytes from underlying stream */
bool_t (*x_putbytes)(); /* put bytes to underlying stream */
u_int (*x_getpostn)(); /* returns bytes off from beginning */
bool_t (*x_setpostn)(); /* lets you reposition the stream */
long * (*x_inline)(); /* buf quick ptr to buffered data */
void (*x_destroy)(); /* free privates of this xdr_stream */
} *x_ops;
caddr_t x_public; /* users' data */
caddr_t x_private; /* pointer to private data */
caddr_t x_base; /* private used for position info */
u_int x_handy; /* extra private word */
} XDR;
/*
* The netbuf structure. This structure is defined in <xti.h> on SysV
* systems, but NetBSD / FreeBSD do not use XTI.
*
* Usually, buf will point to a struct sockaddr, and len and maxlen
* will contain the length and maximum length of that socket address,
* respectively.
*/
struct netbuf {
unsigned int maxlen;
unsigned int len;
void *buf;
};
/*
* The format of the address and options arguments of the XTI t_bind call.
* Only provided for compatibility, it should not be used other than
* as an argument to svc_tli_create().
*/
struct t_bind {
struct netbuf addr;
unsigned int qlen;
};
.Ed
.Sh "Index to Routines"
The following table lists RPC routines and the manual reference
pages on which they are described:
.Pp
.Bl -tag -width "authunix_create_default()" -compact
.It Em "RPC Routine"
.Em "Manual Reference Page"
.Pp
.It Fn auth_destroy
.Xr rpc_clnt_auth 3
.It Fn authdes_create
.Xr rpc_soc 3
.It Fn authnone_create
.Xr rpc_clnt_auth 3
.It Fn authsys_create
.Xr rpc_clnt_auth 3
.It Fn authsys_create_default
.Xr rpc_clnt_auth 3
.It Fn authunix_create
.Xr rpc_soc 3
.It Fn authunix_create_default
.Xr rpc_soc 3
.It Fn callrpc
.Xr rpc_soc 3
.It Fn clnt_broadcast
.Xr rpc_soc 3
.It Fn clnt_call
.Xr rpc_clnt_calls 3
.It Fn clnt_control
.Xr rpc_clnt_create 3
.It Fn clnt_create
.Xr rpc_clnt_create 3
.It Fn clnt_create_timed
.Xr rpc_clnt_create 3
.It Fn clnt_create_vers
.Xr rpc_clnt_create 3
.It Fn clnt_create_vers_timed
.Xr rpc_clnt_create 3
.It Fn clnt_destroy
.Xr rpc_clnt_create 3
.It Fn clnt_dg_create
.Xr rpc_clnt_create 3
.It Fn clnt_freeres
.Xr rpc_clnt_calls 3
.It Fn clnt_geterr
.Xr rpc_clnt_calls 3
.It Fn clnt_pcreateerror
.Xr rpc_clnt_create 3
.It Fn clnt_perrno
.Xr rpc_clnt_calls 3
.It Fn clnt_perror
.Xr rpc_clnt_calls 3
.It Fn clnt_raw_create
.Xr rpc_clnt_create 3
.It Fn clnt_spcreateerror
.Xr rpc_clnt_create 3
.It Fn clnt_sperrno
.Xr rpc_clnt_calls 3
.It Fn clnt_sperror
.Xr rpc_clnt_calls 3
.It Fn clnt_tli_create
.Xr rpc_clnt_create 3
.It Fn clnt_tp_create
.Xr rpc_clnt_create 3
.It Fn clnt_tp_create_timed
.Xr rpc_clnt_create 3
.It Fn clnt_udpcreate
.Xr rpc_soc 3
.It Fn clnt_vc_create
.Xr rpc_clnt_create 3
.It Fn clntraw_create
.Xr rpc_soc 3
.It Fn clnttcp_create
.Xr rpc_soc 3
.It Fn clntudp_bufcreate
.Xr rpc_soc 3
.It Fn get_myaddress
.Xr rpc_soc 3
.It Fn pmap_getmaps
.Xr rpc_soc 3
.It Fn pmap_getport
.Xr rpc_soc 3
.It Fn pmap_rmtcall
.Xr rpc_soc 3
.It Fn pmap_set
.Xr rpc_soc 3
.It Fn pmap_unset
.Xr rpc_soc 3
.It Fn registerrpc
.Xr rpc_soc 3
.It Fn rpc_broadcast
.Xr rpc_clnt_calls 3
.It Fn rpc_broadcast_exp
.Xr rpc_clnt_calls 3
.It Fn rpc_call
.Xr rpc_clnt_calls 3
.It Fn rpc_reg
.Xr rpc_svc_calls 3
.It Fn svc_create
.Xr rpc_svc_create 3
.It Fn svc_destroy
.Xr rpc_svc_create 3
.It Fn svc_dg_create
.Xr rpc_svc_create 3
.It Fn svc_dg_enablecache
.Xr rpc_svc_calls 3
.It Fn svc_fd_create
.Xr rpc_svc_create 3
.It Fn svc_fds
.Xr rpc_soc 3
.It Fn svc_freeargs
.Xr rpc_svc_reg 3
.It Fn svc_getargs
.Xr rpc_svc_reg 3
.It Fn svc_getcaller
.Xr rpc_soc 3
.It Fn svc_getreq
.Xr rpc_soc 3
.It Fn svc_getreqset
.Xr rpc_svc_calls 3
.It Fn svc_getrpccaller
.Xr rpc_svc_calls 3
.It Fn svc_kerb_reg
.Xr kerberos_rpc 3
.It Fn svc_raw_create
.Xr rpc_svc_create 3
.It Fn svc_reg
.Xr rpc_svc_calls 3
.It Fn svc_register
.Xr rpc_soc 3
.It Fn svc_run
.Xr rpc_svc_reg 3
.It Fn svc_sendreply
.Xr rpc_svc_reg 3
.It Fn svc_tli_create
.Xr rpc_svc_create 3
.It Fn svc_tp_create
.Xr rpc_svc_create 3
.It Fn svc_unreg
.Xr rpc_svc_calls 3
.It Fn svc_unregister
.Xr rpc_soc 3
.It Fn svc_vc_create
.Xr rpc_svc_create 3
.It Fn svcerr_auth
.Xr rpc_svc_err 3
.It Fn svcerr_decode
.Xr rpc_svc_err 3
.It Fn svcerr_noproc
.Xr rpc_svc_err 3
.It Fn svcerr_noprog
.Xr rpc_svc_err 3
.It Fn svcerr_progvers
.Xr rpc_svc_err 3
.It Fn svcerr_systemerr
.Xr rpc_svc_err 3
.It Fn svcerr_weakauth
.Xr rpc_svc_err 3
.It Fn svcfd_create
.Xr rpc_soc 3
.It Fn svcraw_create
.Xr rpc_soc 3
.It Fn svctcp_create
.Xr rpc_soc 3
.It Fn svcudp_bufcreate
.Xr rpc_soc 3
.It Fn svcudp_create
.Xr rpc_soc 3
.It Fn xdr_accepted_reply
.Xr rpc_xdr 3
.It Fn xdr_authsys_parms
.Xr rpc_xdr 3
.It Fn xdr_authunix_parms
.Xr rpc_soc 3
.It Fn xdr_callhdr
.Xr rpc_xdr 3
.It Fn xdr_callmsg
.Xr rpc_xdr 3
.It Fn xdr_opaque_auth
.Xr rpc_xdr 3
.It Fn xdr_rejected_reply
.Xr rpc_xdr 3
.It Fn xdr_replymsg
.Xr rpc_xdr 3
.It Fn xprt_register
.Xr rpc_svc_calls 3
.It Fn xprt_unregister
.Xr rpc_svc_calls 3
.El
.Sh FILES
.Bl -tag -width /etc/netconfig
.It Pa /etc/netconfig
.El
.Sh SEE ALSO
.Xr getnetconfig 3 ,
.Xr getnetpath 3 ,
.Xr rpcbind 3 ,
.Xr rpc_clnt_auth 3 ,
.Xr rpc_clnt_calls 3 ,
.Xr rpc_clnt_create 3 ,
.Xr rpc_svc_calls 3 ,
.Xr rpc_svc_create 3 ,
.Xr rpc_svc_err 3 ,
.Xr rpc_svc_reg 3 ,
.Xr rpc_xdr 3 ,
.Xr xdr 3 ,
.Xr netconfig 5

57
libtirpc/man/rpc.5 Normal file
View file

@ -0,0 +1,57 @@
.\" @(#)rpc.4 1.17 93/08/30 SMI; from SVr4
.\" Copyright 1989 AT&T
.Dd December 10, 1991
.Dt RPC 5
.Os
.Sh NAME
.Nm rpc
.Nd rpc program number data base
.Sh SYNOPSIS
.Pa /etc/rpc
.Sh DESCRIPTION
The
.Nm
file contains user readable names that
can be used in place of RPC program numbers.
For each RPC program a single line should be present
with the following information:
.Pp
.Bl -enum -compact
.It
name of the RPC program
.It
RPC program number
.It
aliases
.El
.Pp
Items are separated by any number of blanks and/or
tab characters.
A hash
.Pq Dq Li #
indicates the beginning of a comment; characters up to the end of
the line are not interpreted by routines which search the file.
.Sh EXAMPLES
Below is an example of an RPC database:
.Bd -literal
#
# rpc
#
rpcbind 100000 portmap sunrpc portmapper
rusersd 100002 rusers
nfs 100003 nfsprog
mountd 100005 mount showmount
walld 100008 rwall shutdown
sprayd 100012 spray
llockmgr 100020
nlockmgr 100021
status 100024
bootparam 100026
keyserv 100029 keyserver
.Ed
.Sh FILES
.Bl -tag -width /etc/nsswitch.conf -compact
.It Pa /etc/nsswitch.conf
.El
.Sh SEE ALSO
.Xr getrpcent 3

96
libtirpc/man/rpc_clnt_auth.3t Normal file
View file

@ -0,0 +1,96 @@
.\" @(#)rpc_clnt_auth.3n 1.21 93/05/07 SMI; from SVr4
.\" Copyright 1989 AT&T
.\" @(#)rpc_clnt_auth 1.4 89/07/20 SMI;
.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
.\" $NetBSD: rpc_clnt_auth.3,v 1.1 2000/06/03 09:29:50 fvdl Exp $
.\" $FreeBSD: src/lib/libc/rpc/rpc_clnt_auth.3,v 1.5 2002/12/19 09:40:23 ru Exp $
.Dd May 7, 1993
.Dt RPC_CLNT_AUTH 3
.Os
.Sh NAME
.Nm auth_destroy ,
.Nm authnone_create ,
.Nm authsys_create ,
.Nm authsys_create_default
.Nd library routines for client side remote procedure call authentication
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/rpc.h
.Ft "void"
.Fn auth_destroy "AUTH *auth"
.Ft "AUTH *"
.Fn authnone_create "void"
.Ft "AUTH *"
.Fn authsys_create "const char *host" "const uid_t uid" "const gid_t gid" "const int len" "const gid_t *aup_gids"
.Ft "AUTH *"
.Fn authsys_create_default "void"
.Sh DESCRIPTION
These routines are part of the
RPC library that allows C language programs to make procedure
calls on other machines across the network,
with desired authentication.
.Pp
These routines are normally called after creating the
.Vt CLIENT
handle.
The
.Va cl_auth
field of the
.Vt CLIENT
structure should be initialized by the
.Vt AUTH
structure returned by some of the following routines.
The client's authentication information
is passed to the server when the
RPC
call is made.
.Pp
Only the
.Dv NULL
and the
.Dv SYS
style of authentication is discussed here.
.Sh Routines
.Bl -tag -width authsys_create_default()
.It Fn auth_destroy
A function 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 .
.It Fn authnone_create
Create and return an RPC
authentication handle that passes nonusable
authentication information with each remote procedure call.
This is the default authentication used by RPC.
.It Fn authsys_create
Create and return an RPC authentication handle that contains
.Dv AUTH_SYS
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 Fn authsys_create_default
Call
.Fn authsys_create
with the appropriate arguments.
.El
.Sh SEE ALSO
.Xr rpc 3 ,
.Xr rpc_clnt_calls 3 ,
.Xr rpc_clnt_create 3

316
libtirpc/man/rpc_clnt_calls.3t Normal file
View file

@ -0,0 +1,316 @@
.\" @(#)rpc_clnt_calls.3n 1.30 93/08/31 SMI; from SVr4
.\" Copyright 1989 AT&T
.\" @(#)rpc_clnt_calls 1.4 89/07/20 SMI;
.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
.\" $FreeBSD: src/lib/libc/rpc/rpc_clnt_calls.3,v 1.7 2002/12/19 09:40:23 ru Exp $
.Dd May 7, 1993
.Dt RPC_CLNT_CALLS 3
.Os
.Sh NAME
.Nm rpc_clnt_calls ,
.Nm clnt_call ,
.Nm clnt_freeres ,
.Nm clnt_geterr ,
.Nm clnt_perrno ,
.Nm clnt_perror ,
.Nm clnt_sperrno ,
.Nm clnt_sperror ,
.Nm rpc_broadcast ,
.Nm rpc_broadcast_exp ,
.Nm rpc_call
.Nd library routines for client side calls
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/rpc.h
.Ft "enum clnt_stat"
.Fn clnt_call "CLIENT *clnt" "const rpcproc_t procnum" "const xdrproc_t inproc" "const caddr_t in" "const xdrproc_t outproc" "caddr_t out" "const struct timeval tout"
.Ft bool_t
.Fn clnt_freeres "CLIENT *clnt" "const xdrproc_t outproc" "caddr_t out"
.Ft void
.Fn clnt_geterr "const CLIENT * clnt" "struct rpc_err * errp"
.Ft void
.Fn clnt_perrno "const enum clnt_stat stat"
.Ft void
.Fn clnt_perror "CLIENT *clnt" "const char *s"
.Ft "char *"
.Fn clnt_sperrno "const enum clnt_stat stat"
.Ft "char *"
.Fn clnt_sperror "CLIENT *clnt" "const char * s"
.Ft "enum clnt_stat"
.Fo rpc_broadcast
.Fa "const rpcprog_t prognum" "const rpcvers_t versnum"
.Fa "const rpcproc_t procnum" "const xdrproc_t inproc"
.Fa "const caddr_t in" "const xdrproc_t outproc" "caddr_t out"
.Fa "const resultproc_t eachresult" "const char *nettype"
.Fc
.Ft "enum clnt_stat"
.Fo rpc_broadcast_exp
.Fa "const rpcprog_t prognum" "const rpcvers_t versnum"
.Fa "const rpcproc_t procnum" "const xdrproc_t xargs"
.Fa "caddr_t argsp" "const xdrproc_t xresults"
.Fa "caddr_t resultsp" "const resultproc_t eachresult"
.Fa "const int inittime" "const int waittime"
.Fa "const char * nettype"
.Fc
.Ft "enum clnt_stat"
.Fo rpc_call
.Fa "const char *host" "const rpcprog_t prognum"
.Fa "const rpcvers_t versnum" "const rpcproc_t procnum"
.Fa "const xdrproc_t inproc" "const char *in"
.Fa "const xdrproc_t outproc" "char *out" "const char *nettype"
.Fc
.Sh DESCRIPTION
RPC library routines allow C language programs to make procedure
calls on other machines across the network.
First, the client calls a procedure to send a request to the server.
Upon receipt of the request, the server calls a dispatch routine
to perform the requested service, and then sends back a reply.
.Pp
The
.Fn clnt_call ,
.Fn rpc_call ,
and
.Fn rpc_broadcast
routines handle the client side of the procedure call.
The remaining routines deal with error handling in the case of errors.
.Pp
Some of the routines take a
.Vt CLIENT
handle as one of the arguments.
A
.Vt CLIENT
handle can be created by an RPC creation routine such as
.Fn clnt_create
(see
.Xr rpc_clnt_create 3 ) .
.Pp
These routines are safe for use in multithreaded applications.
.Vt CLIENT
handles can be shared between threads, however in this implementation
requests by different threads are serialized (that is, the first request will
receive its results before the second request is sent).
.Sh Routines
See
.Xr rpc 3
for the definition of the
.Vt CLIENT
data structure.
.Bl -tag -width XXXXX
.It Fn clnt_call
A function macro that calls the remote procedure
.Fa procnum
associated with the client handle,
.Fa clnt ,
which is obtained with an RPC
client creation routine such as
.Fn clnt_create
(see
.Xr rpc_clnt_create 3 ) .
The
.Fa inproc
argument
is the XDR function used to encode the procedure's arguments, and
.Fa outproc
is the XDR function used to decode the procedure's results;
.Fa in
is the address of the procedure's argument(s), and
.Fa out
is the address of where to place the result(s).
The
.Fa tout
argument
is the time allowed for results to be returned, which is overridden by
a time-out set explicitly through
.Fn clnt_control ,
see
.Xr rpc_clnt_create 3 .
If the remote call succeeds, the status returned is
.Dv RPC_SUCCESS ,
otherwise an appropriate status is returned.
.It Fn clnt_freeres
A function macro that frees any data allocated by the
RPC/XDR system when it decoded the results of an RPC call.
The
.Fa out
argument
is the address of the results, and
.Fa outproc
is the XDR routine describing the results.
This routine returns 1 if the results were successfully freed,
and 0 otherwise.
.It Fn clnt_geterr
A function macro that copies the error structure out of the client
handle to the structure at address
.Fa errp .
.It Fn clnt_perrno
Print a message to standard error corresponding
to the condition indicated by
.Fa stat .
A newline is appended.
Normally used after a procedure call fails for a routine
for which a client handle is not needed, for instance
.Fn rpc_call .
.It Fn clnt_perror
Print a message to the standard error indicating why an
RPC call failed;
.Fa clnt
is the handle used to do the call.
The message is prepended with string
.Fa s
and a colon.
A newline is appended.
Normally used after a remote procedure call fails
for a routine which requires a client handle,
for instance
.Fn clnt_call .
.It Fn clnt_sperrno
Take the same arguments as
.Fn clnt_perrno ,
but instead of sending a message to the standard error
indicating why an RPC
call failed, return a pointer to a string which contains the message.
The
.Fn clnt_sperrno
function
is normally used instead of
.Fn clnt_perrno
when 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
(see
.Xr printf 3 ) ,
or if a message format different than that supported by
.Fn clnt_perrno
is to be used.
Note:
unlike
.Fn clnt_sperror
and
.Fn clnt_spcreateerror
(see
.Xr rpc_clnt_create 3 ) ,
.Fn clnt_sperrno
does not return pointer to static data so the
result will not get overwritten on each call.
.It Fn clnt_sperror
Like
.Fn clnt_perror ,
except that (like
.Fn clnt_sperrno )
it returns a string instead of printing to standard error.
However,
.Fn clnt_sperror
does not append a newline at the end of the message.
Warning:
returns pointer to a buffer that is overwritten
on each call.
.It Fn rpc_broadcast
Like
.Fn rpc_call ,
except the call message is broadcast to
all the connectionless transports specified by
.Fa nettype .
If
.Fa nettype
is
.Dv NULL ,
it defaults to
.Qq netpath .
Each time it receives a response,
this routine calls
.Fn eachresult ,
whose form is:
.Ft bool_t
.Fn eachresult "caddr_t out" "const struct netbuf * addr" "const struct netconfig * netconf"
where
.Fa out
is the same as
.Fa out
passed to
.Fn rpc_broadcast ,
except that the remote procedure's output is decoded there;
.Fa addr
points to the address of the machine that sent the results, and
.Fa netconf
is the netconfig structure of the transport on which the remote
server responded.
If
.Fn eachresult
returns 0,
.Fn rpc_broadcast
waits for more replies;
otherwise it returns with appropriate status.
Warning:
broadcast file descriptors are limited in size to the
maximum transfer size of that transport.
For Ethernet, this value is 1500 bytes.
The
.Fn rpc_broadcast
function
uses
.Dv AUTH_SYS
credentials by default (see
.Xr rpc_clnt_auth 3 ) .
.It Fn rpc_broadcast_exp
Like
.Fn rpc_broadcast ,
except that the initial timeout,
.Fa inittime
and the maximum timeout,
.Fa waittime
are specified in milliseconds.
The
.Fa inittime
argument
is the initial time that
.Fn rpc_broadcast_exp
waits before resending the request.
After the first resend, the re-transmission interval
increases exponentially until it exceeds
.Fa waittime .
.It Fn rpc_call
Call the remote procedure associated with
.Fa prognum ,
.Fa versnum ,
and
.Fa procnum
on the machine,
.Fa host .
The
.Fa inproc
argument
is used to encode the procedure's arguments, and
.Fa outproc
is used to decode the procedure's results;
.Fa in
is the address of the procedure's argument(s), and
.Fa out
is the address of where to place the result(s).
The
.Fa nettype
argument
can be any of the values listed on
.Xr rpc 3 .
This routine returns
.Dv RPC_SUCCESS
if it succeeds,
or an appropriate status is returned.
Use the
.Fn clnt_perrno
routine to translate failure status into error messages.
Warning:
.Fn rpc_call
uses the first available transport belonging
to the class
.Fa nettype ,
on which it can create a connection.
You do not have control of timeouts or authentication
using this routine.
.El
.Sh SEE ALSO
.Xr printf 3 ,
.Xr rpc 3 ,
.Xr rpc_clnt_auth 3 ,
.Xr rpc_clnt_create 3

514
libtirpc/man/rpc_clnt_create.3t Normal file
View file

@ -0,0 +1,514 @@
.\" @(#)rpc_clnt_create.3n 1.36 93/08/31 SMI; from SVr4
.\" Copyright 1989 AT&T
.\" @(#)rpc_clnt_create 1.5 89/07/24 SMI;
.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
.\" $NetBSD: rpc_clnt_create.3,v 1.2 2000/06/20 00:53:08 fvdl Exp $
.\" $FreeBSD: src/lib/libc/rpc/rpc_clnt_create.3,v 1.12 2003/09/14 13:41:56 ru Exp $
.Dd May 7, 1993
.Dt RPC_CLNT_CREATE 3
.Os
.Sh NAME
.Nm rpc_clnt_create ,
.Nm clnt_control ,
.Nm clnt_create ,
.Nm clnt_create_timed ,
.Nm clnt_create_vers ,
.Nm clnt_create_vers_timed ,
.Nm clnt_destroy ,
.Nm clnt_dg_create ,
.Nm clnt_pcreateerror ,
.Nm clnt_raw_create ,
.Nm clnt_spcreateerror ,
.Nm clnt_tli_create ,
.Nm clnt_tp_create ,
.Nm clnt_tp_create_timed ,
.Nm clnt_vc_create ,
.Nm rpc_createerr
.Nd "library routines for dealing with creation and manipulation of"
.Vt CLIENT
handles
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/rpc.h
.Ft bool_t
.Fn clnt_control "CLIENT *clnt" "const u_int req" "char *info"
.Ft "CLIENT *"
.Fn clnt_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype"
.Ft "CLIENT *"
.Fn clnt_create_timed "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype" "const struct timeval *timeout"
.Ft "CLIENT *"
.Fn clnt_create_vers "const char * host" "const rpcprog_t prognum" "rpcvers_t *vers_outp" "const rpcvers_t vers_low" "const rpcvers_t vers_high" "const char *nettype"
.Ft "CLIENT *"
.Fn clnt_create_vers_timed "const char * host" "const rpcprog_t prognum" "rpcvers_t *vers_outp" "const rpcvers_t vers_low" "const rpcvers_t vers_high" "char *nettype" "const struct timeval *timeout"
.Ft void
.Fn clnt_destroy "CLIENT *clnt"
.Ft "CLIENT *"
.Fn clnt_dg_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz"
.Ft void
.Fn clnt_pcreateerror "const char *s"
.Ft "char *"
.Fn clnt_spcreateerror "const char *s"
.Ft "CLIENT *"
.Fn clnt_raw_create "const rpcprog_t prognum" "const rpcvers_t versnum"
.Ft "CLIENT *"
.Fn clnt_tli_create "const int fildes" "const struct netconfig *netconf" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz"
.Ft "CLIENT *"
.Fn clnt_tp_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf"
.Ft "CLIENT *"
.Fn clnt_tp_create_timed "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "const struct timeval *timeout"
.Ft "CLIENT *"
.Fn clnt_vc_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "u_int sendsz" "u_int recvsz"
.Sh DESCRIPTION
RPC library routines allow C language programs to make procedure
calls on other machines across the network.
First a
.Vt CLIENT
handle is created and then the client calls a procedure to send a
request to the server.
On receipt of the request, the server calls a dispatch routine
to perform the requested service, and then sends a reply.
.Sh Routines
.Bl -tag -width YYYYYYY
.It Fn clnt_control
A function macro 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 connectionless and connection-oriented transports,
the supported values of
.Fa req
and their argument types and what they do are:
.Bl -column "CLSET_FD_NCLOSE" "struct timeval *" "set total timeout"
.It Dv CLSET_TIMEOUT Ta "struct timeval *" Ta "set total timeout"
.It Dv CLGET_TIMEOUT Ta "struct timeval *" Ta "get total timeout"
.El
.Pp
Note:
if you set the timeout using
.Fn clnt_control ,
the timeout argument passed by
.Fn clnt_call
is ignored in all subsequent calls.
.Pp
Note:
If you set the timeout value to 0,
.Fn clnt_control
immediately returns an error
.Pq Dv RPC_TIMEDOUT .
Set the timeout argument to 0 for batching calls.
.Bl -column CLSET_FD_NCLOSE "struct timeval *" "do not close fd on destroy"
.It Dv CLGET_SVC_ADDR Ta "struct netbuf *" Ta "get servers address"
.It Dv CLGET_FD Ta "int *" Ta "get fd from handle"
.It Dv CLSET_FD_CLOSE Ta "void" Ta "close fd on destroy"
.It Dv CLSET_FD_NCLOSE Ta void Ta "don't close fd on destroy"
.It Dv CLGET_VERS Ta "u_int32_t *" Ta "get RPC program version"
.It Dv CLSET_VERS Ta "u_int32_t *" Ta "set RPC program version"
.It Dv CLGET_XID Ta "u_int32_t *" Ta "get XID of previous call"
.It Dv CLSET_XID Ta "u_int32_t *" Ta "set XID of next call"
.El
.Pp
The following operations are valid for connectionless transports only:
.Bl -column CLSET_RETRY_TIMEOUT "struct timeval *" "set total timeout"
.It Dv CLSET_RETRY_TIMEOUT Ta "struct timeval *" Ta "set the retry timeout"
.It Dv CLGET_RETRY_TIMEOUT Ta "struct timeval *" Ta "get the retry timeout"
.It Dv CLSET_CONNECT Ta Vt "int *" Ta use Xr connect 2
.El
.Pp
The retry timeout is the time that RPC
waits for the server to reply before retransmitting the request.
The
.Fn clnt_control
function
returns
.Dv TRUE
on success and
.Dv FALSE
on failure.
.It Fn clnt_create
Generic client creation routine for program
.Fa prognum
and version
.Fa versnum .
The
.Fa host
argument
identifies the name of the remote host where the server
is located.
The
.Fa nettype
argument
indicates the class of transport protocol to use.
The transports are tried in left to right order in
.Ev NETPATH
environment variable or in top to bottom order in
the netconfig database.
The
.Fn clnt_create
function
tries all the transports of the
.Fa nettype
class available from the
.Ev NETPATH
environment variable and the netconfig database,
and chooses the first successful one.
A default timeout is set and can be modified using
.Fn clnt_control .
This routine returns
.Dv NULL
if it fails.
The
.Fn clnt_pcreateerror
routine can be used to print the reason for failure.
.Pp
Note:
.Fn clnt_create
returns a valid client handle even
if the particular version number supplied to
.Fn clnt_create
is not registered with the
.Xr rpcbind 8
service.
This mismatch will be discovered by a
.Fn clnt_call
later (see
.Xr rpc_clnt_calls 3 ) .
.It Fn clnt_create_timed
Generic client creation routine which is similar to
.Fn clnt_create
but which also has the additional argument
.Fa timeout
that specifies the maximum amount of time allowed for
each transport class tried.
In all other respects, the
.Fn clnt_create_timed
call behaves exactly like the
.Fn clnt_create
call.
.It Fn clnt_create_vers
Generic client creation routine which is similar to
.Fn clnt_create
but which also checks for the
version availability.
The
.Fa host
argument
identifies the name of the remote host where the server
is located.
The
.Fa nettype
argument
indicates the class transport protocols to be used.
If the routine is successful it returns a client handle created for
the highest version between
.Fa vers_low
and
.Fa vers_high
that is supported by the server.
The
.Fa vers_outp
argument
is set to this value.
That is, after a successful return
.Fa vers_low
<=
.Fa *vers_outp
<=
.Fa vers_high .
If no version between
.Fa vers_low
and
.Fa vers_high
is supported by the server then the routine fails and returns
.Dv NULL .
A default timeout is set and can be modified using
.Fn clnt_control .
This routine returns
.Dv NULL
if it fails.
The
.Fn clnt_pcreateerror
routine can be used to print the reason for failure.
Note:
.Fn clnt_create
returns a valid client handle even
if the particular version number supplied to
.Fn clnt_create
is not registered with the
.Xr rpcbind 8
service.
This mismatch will be discovered by a
.Fn clnt_call
later (see
.Xr rpc_clnt_calls 3 ) .
However,
.Fn clnt_create_vers
does this for you and returns a valid handle
only if a version within
the range supplied is supported by the server.
.It Fn clnt_create_vers_timed
Generic client creation routine which is similar to
.Fn clnt_create_vers
but which also has the additional argument
.Fa timeout
that specifies the maximum amount of time allowed for
each transport class tried.
In all other respects, the
.Fn clnt_create_vers_timed
call behaves exactly like the
.Fn clnt_create_vers
call.
.It Fn clnt_destroy
A function macro that destroys the client's 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 RPC library opened the associated file descriptor, or
.Dv CLSET_FD_CLOSE
was set using
.Fn clnt_control ,
the file descriptor will be closed.
The caller should call
.Fn auth_destroy "clnt->cl_auth"
(before calling
.Fn clnt_destroy )
to destroy the associated
.Vt AUTH
structure (see
.Xr rpc_clnt_auth 3 ) .
.It Fn clnt_dg_create
This routine creates an RPC client for the remote program
.Fa prognum
and version
.Fa versnum ;
the client uses a connectionless transport.
The remote program is located at address
.Fa svcaddr .
The
.Fa fildes
argument
is an open and bound file descriptor.
This routine will resend the call message in intervals of
15 seconds until a response is received or until the
call times out.
The total time for the call to time out is specified by
.Fn clnt_call
(see
.Fn clnt_call
in
.Xr rpc_clnt_calls 3 ) .
The retry time out and the total time out periods can
be changed using
.Fn clnt_control .
The user may set the size of the send and receive
buffers with the
.Fa sendsz
and
.Fa recvsz
arguments;
values of 0 choose suitable defaults.
This routine returns
.Dv NULL
if it fails.
.It Fn clnt_pcreateerror
Print a message to standard error indicating
why a client RPC handle could not be created.
The message is prepended with the string
.Fa s
and a colon, and appended with a newline.
.It Fn clnt_spcreateerror
Like
.Fn clnt_pcreateerror ,
except that it returns a string
instead of printing to the standard error.
A newline is not appended to the message in this case.
Warning:
returns a pointer to a buffer that is overwritten
on each call.
.It Fn clnt_raw_create
This routine creates an RPC
client handle for the remote program
.Fa prognum
and version
.Fa versnum .
The transport used to pass messages to the service is
a buffer within the process's address space,
so the corresponding RPC
server should live in the same address space;
(see
.Fn svc_raw_create
in
.Xr rpc_svc_create 3 ) .
This allows simulation of RPC and measurement of
RPC overheads, such as round trip times,
without any kernel or networking interference.
This routine returns
.Dv NULL
if it fails.
The
.Fn clnt_raw_create
function
should be called after
.Fn svc_raw_create .
.It Fn clnt_tli_create
This routine creates an RPC
client handle for the remote program
.Fa prognum
and version
.Fa versnum .
The remote program is located at address
.Fa svcaddr .
If
.Fa svcaddr
is
.Dv NULL
and it is connection-oriented, it is assumed that the file descriptor
is connected.
For connectionless transports, if
.Fa svcaddr
is
.Dv NULL ,
.Dv RPC_UNKNOWNADDR
error is set.
The
.Fa fildes
argument
is a file descriptor which may be open, bound and connected.
If it is
.Dv RPC_ANYFD ,
it opens a file descriptor on the transport specified by
.Fa netconf .
If
.Fa fildes
is
.Dv RPC_ANYFD
and
.Fa netconf
is
.Dv NULL ,
a
.Dv RPC_UNKNOWNPROTO
error is set.
If
.Fa fildes
is unbound, then it will attempt to bind the descriptor.
The user may specify the size of the buffers with the
.Fa sendsz
and
.Fa recvsz
arguments;
values of 0 choose suitable defaults.
Depending upon the type of the transport (connection-oriented
or connectionless),
.Fn clnt_tli_create
calls appropriate client creation routines.
This routine returns
.Dv NULL
if it fails.
The
.Fn clnt_pcreateerror
routine can be used to print the reason for failure.
The remote rpcbind
service (see
.Xr rpcbind 8 )
is not consulted for the address of the remote
service.
.It Fn clnt_tp_create
Like
.Fn clnt_create
except
.Fn clnt_tp_create
tries only one transport specified through
.Fa netconf .
The
.Fn clnt_tp_create
function
creates a client handle for the program
.Fa prognum ,
the version
.Fa versnum ,
and for the transport specified by
.Fa netconf .
Default options are set,
which can be changed using
.Fn clnt_control
calls.
The remote rpcbind service on the host
.Fa host
is consulted for the address of the remote service.
This routine returns
.Dv NULL
if it fails.
The
.Fn clnt_pcreateerror
routine can be used to print the reason for failure.
.It Fn clnt_tp_create_timed
Like
.Fn clnt_tp_create
except
.Fn clnt_tp_create_timed
has the extra argument
.Fa timeout
which specifies the maximum time allowed for
the creation attempt to succeed.
In all other respects, the
.Fn clnt_tp_create_timed
call behaves exactly like the
.Fn clnt_tp_create
call.
.It Fn clnt_vc_create
This routine creates an RPC
client for the remote program
.Fa prognum
and version
.Fa versnum ;
the client uses a connection-oriented transport.
The remote program is located at address
.Fa svcaddr .
The
.Fa fildes
argument
is an open and bound file descriptor.
The user may specify the size of the send and receive buffers
with the
.Fa sendsz
and
.Fa recvsz
arguments;
values of 0 choose suitable defaults.
This routine returns
.Dv NULL
if it fails.
The address
.Fa svcaddr
should not be
.Dv NULL
and should point to the actual address of the remote program.
The
.Fn clnt_vc_create
function
does not consult the remote rpcbind service for this information.
.It Xo
.Vt "struct rpc_createerr" Va rpc_createerr ;
.Xc
A global variable whose value is set by any RPC
client handle creation routine
that fails.
It is used by the routine
.Fn clnt_pcreateerror
to print the reason for the failure.
.El
.Sh SEE ALSO
.Xr rpc 3 ,
.Xr rpc_clnt_auth 3 ,
.Xr rpc_clnt_calls 3 ,
.Xr rpcbind 8

279
libtirpc/man/rpc_secure.3t Normal file
View file

@ -0,0 +1,279 @@
.\" @(#)rpc_secure.3n 2.1 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI
.\" $FreeBSD: src/lib/libc/rpc/rpc_secure.3,v 1.14 2002/12/19 09:40:23 ru Exp $
.\"
.Dd February 16, 1988
.Dt RPC 3
.Os
.Sh NAME
.Nm rpc_secure
.Nd library routines for secure remote procedure calls
.Sh SYNOPSIS
.In rpc/rpc.h
.Ft AUTH *
.Fo authdes_create
.Fa "char *name"
.Fa "unsigned window"
.Fa "struct sockaddr *addr"
.Fa "des_block *ckey"
.Fc
.Ft int
.Fn authdes_getucred "struct authdes_cred *adc" "uid_t *uid" "gid_t *gid" "int *grouplen" "gid_t *groups"
.Ft int
.Fn getnetname "char *name"
.Ft int
.Fn host2netname "char *name" "const char *host" "const char *domain"
.Ft int
.Fn key_decryptsession "const char *remotename" "des_block *deskey"
.Ft int
.Fn key_encryptsession "const char *remotename" "des_block *deskey"
.Ft int
.Fn key_gendes "des_block *deskey"
.Ft int
.Fn key_setsecret "const char *key"
.Ft int
.Fn netname2host "char *name" "char *host" "int hostlen"
.Ft int
.Fn netname2user "char *name" "uid_t *uidp" "gid_t *gidp" "int *gidlenp" "gid_t *gidlist"
.Ft int
.Fn user2netname "char *name" "const uid_t uid" "const char *domain"
.Sh DESCRIPTION
These routines are part of the
.Tn RPC
library. They implement
.Tn DES
Authentication. See
.Xr rpc 3
for further details about
.Tn RPC .
.Pp
The
.Fn authdes_create
is the first of two routines which interface to the
.Tn RPC
secure authentication system, known as
.Tn DES
authentication.
The second is
.Fn authdes_getucred ,
below.
.Pp
Note: the keyserver daemon
.Xr keyserv 8
must be running for the
.Tn DES
authentication system to work.
.Pp
The
.Fn authdes_create
function,
used on the client side, returns an authentication handle that
will enable the use of the secure authentication system.
The first argument
.Fa name
is the network name, or
.Fa netname ,
of the owner of the server process.
This field usually
represents a
.Fa hostname
derived from the utility routine
.Fn host2netname ,
but could also represent a user name using
.Fn user2netname .
The second field is window on the validity of
the client credential, given in seconds. A small
window is more secure than a large one, but choosing
too small of a window will increase the frequency of
resynchronizations because of clock drift.
The third
argument
.Fa addr
is optional. If it is
.Dv NULL ,
then the authentication system will assume
that the local clock is always in sync with the server's
clock, and will not attempt resynchronizations.
If an address
is supplied, however, then the system will use the address
for consulting the remote time service whenever
resynchronization
is required.
This argument is usually the
address of the
.Tn RPC
server itself.
The final argument
.Fa ckey
is also optional. If it is
.Dv NULL ,
then the authentication system will
generate a random
.Tn DES
key to be used for the encryption of credentials.
If it is supplied, however, then it will be used instead.
.Pp
The
.Fn authdes_getucred
function,
the second of the two
.Tn DES
authentication routines,
is used on the server side for converting a
.Tn DES
credential, which is
operating system independent, into a
.Ux
credential.
This routine differs from utility routine
.Fn netname2user
in that
.Fn authdes_getucred
pulls its information from a cache, and does not have to do a
Yellow Pages lookup every time it is called to get its information.
.Pp
The
.Fn getnetname
function
installs the unique, operating-system independent netname of
the
caller in the fixed-length array
.Fa name .
Returns
.Dv TRUE
if it succeeds and
.Dv FALSE
if it fails.
.Pp
The
.Fn host2netname
function
converts from a domain-specific hostname to an
operating-system independent netname.
Returns
.Dv TRUE
if it succeeds and
.Dv FALSE
if it fails.
Inverse of
.Fn netname2host .
.Pp
The
.Fn key_decryptsession
function
is an interface to the keyserver daemon, which is associated
with
.Tn RPC Ns 's
secure authentication system
.Tn ( DES
authentication).
User programs rarely need to call it, or its associated routines
.Fn key_encryptsession ,
.Fn key_gendes
and
.Fn key_setsecret .
System commands such as
.Xr login 1
and the
.Tn RPC
library are the main clients of these four routines.
.Pp
The
.Fn key_decryptsession
function
takes a server netname and a
.Tn DES
key, and decrypts the key by
using the public key of the server and the secret key
associated with the effective uid of the calling process. It
is the inverse of
.Fn key_encryptsession .
.Pp
The
.Fn key_encryptsession
function
is a keyserver interface routine.
It
takes a server netname and a des key, and encrypts
it using the public key of the server and the secret key
associated with the effective uid of the calling process. It
is the inverse of
.Fn key_decryptsession .
.Pp
The
.Fn key_gendes
function
is a keyserver interface routine.
It
is used to ask the keyserver for a secure conversation key.
Choosing one
.Qq random
is usually not good enough,
because
the common ways of choosing random numbers, such as using the
current time, are very easy to guess.
.Pp
The
.Fn key_setsecret
function
is a keyserver interface routine.
It is used to set the key for
the effective
.Fa uid
of the calling process.
.Pp
The
.Fn netname2host
function
converts from an operating-system independent netname to a
domain-specific hostname.
Returns
.Dv TRUE
if it succeeds and
.Dv FALSE
if it fails. Inverse of
.Fn host2netname .
.Pp
The
.Fn netname2user
function
converts from an operating-system independent netname to a
domain-specific user ID.
Returns
.Dv TRUE
if it succeeds and
.Dv FALSE
if it fails.
Inverse of
.Fn user2netname .
.Pp
The
.Fn user2netname
function
converts from a domain-specific username to an operating-system
independent netname.
Returns
.Dv TRUE
if it succeeds and
.Dv FALSE
if it fails.
Inverse of
.Fn netname2user .
.Sh SEE ALSO
.Xr rpc 3 ,
.Xr xdr 3 ,
.Xr keyserv 8
.Pp
The following manuals:
.Rs
.%B Remote Procedure Calls: Protocol Specification
.Re
.Rs
.%B Remote Procedure Call Programming Guide
.Re
.Rs
.%B Rpcgen Programming Guide
.Re
.Rs
.%B RPC: Remote Procedure Call Protocol Specification
.%O RFC1050, Sun Microsystems Inc., USC-ISI
.Re

1726
libtirpc/man/rpc_soc.3t Normal file
View file

File diff suppressed because it is too large Load diff

267
libtirpc/man/rpc_svc_calls.3t Normal file
View file

@ -0,0 +1,267 @@
.\" @(#)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.1 2000/06/02 23:11:13 fvdl Exp $
.\" $FreeBSD: src/lib/libc/rpc/rpc_svc_calls.3,v 1.8 2003/09/08 19:57:15 ru 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
.In rpc/rpc.h
.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 cmsgcred *"
.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 "SVCXPRT *xprt" "xdrproc_t outproc" "char *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
.Vt SVCXPRT
data structure.
.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
.Va 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
.Xr rpc_svc_create 3
functions, or using
.Fn xprt_register .
The
.Fn svc_exit
function
has global scope and ends all RPC server activity.
.It Xo
.Vt fd_set Va svc_fdset
.Xc
A global variable reflecting the
RPC server's read file descriptor bit mask; it is suitable as an argument
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.
.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.
.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
.Fa in
argument
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.
.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;
.Fa pollretval
is the return value from
.Xr poll 2
and
.Fa pfdp
is the array of
.Vt 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.
.It 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.
.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 .
.It Fn __svc_getcallercreds
.Em Warning :
this macro is specific to
.Fx
and thus not portable.
This macro returns a pointer to a
.Vt cmsgcred
structure, defined in
.In sys/socket.h ,
identifying the calling client.
This only works if the client is
calling the server over an
.Dv AF_LOCAL
socket.
.It Xo
.Vt struct pollfd Va svc_pollset[FD_SETSIZE] ;
.Xc
.Va svc_pollset
is an array of
.Vt pollfd
structures derived from
.Va svc_fdset[] .
It is suitable as an argument 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.
.It Fn svc_run
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.
.It Fn svc_sendreply
Called by an RPC service's dispatch routine to send the results of a
remote procedure call.
The
.Fa xprt
argument
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 select 2 ,
.Xr rpc 3 ,
.Xr rpc_svc_create 3 ,
.Xr rpc_svc_err 3 ,
.Xr rpc_svc_reg 3

337
libtirpc/man/rpc_svc_create.3t Normal file
View file

@ -0,0 +1,337 @@
.\" @(#)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: src/lib/libc/rpc/rpc_svc_create.3,v 1.7 2003/09/08 19:57:15 ru Exp $
.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
.In rpc/rpc.h
.Ft bool_t
.Fn svc_control "SVCXPRT *svc" "const u_int req" "void *info"
.Ft int
.Fn svc_create "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 "void (*dispatch)(struct svc_req *, 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.
The
.Fa req
argument
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.
The
.Fa info
argument
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.
The
.Fa info
argument
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
The
.Fn svc_create
function
creates server handles for all the transports
belonging to the class
.Fa nettype .
The
.Fa nettype
argument
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
The
.Fn svc_create
function
registers itself with the rpcbind
service (see
.Xr rpcbind 8 ) .
The
.Fa dispatch
function
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.
The
.Fa sendsz
and
.Fa recvsz
arguments
are arguments 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.
The
.Fa sendsz
and
.Fa recvsz
arguments
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.
The
.Fa fildes
argument
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
.In 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 arguments
.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
The
.Fn svc_tp_create
function
creates a server handle for the network
specified by
.Fa netconf ,
and registers itself with the rpcbind service.
The
.Fa dispatch
function
is called when there is a remote procedure call
for the given
.Fa prognum
and
.Fa versnum ;
this requires calling
.Fn svc_run .
The
.Fn svc_tp_create
function
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 arguments
.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

97
libtirpc/man/rpc_svc_err.3t Normal file
View file

@ -0,0 +1,97 @@
.\" @(#)rpc_svc_err.3n 1.23 93/08/31 SMI; from SVr4
.\" Copyright 1989 AT&T
.\" @(#)rpc_svc_err 1.4 89/06/28 SMI;
.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
.\" $NetBSD: rpc_svc_err.3,v 1.1 2000/06/02 23:11:14 fvdl Exp $
.\" $FreeBSD: src/lib/libc/rpc/rpc_svc_err.3,v 1.4 2002/12/19 09:40:23 ru Exp $
.Dd May 3, 1993
.Dt RPC_SVC_ERR 3
.Os
.Sh NAME
.Nm rpc_svc_err ,
.Nm svcerr_auth ,
.Nm svcerr_decode ,
.Nm svcerr_noproc ,
.Nm svcerr_noprog ,
.Nm svcerr_progvers ,
.Nm svcerr_systemerr ,
.Nm svcerr_weakauth
.Nd library routines for server side remote procedure call errors
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/rpc.h
.Ft void
.Fn svcerr_auth "SVCXPRT *xprt" "enum auth_stat why"
.Ft void
.Fn svcerr_decode "SVCXPRT *xprt"
.Ft void
.Fn svcerr_noproc "SVCXPRT *xprt"
.Ft void
.Fn svcerr_noprog "SVCXPRT *xprt"
.Ft void
.Fn svcerr_progvers "SVCXPRT *xprt" "rpcvers_t low_vers" "rpcvers_t high_vers"
.Ft void
.Fn svcerr_systemerr "SVCXPRT *xprt"
.Ft void
.Fn svcerr_weakauth "SVCXPRT *xprt"
.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 can be called by the server side
dispatch function if there is any error in the
transaction with the client.
.Sh Routines
See
.Xr rpc 3
for the definition of the
.Vt SVCXPRT
data structure.
.Bl -tag -width XXXXX
.It Fn svcerr_auth
Called by a service dispatch routine that refuses to perform
a remote procedure call due to an authentication error.
.It Fn svcerr_decode
Called by a service dispatch routine that cannot successfully
decode the remote arguments
(see
.Fn svc_getargs
in
.Xr rpc_svc_reg 3 ) .
.It Fn svcerr_noproc
Called by a service dispatch routine that does not implement
the procedure number that the caller requests.
.It Fn svcerr_noprog
Called when the desired program is not registered with the
RPC package.
Service implementors usually do not need this routine.
.It Fn svcerr_progvers
Called when the desired version of a program is not registered with the
RPC package.
The
.Fa low_vers
argument
is the lowest version number,
and
.Fa high_vers
is the highest version number.
Service implementors usually do not need this routine.
.It Fn svcerr_systemerr
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.
.It Fn svcerr_weakauth
Called by a service dispatch routine that refuses to perform
a remote procedure call due to insufficient (but correct)
authentication arguments.
The routine calls
.Fn svcerr_auth "xprt" "AUTH_TOOWEAK" .
.El
.Sh SEE ALSO
.Xr rpc 3 ,
.Xr rpc_svc_calls 3 ,
.Xr rpc_svc_create 3 ,
.Xr rpc_svc_reg 3

183
libtirpc/man/rpc_svc_reg.3t Normal file
View file

@ -0,0 +1,183 @@
.\" @(#)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 LIBRARY
.Lb libc
.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 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

101
libtirpc/man/rpc_xdr.3t Normal file
View file

@ -0,0 +1,101 @@
.\" @(#)rpc_xdr.3n 1.24 93/08/31 SMI; from SVr4
.\" Copyright 1989 AT&T
.\" @(#)rpc_xdr.new 1.1 89/04/06 SMI;
.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
.\" $FreeBSD: src/lib/libc/rpc/rpc_xdr.3,v 1.3 2001/10/03 16:47:56 bde Exp $
.Dd May 3, 1993
.Dt RPC_XDR 3
.Os
.Sh NAME
.Nm xdr_accepted_reply ,
.Nm xdr_authsys_parms ,
.Nm xdr_callhdr ,
.Nm xdr_callmsg ,
.Nm xdr_opaque_auth ,
.Nm xdr_rejected_reply ,
.Nm xdr_replymsg
.Nd XDR library routines for remote procedure calls
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/rpc.h
.Ft bool_t
.Fn xdr_accepted_reply "XDR *xdrs" "struct accepted_reply *ar"
.Ft bool_t
.Fn xdr_authsys_parms "XDR *xdrs" "struct authsys_parms *aupp"
.Ft bool_t
.Fn xdr_callhdr "XDR *xdrs" "struct rpc_msg *chdr"
.Ft bool_t
.Fn xdr_callmsg "XDR *xdrs" "struct rpc_msg *cmsg"
.Ft bool_t
.Fn xdr_opaque_auth "XDR *xdrs" "struct opaque_auth *ap"
.Ft bool_t
.Fn xdr_rejected_reply "XDR *xdrs" "struct rejected_reply *rr"
.Ft bool_t
.Fn xdr_replymsg "XDR *xdrs" "struct rpc_msg *rmsg"
.Sh DESCRIPTION
These routines are used for describing the
RPC messages in XDR language.
They should normally be used by those who do not
want to use the RPC
package directly.
These routines return
.Dv TRUE
if they succeed,
.Dv FALSE
otherwise.
.Sh Routines
See
.Xr rpc 3
for the definition of the
.Vt XDR
data structure.
.Bl -tag -width XXXXX
.It Fn xdr_accepted_reply
Used to translate between RPC
reply messages and their external representation.
It includes the status of the RPC
call in the XDR language format.
In the case of success, it also includes the call results.
.It Fn xdr_authsys_parms
Used for describing
.Ux
operating system credentials.
It includes machine-name, uid, gid list, etc.
.It Fn xdr_callhdr
Used for describing
RPC
call header messages.
It encodes the static part of the call message header in the
XDR language format.
It includes information such as transaction
ID, RPC version number, program and version number.
.It Fn xdr_callmsg
Used for describing
RPC call messages.
This includes all the RPC
call information such as transaction
ID, RPC version number, program number, version number,
authentication information, etc.
This is normally used by servers to determine information about the client
RPC call.
.It Fn xdr_opaque_auth
Used for describing RPC
opaque authentication information messages.
.It Fn xdr_rejected_reply
Used for describing RPC reply messages.
It encodes the rejected RPC message in the XDR language format.
The message could be rejected either because of version
number mis-match or because of authentication errors.
.It Fn xdr_replymsg
Used for describing RPC
reply messages.
It translates between the
RPC reply message and its external representation.
This reply could be either an acceptance,
rejection or
.Dv NULL .
.El
.Sh SEE ALSO
.Xr rpc 3 ,
.Xr xdr 3

194
libtirpc/man/rpcbind.3t Normal file
View file

@ -0,0 +1,194 @@
.\" @(#)rpcbind.3n 1.25 93/05/07 SMI; from SVr4
.\" Copyright 1989 AT&T
.\" Copyright (c) 1988 Sun Microsystem's, Inc. - All Right's Reserved.
.\" $NetBSD: rpcbind.3,v 1.2 2000/06/03 18:47:28 fvdl Exp $
.\" $FreeBSD: src/lib/libc/rpc/rpcbind.3,v 1.5 2002/12/19 09:40:23 ru Exp $
.Dd May 7, 1993
.Dt RPCBIND 3
.Os
.Sh NAME
.Nm rpcb_getmaps ,
.Nm rpcb_getaddr ,
.Nm rpcb_gettime ,
.Nm rpcb_rmtcall ,
.Nm rpcb_set ,
.Nm rpcb_unset
.Nd library routines for RPC bind service
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In rpc/rpc.h
.Ft "rpcblist *"
.Fn rpcb_getmaps "const struct netconfig *netconf" "const char *host"
.Ft bool_t
.Fn rpcb_getaddr "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "struct netbuf *svcaddr" "const char *host"
.Ft bool_t
.Fn rpcb_gettime "const char *host" "time_t * timep"
.Ft "enum clnt_stat"
.Fn rpcb_rmtcall "const struct netconfig *netconf" "const char *host" "const rpcprog_t prognum, const rpcvers_t versnum" "const rpcproc_t procnum, const xdrproc_t inproc" "const caddr_t in" "const xdrproc_t outproc" "const caddr_t out" "const struct timeval tout, const struct netbuf *svcaddr"
.Ft bool_t
.Fn rpcb_set "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "const struct netbuf *svcaddr"
.Ft bool_t
.Fn rpcb_unset "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf"
.Sh DESCRIPTION
These routines allow client C programs to make procedure
calls to the RPC binder service.
(see
.Xr rpcbind 8 )
maintains a list of mappings between programs
and their universal addresses.
.Sh Routines
.Bl -tag -width XXXXX
.It Fn rpcb_getmaps
An interface to the rpcbind service,
which returns a list of the current
RPC program-to-address mappings on
.Fa host .
It uses the transport specified through
.Fa netconf
to contact the remote rpcbind
service on
.Fa host .
This routine will return
.Dv NULL ,
if the remote rpcbind could not be contacted.
.It Fn rpcb_getaddr
An interface to the rpcbind
service, which finds the address of the service on
.Fa host
that is registered with program number
.Fa prognum ,
version
.Fa versnum ,
and speaks the transport protocol associated with
.Fa netconf .
The address found is returned in
.Fa svcaddr .
The
.Fa svcaddr
argument
should be preallocated.
This routine returns
.Dv TRUE
if it succeeds.
A return value of
.Dv FALSE
means that the mapping does not exist
or that the RPC
system failed to contact the remote
rpcbind service.
In the latter case, the global variable
.Va rpc_createerr
(see
.Xr rpc_clnt_create 3 )
contains the
RPC status.
.It Fn rpcb_gettime
This routine returns the time on
.Fa host
in
.Fa timep .
If
.Fa host
is
.Dv NULL ,
.Fn rpcb_gettime
returns the time on its own machine.
This routine returns
.Dv TRUE
if it succeeds,
.Dv FALSE
if it fails.
The
.Fn rpcb_gettime
function
can be used to synchronize the time between the
client and the remote server.
.It Fn rpcb_rmtcall
An interface to the rpcbind service, which instructs
rpcbind on
.Fa host
to make an RPC
call on your behalf to a procedure on that host.
The
.Fn netconfig
structure should correspond to a connectionless transport.
The
.Fa svcaddr
argument
will be modified to the server's address if the procedure succeeds
(see
.Fn rpc_call
and
.Fn clnt_call
in
.Xr rpc_clnt_calls 3
for the definitions of other arguments).
.Pp
This procedure should normally be used for a
.Dq ping
and nothing else.
This routine allows programs to do lookup and call, all in one step.
.Pp
Note: Even if the server is not running
.Fn rpcb_rmtcall
does not return any error messages to the caller.
In such a case, the caller times out.
.Pp
Note:
.Fn rpcb_rmtcall
is only available for connectionless transports.
.It Fn rpcb_set
An interface to the rpcbind
service, which establishes a mapping between the triple
.Bq Fa prognum , versnum , netconf->nc_netid
and
.Fa svcaddr
on the machine's rpcbind
service.
The value of
.Fa nc_netid
must correspond to a network identifier that is defined by the
netconfig database.
This routine returns
.Dv TRUE
if it succeeds,
.Dv FALSE
otherwise.
(See also
.Fn svc_reg
in
.Xr rpc_svc_calls 3 . )
If there already exists such an entry with rpcbind,
.Fn rpcb_set
will fail.
.It Fn rpcb_unset
An interface to the rpcbind
service, which destroys the mapping between the triple
.Bq Fa prognum , versnum , netconf->nc_netid
and the address on the machine's rpcbind
service.
If
.Fa netconf
is
.Dv NULL ,
.Fn rpcb_unset
destroys all mapping between the triple
.Bq Fa prognum , versnum , No all-transports
and the addresses on the machine's rpcbind service.
This routine returns
.Dv TRUE
if it succeeds,
.Dv FALSE
otherwise.
Only the owner of the service or the super-user can destroy the mapping.
(See also
.Fn svc_unreg
in
.Xr rpc_svc_calls 3 . )
.El
.Sh SEE ALSO
.Xr rpc_clnt_calls 3 ,
.Xr rpc_svc_calls 3 ,
.Xr rpcbind 8 ,
.Xr rpcinfo 8

50
libtirpc/man/rtime.3t Normal file
View file

@ -0,0 +1,50 @@
.\" @(#)rtime.3n 2.1 88/08/08 4.0 RPCSRC; from 1.5 88/02/08 SMI
.\" $FreeBSD: src/lib/libc/rpc/rtime.3,v 1.8 2002/12/19 09:40:23 ru Exp $
.\"
.Dd November 22, 1987
.Dt RTIME 3
.Os
.Sh NAME
.Nm rtime
.Nd "get remote time"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/types.h
.In sys/time.h
.In netinet/in.h
.Ft int
.Fo rtime
.Fa "struct sockaddr_in *addrp"
.Fa "struct timeval *timep"
.Fa "struct timeval *timeout"
.Fc
.Sh DESCRIPTION
The
.Fn rtime
function
consults the Internet Time Server at the address pointed to by
.Fa addrp
and returns the remote time in the
.Vt timeval
struct pointed to by
.Fa timep .
Normally, the
.Tn UDP
protocol is used when consulting the Time Server.
The
.Fa timeout
argument specifies how long the
routine should wait before giving
up when waiting for a reply.
If
.Fa timeout
is specified as
.Dv NULL ,
however, the routine will instead use
.Tn TCP
and block until a reply is received from the time server.
.Sh RETURN VALUES
.Rv -std rtime
.Sh SEE ALSO
.Xr timed 8