[apple/libinfo.git] / rpc.subproj / getrpcent.3

.\" @(#)getrpcent.3n	2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI
.\" $NetBSD: getrpcent.3,v 1.6 1998/02/05 18:49:06 perry Exp $
.\" $FreeBSD: src/lib/libc/rpc/getrpcent.3,v 1.18 2005/01/20 09:17:04 ru Exp $
.\"
.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 DIAGNOSTICS
A
.Dv NULL
pointer is returned on
.Dv EOF
or error.
.Sh SEE ALSO
.Xr rpc 5 ,
.Xr rpcinfo 8 ,
.Xr ypserv 8
.Sh BUGS
.\"All information
.\"is contained in a static area
.\"so it must be copied if it is
.\"to be saved.
The data space used by
these functions is thread-specific; if future use requires the data, it should be
copied before any subsequent calls to these functions overwrite it.
Commit	Line	Data
d49d4c81 A	1	.\" @(#)getrpcent.3n 2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI
	2	.\" $NetBSD: getrpcent.3,v 1.6 1998/02/05 18:49:06 perry Exp $
	3	.\" $FreeBSD: src/lib/libc/rpc/getrpcent.3,v 1.18 2005/01/20 09:17:04 ru Exp $
b3dd680f A	4	.\"
	5	.Dd December 14, 1987
	6	.Dt GETRPCENT 3
	7	.Os
	8	.Sh NAME
	9	.Nm getrpcent ,
	10	.Nm getrpcbyname ,
	11	.Nm getrpcbynumber ,
	12	.Nm endrpcent ,
	13	.Nm setrpcent
	14	.Nd get RPC entry
d49d4c81 A	15	.Sh LIBRARY
d49d4c81 A	16	.Lb libc
b3dd680f	17	.Sh SYNOPSIS
d49d4c81	18	.In rpc/rpc.h
b3dd680f A	19	.Ft struct rpcent *
	20	.Fn getrpcent void
	21	.Ft struct rpcent *
	22	.Fn getrpcbyname "char *name"
	23	.Ft struct rpcent *
	24	.Fn getrpcbynumber "int number"
	25	.Ft void
	26	.Fn setrpcent "int stayopen"
d49d4c81	27	.Ft void
b3dd680f A	28	.Fn endrpcent void
b3dd680f A	29	.Sh DESCRIPTION
d49d4c81	30	The
b3dd680f A	31	.Fn getrpcent ,
	32	.Fn getrpcbyname ,
	33	and
d49d4c81 A	34	.Fn getrpcbynumber
d49d4c81 A	35	functions
b3dd680f A	36	each return a pointer to an object with the
	37	following structure
	38	containing the broken-out
	39	fields of a line in the rpc program number data base,
	40	.Pa /etc/rpc :
d49d4c81	41	.Bd -literal
b3dd680f A	42	struct rpcent {
	43	char r_name; / name of server for this rpc program */
	44	char *r_aliases; / alias list */
	45	long r_number; /* rpc program number */
	46	};
	47	.Ed
	48	.Pp
	49	The members of this structure are:
	50	.Bl -tag -width r_aliases -offset indent
d49d4c81	51	.It Va r_name
b3dd680f	52	The name of the server for this rpc program.
d49d4c81	53	.It Va r_aliases
b3dd680f	54	A zero terminated list of alternate names for the rpc program.
d49d4c81	55	.It Va r_number
b3dd680f A	56	The rpc program number for this service.
	57	.El
	58	.Pp
d49d4c81	59	The
b3dd680f	60	.Fn getrpcent
d49d4c81	61	function
b3dd680f A	62	reads the next line of the file, opening the file if necessary.
b3dd680f A	63	.Pp
d49d4c81	64	The
b3dd680f	65	.Fn setrpcent
d49d4c81 A	66	function
	67	opens and rewinds the file.
	68	If the
b3dd680f A	69	.Fa stayopen
	70	flag is non-zero,
	71	the net data base will not be closed after each call to
d49d4c81	72	.Fn getrpcent
b3dd680f	73	(either directly, or indirectly through one of
d49d4c81	74	the other
b3dd680f A	75	.Dq getrpc
	76	calls).
	77	.Pp
d49d4c81	78	The
b3dd680f	79	.Fn endrpcent
d49d4c81	80	function
b3dd680f A	81	closes the file.
b3dd680f A	82	.Pp
d49d4c81	83	The
b3dd680f A	84	.Fn getrpcbyname
	85	and
	86	.Fn getrpcbynumber
d49d4c81	87	functions
b3dd680f A	88	sequentially search from the beginning
	89	of the file until a matching rpc program name or
	90	program number is found, or until end-of-file is encountered.
	91	.Sh FILES
d49d4c81 A	92	.Bl -tag -width /etc/rpc -compact
	93	.It Pa /etc/rpc
	94	.El
b3dd680f A	95	.Sh DIAGNOSTICS
	96	A
	97	.Dv NULL
d49d4c81	98	pointer is returned on
b3dd680f A	99	.Dv EOF
b3dd680f A	100	or error.
d49d4c81 A	101	.Sh SEE ALSO
	102	.Xr rpc 5 ,
	103	.Xr rpcinfo 8 ,
	104	.Xr ypserv 8
b3dd680f	105	.Sh BUGS
d49d4c81 A	106	.\"All information
	107	.\"is contained in a static area
	108	.\"so it must be copied if it is
	109	.\"to be saved.
	110	The data space used by
	111	these functions is thread-specific; if future use requires the data, it should be
	112	copied before any subsequent calls to these functions overwrite it.