1getrpcbyname(3NSL) Networking Services Library Functions getrpcbyname(3NSL)
2
6 getrpcbyname, getrpcbyname_r, getrpcbynumber, getrpcbynumber_r, getrp‐
7 cent, getrpcent_r, setrpcent, endrpcent - get RPC entry
8
10 cc [ flag ... ] file ... -lnsl [ library ... ]
11 #include <rpc/rpcent.h>
12 struct rpcent *getrpcbyname(const char *name);
16 struct rpcent *getrpcbyname_r(const char *name, struct rpcent *result,
19 char *buffer, int buflen);
20 struct rpcent *getrpcbynumber(const int number);
23 struct rpcent *getrpcbynumber_r(const int number, struct rpcent *result,
26 char *buffer, int buflen);
27 struct rpcent *getrpcent(void);
30 struct rpcent *getrpcent_r(struct rpcent *result, char *buffer,
33 int buflen);
34 void setrpcent(const int stayopen);
37 void endrpcent(void);
40
43 These functions are used to obtain entries for RPC (Remote Procedure
44 Call) services. An entry may come from any of the sources for rpc
45 specified in the /etc/nsswitch.conf file (see nsswitch.conf(4)).
46 getrpcbyname() searches for an entry with the RPC service name speci‐
49 fied by the parameter name.
50 getrpcbynumber() searches for an entry with the RPC program number num‐
53 ber.
54 The functions setrpcent(), getrpcent(), and endrpcent() are used to
57 enumerate RPC entries from the database.
58 setrpcent() sets (or resets) the enumeration to the beginning of the
61 set of RPC entries. This function should be called before the first
62 call to getrpcent(). Calls to getrpcbyname() and getrpcbynumber() leave
63 the enumeration position in an indeterminate state. If the stayopen
64 flag is non-zero, the system may keep allocated resources such as open
65 file descriptors until a subsequent call to endrpcent().
66 Successive calls to getrpcent() return either successive entries or
69 NULL, indicating the end of the enumeration.
70 endrpcent() may be called to indicate that the caller expects to do no
73 further RPC entry retrieval operations; the system may then deallocate
74 resources it was using. It is still allowed, but possibly less effi‐
75 cient, for the process to call more RPC entry retrieval functions after
76 calling endrpcent().
77 Reentrant Interfaces
79 The functions getrpcbyname(), getrpcbynumber(), and getrpcent() use
80 static storage that is re-used in each call, making these routines
81 unsafe for use in multithreaded applications.
82 The functions getrpcbyname_r(), getrpcbynumber_r(), and getrpcent_r()
85 provide reentrant interfaces for these operations.
86 Each reentrant interface performs the same operation as its non-reen‐
89 trant counterpart, named by removing the ``_r'' suffix. The reentrant
90 interfaces, however, use buffers supplied by the caller to store
91 returned results, and are safe for use in both single-threaded and
92 multithreaded applications.
93 Each reentrant interface takes the same parameters as its non-reentrant
96 counterpart, as well as the following additional parameters. The
97 parameter result must be a pointer to a struct rpcent structure allo‐
98 cated by the caller. On successful completion, the function returns
99 the RPC entry in this structure. The parameter buffer must be a pointer
100 to a buffer supplied by the caller. This buffer is used as storage
101 space for the RPC entry data. All of the pointers within the returned
102 struct rpcent result point to data stored within this buffer (see
103 RETURN VALUES). The buffer must be large enough to hold all of the data
104 associated with the RPC entry. The parameter buflen should give the
105 size in bytes of the buffer indicated by buffer.
106 For enumeration in multithreaded applications, the position within the
109 enumeration is a process-wide property shared by all threads. setrp‐
110 cent() may be used in a multithreaded application but resets the enu‐
111 meration position for all threads. If multiple threads interleave
112 calls to getrpcent_r(), the threads will enumerate disjoint subsets of
113 the RPC entry database.
114 Like their non-reentrant counterparts, getrpcbyname_r() and getr‐
117 pcbynumber_r() leave the enumeration position in an indeterminate
118 state.
119
121 RPC entries are represented by the struct rpcent structure defined in
122 <rpc/rpcent.h>:
123 struct rpcent {
125 char *r_name; /* name of this rpc service
126 char **r_aliases; /* zero-terminated list of alternate names */
127 int r_number; /* rpc program number */
128 };
129 The functions getrpcbyname(), getrpcbyname_r(), getrpcbynumber(), and
133 getrpcbynumber_r() each return a pointer to a struct rpcent if they
134 successfully locate the requested entry; otherwise they return NULL.
135 The functions getrpcent() and getrpcent_r() each return a pointer to a
138 struct rpcent if they successfully enumerate an entry; otherwise they
139 return NULL, indicating the end of the enumeration.
140 The functions getrpcbyname(), getrpcbynumber(), and getrpcent() use
143 static storage, so returned data must be copied before a subsequent
144 call to any of these functions if the data is to be saved.
145 When the pointer returned by the reentrant functions getrpcbyname_r(),
148 getrpcbynumber_r(), and getrpcent_r() is non-NULL, it is always equal
149 to the result pointer that was supplied by the caller.
150
152 The reentrant functions getrpcyname_r(), getrpcbynumber_r() and getrp‐
153 cent_r() will return NULL and set errno to ERANGE if the length of the
154 buffer supplied by caller is not large enough to store the result. See
155 Intro(2) for the proper usage and interpretation of errno in multi‐
156 threaded applications.
157
159 /etc/rpc
160 /etc/nsswitch.conf
163
165 See attributes(5) for descriptions of the following attributes:
166 ┌─────────────────────────────┬─────────────────────────────┐
171 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
172 ├─────────────────────────────┼─────────────────────────────┤
173 │MT-Level │See "Reentrant Interfaces" │
174 │ │in DESCRIPTION. │
175 └─────────────────────────────┴─────────────────────────────┘
176
178 rpcinfo(1M), rpc(3NSL), nsswitch.conf(4), rpc(4), attributes(5)
179
181 The reentrant interfaces getrpcbyname_r(), getrpcbynumber_r(), and
182 getrpcent_r() are included in this release on an uncommitted basis
183 only, and are subject to change or removal in future minor releases.
184
186 When compiling multithreaded applications, see Intro(3), Notes On Mul‐
187 tithreaded Applications, for information about the use of the _REEN‐
188 TRANT flag.
189 Use of the enumeration interfaces getrpcent() and getrpcent_r() is dis‐
192 couraged; enumeration may not be supported for all database sources.
193 The semantics of enumeration are discussed further in nsswitch.conf(4).
194SunOS 5.11 20 Feb 1998 getrpcbyname(3NSL)