1getrpcbyname(3NSL)   Networking Services Library Functions  getrpcbyname(3NSL)
2
3
4

NAME

6       getrpcbyname,  getrpcbyname_r, getrpcbynumber, getrpcbynumber_r, getrp‐
7       cent, getrpcent_r, setrpcent, endrpcent - get RPC entry
8

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

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  speci‐
49       fied by the parameter name.
50
51
52       getrpcbynumber() searches for an entry with the RPC program number num‐
53       ber.
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 effi‐
75       cient, for the process to call more RPC entry retrieval functions after
76       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-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
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  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
107
108       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
115
116       Like  their  non-reentrant  counterparts,  getrpcbyname_r()  and  getr‐
117       pcbynumber_r() leave  the  enumeration  position  in  an  indeterminate
118       state.
119

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

ERRORS

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

FILES

159       /etc/rpc
160
161
162       /etc/nsswitch.conf
163

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"  │
174       │                             │in DESCRIPTION.              │
175       └─────────────────────────────┴─────────────────────────────┘
176

SEE ALSO

178       rpcinfo(1M), rpc(3NSL), nsswitch.conf(4), rpc(4), attributes(5)
179

WARNINGS

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

NOTES

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
190
191       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).
194
195
196
197SunOS 5.11                        20 Feb 1998               getrpcbyname(3NSL)
Impressum