1 GETRPCBYNAME(3NSL) Networking Services Library Functions GETRPCBYNAME(3NSL)
2
3
4
5 NAME
6 getrpcbyname, getrpcbyname_r, getrpcbynumber, getrpcbynumber_r,
7 getrpcent, getrpcent_r, setrpcent, endrpcent - get RPC entry
8
9 SYNOPSIS
10 cc [ flag ... ] file ... -lnsl [ library ... ]
11 #include <rpc/rpcent.h>
12
13
14
15 struct rpcent *getrpcbyname(const char *name);
16
17
18 struct rpcent *getrpcbyname_r(const char *name, struct rpcent *result,
19 char *buffer, int buflen);
20
21
22 struct rpcent *getrpcbynumber(const int number);
23
24
25 struct rpcent *getrpcbynumber_r(const int number, struct rpcent *result,
26 char *buffer, int buflen);
27
28
29 struct rpcent *getrpcent(void);
30
31
32 struct rpcent *getrpcent_r(struct rpcent *result, char *buffer,
33 int buflen);
34
35
36 void setrpcent(const int stayopen);
37
38
39 void endrpcent(void);
40
41
42 DESCRIPTION
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
47
48 getrpcbyname() searches for an entry with the RPC service name
49 specified by the parameter name.
50
51
52 getrpcbynumber() searches for an entry with the RPC program number
53 number.
54
55
56 The functions setrpcent(), getrpcent(), and endrpcent() are used to
57 enumerate RPC entries from the database.
58
59
60 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
67
68 Successive calls to getrpcent() return either successive entries or
69 NULL, indicating the end of the enumeration.
70
71
72 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
75 efficient, for the process to call more RPC entry retrieval functions
76 after calling endrpcent().
77
78 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
83
84 The functions getrpcbyname_r(), getrpcbynumber_r(), and getrpcent_r()
85 provide reentrant interfaces for these operations.
86
87
88 Each reentrant interface performs the same operation as its non-
89 reentrant counterpart, named by removing the ``_r'' suffix. The
90 reentrant interfaces, however, use buffers supplied by the caller to
91 store returned results, and are safe for use in both single-threaded
92 and multithreaded applications.
93
94
95 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
98 allocated by the caller. On successful completion, the function
99 returns the RPC entry in this structure. The parameter buffer must be a
100 pointer to a buffer supplied by the caller. This buffer is used as
101 storage space for the RPC entry data. All of the pointers within the
102 returned struct rpcent result point to data stored within this buffer
103 (see RETURN VALUES). The buffer must be large enough to hold all of the
104 data associated with the RPC entry. The parameter buflen should give
105 the size in bytes of the buffer indicated by buffer.
106
107
108 For enumeration in multithreaded applications, the position within the
109 enumeration is a process-wide property shared by all threads.
110 setrpcent() may be used in a multithreaded application but resets the
111 enumeration 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
115
116 Like their non-reentrant counterparts, getrpcbyname_r() and
117 getrpcbynumber_r() leave the enumeration position in an indeterminate
118 state.
119
120 RETURN VALUES
121 RPC entries are represented by the struct rpcent structure defined in
122 <rpc/rpcent.h>:
123
124 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
130
131
132 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
136
137 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
141
142 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
146
147 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
151 ERRORS
152 The reentrant functions getrpcbyname_r(), getrpcbynumber_r() and
153 getrpcent_r() will return NULL and set errno to ERANGE if the length of
154 the buffer supplied by caller is not large enough to store the result.
155 See Intro(2) for the proper usage and interpretation of errno in
156 multithreaded applications.
157
158 FILES
159 /etc/rpc
160
161
162 /etc/nsswitch.conf
163
164 ATTRIBUTES
165 See attributes(5) for descriptions of the following attributes:
166
167
168
169
170 +---------------+--------------------------------------------+
171 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
172 +---------------+--------------------------------------------+
173 |MT-Level | See "Reentrant Interfaces" in DESCRIPTION. |
174 +---------------+--------------------------------------------+
175
176 SEE ALSO
177 rpcinfo(1M), rpc(3NSL), nsswitch.conf(4), rpc(4), attributes(5)
178
179 WARNINGS
180 The reentrant interfaces getrpcbyname_r(), getrpcbynumber_r(), and
181 getrpcent_r() are included in this release on an uncommitted basis
182 only, and are subject to change or removal in future minor releases.
183
184 NOTES
185 When compiling multithreaded applications, see Intro(3), Notes On
186 Multithreaded Applications, for information about the use of the
187 _REENTRANT flag.
188
189
190 Use of the enumeration interfaces getrpcent() and getrpcent_r() is
191 discouraged; enumeration may not be supported for all database sources.
192 The semantics of enumeration are discussed further in nsswitch.conf(4).
193
194
195
196 February 20, 1998 GETRPCBYNAME(3NSL)