Networking Services Library Functions getrpcbyname(3NSL)
NAME
getrpcbyname, getrpcbynamer, getrpcbynumber,
getrpcbynumberr, getrpcent, getrpcentr, setrpcent,
endrpcent - get RPC entry
SYNOPSIS
cc [ flag ... ] file ... -lnsl [ library ... ]
#include
struct rpcent *getrpcbyname(const char *name);
struct rpcent *getrpcbynamer(const char *name, struct rpcent *result,
char *buffer, int buflen);
struct rpcent *getrpcbynumber(const int number);
struct rpcent *getrpcbynumberr(const int number, struct rpcent *result,
char *buffer, int buflen);
struct rpcent *getrpcent(void);
struct rpcent *getrpcentr(struct rpcent *result, char *buffer,
int buflen);
void setrpcent(const int stayopen);
void endrpcent(void);
DESCRIPTION
These functions are used to obtain entries for RPC (Remote
Procedure Call) services. An entry may come from any of the
sources for rpc specified in the /etc/nsswitch.conf file
(see nsswitch.conf(4)).
getrpcbyname() searches for an entry with the RPC service
name specified by the parameter name.
getrpcbynumber() searches for an entry with the RPC program
number number.
SunOS 5.11 Last change: 20 Feb 1998 1
Networking Services Library Functions getrpcbyname(3NSL)
The functions setrpcent(), getrpcent(), and endrpcent() are
used to enumerate RPC entries from the database.
setrpcent() sets (or resets) the enumeration to the begin-
ning of the set of RPC entries. This function should be
called before the first call to getrpcent(). Calls to
getrpcbyname() and getrpcbynumber() leave the enumeration
position in an indeterminate state. If the stayopen flag
is non-zero, the system may keep allocated resources such as
open file descriptors until a subsequent call to
endrpcent().
Successive calls to getrpcent() return either successive
entries or NUL, indicating the end of the enumeration.
endrpcent() may be called to indicate that the caller
expects to do no further RPC entry retrieval operations; the
system may then deallocate resources it was using. It is
still allowed, but possibly less efficient, for the process
to call more RPC entry retrieval functions after calling
endrpcent().
Reentrant Interfaces
The functions getrpcbyname(), getrpcbynumber(), and getrp-
cent() use static storage that is re-used in each call, mak-
ing these routines unsafe for use in multithreaded applica-
tions.
The functions getrpcbynamer(), getrpcbynumberr(), and
getrpcentr() provide reentrant interfaces for these opera-
tions.
Each reentrant interface performs the same operation as its
non-reentrant counterpart, named by removing the ``r''
suffix. The reentrant interfaces, however, use buffers sup-
plied by the caller to store returned results, and are safe
for use in both single-threaded and multithreaded applica-
tions.
Each reentrant interface takes the same parameters as its
non-reentrant counterpart, as well as the following addi-
tional parameters. The parameter result must be a pointer
to a struct rpcent structure allocated by the caller. On
successful completion, the function returns the RPC entry in
this structure. The parameter buffer must be a pointer to a
buffer supplied by the caller. This buffer is used as
SunOS 5.11 Last change: 20 Feb 1998 2
Networking Services Library Functions getrpcbyname(3NSL)
storage space for the RPC entry data. All of the pointers
within the returned struct rpcent result point to data
stored within this buffer (see RETURN VALUES). The buffer
must be large enough to hold all of the data associated with
the RPC entry. The parameter buflen should give the size in
bytes of the buffer indicated by buffer.
For enumeration in multithreaded applications, the position
within the enumeration is a process-wide property shared by
all threads. setrpcent() may be used in a multithreaded
application but resets the enumeration position for all
threads. If multiple threads interleave calls to
getrpcentr(), the threads will enumerate disjoint subsets
of the RPC entry database.
Like their non-reentrant counterparts, getrpcbynamer() and
getrpcbynumberr() leave the enumeration position in an
indeterminate state.
RETURN VALUES
RPC entries are represented by the struct rpcent structure
defined in :
struct rpcent {
char *rname; /* name of this rpc service
char **raliases; /* zero-terminated list of alternate names */
int rnumber; /* rpc program number */
};
The functions getrpcbyname(), getrpcbynamer(),
getrpcbynumber(), and getrpcbynumberr() each return a
pointer to a struct rpcent if they successfully locate the
requested entry; otherwise they return NUL.
The functions getrpcent() and getrpcentr() each return a
pointer to a struct rpcent if they successfully enumerate an
entry; otherwise they return NUL, indicating the end of the
enumeration.
The functions getrpcbyname(), getrpcbynumber(), and getrp-
cent() use static storage, so returned data must be copied
before a subsequent call to any of these functions if the
data is to be saved.
SunOS 5.11 Last change: 20 Feb 1998 3
Networking Services Library Functions getrpcbyname(3NSL)
When the pointer returned by the reentrant functions
getrpcbynamer(), getrpcbynumberr(), and getrpcentr() is
non-NUL, it is always equal to the result pointer that was
supplied by the caller.
ERORS
The reentrant functions getrpcynamer(), getrpcbynumberr()
and getrpcentr() will return NUL and set errno to ERANGE
if the length of the buffer supplied by caller is not large
enough to store the result. See Intro(2) for the proper
usage and interpretation of errno in multithreaded applica-
tions.
FILES
/etc/rpc
/etc/nsswitch.conf
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level See "Reentrant Interfaces"
in DESCRIPTION.
SEE ALSO
rpcinfo(1M), rpc(3NSL), nsswitch.conf(4), rpc(4), attri-
butes(5)
WARNINGS
The reentrant interfaces getrpcbynamer(),
getrpcbynumberr(), and getrpcentr() are included in this
release on an uncommitted basis only, and are subject to
change or removal in future minor releases.
NOTES
When compiling multithreaded applications, see Intro(3),
Notes On Multithreaded Applications, for information about
the use of the RENTRANT flag.
Use of the enumeration interfaces getrpcent() and
getrpcentr() is discouraged; enumeration may not be sup-
ported for all database sources. The semantics of
SunOS 5.11 Last change: 20 Feb 1998 4
Networking Services Library Functions getrpcbyname(3NSL)
enumeration are discussed further in nsswitch.conf(4).
SunOS 5.11 Last change: 20 Feb 1998 5
|
