2 .\" Copyright 2008, Linux Foundation, written by Michael Kerrisk
3 .\" <mtk.manpages@gmail.com>
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .TH getprotoent_r 3 (date) "Linux man-pages (unreleased)"
9 getprotoent_r, getprotobyname_r, getprotobynumber_r \- get
10 protocol entry (reentrant)
13 .RI ( libc ", " \-lc )
18 .BI "int getprotoent_r(struct protoent *restrict " result_buf ,
19 .BI " char " buf "[restrict ." buflen "], size_t " buflen ,
20 .BI " struct protoent **restrict " result );
21 .BI "int getprotobyname_r(const char *restrict " name ,
22 .BI " struct protoent *restrict " result_buf ,
23 .BI " char " buf "[restrict ." buflen "], size_t " buflen ,
24 .BI " struct protoent **restrict " result );
25 .BI "int getprotobynumber_r(int " proto ,
26 .BI " struct protoent *restrict " result_buf ,
27 .BI " char " buf "[restrict ." buflen "], size_t " buflen ,
28 .BI " struct protoent **restrict " result );
32 Feature Test Macro Requirements for glibc (see
33 .BR feature_test_macros (7)):
37 .BR getprotobyname_r (),
38 .BR getprotobynumber_r ():
42 glibc 2.19 and earlier:
43 _BSD_SOURCE || _SVID_SOURCE
48 .BR getprotobyname_r (),
50 .BR getprotobynumber_r ()
51 functions are the reentrant equivalents of, respectively,
53 .BR getprotobyname (3),
55 .BR getprotobynumber (3).
56 They differ in the way that the
58 structure is returned,
59 and in the function calling signature and return value.
60 This manual page describes just the differences from
61 the nonreentrant functions.
63 Instead of returning a pointer to a statically allocated
65 structure as the function result,
66 these functions copy the structure into the location pointed to by
71 array is used to store the string fields pointed to by the returned
74 (The nonreentrant functions allocate these strings in static storage.)
75 The size of this array is specified in
79 is too small, the call fails with the error
81 and the caller must try again with a larger buffer.
82 (A buffer of length 1024 bytes should be sufficient for most applications.)
83 .\" I can find no information on the required/recommended buffer size;
84 .\" the nonreentrant functions use a 1024 byte buffer.
85 .\" The 1024 byte value is also what the Solaris man page suggests. -- mtk
87 If the function call successfully obtains a protocol record, then
95 On success, these functions return 0.
96 On error, they return one of the positive error numbers listed in ERRORS.
98 On error, record not found
99 .RB ( getprotobyname_r (),
100 .BR getprotobynumber_r ()),
102 .RB ( getprotoent_r ())
108 .RB ( getprotoent_r ())
109 No more records in database.
114 Try again with a larger buffer
118 For an explanation of the terms used in this section, see
126 Interface Attribute Value
128 .BR getprotoent_r (),
129 .BR getprotobyname_r (),
130 .BR getprotobynumber_r ()
131 T} Thread safety MT-Safe locale
137 Functions with similar names exist on some other systems,
138 though typically with different calling signatures.
142 The program below uses
143 .BR getprotobyname_r ()
144 to retrieve the protocol record for the protocol named
145 in its first command-line argument.
146 If a second (integer) command-line argument is supplied,
147 it is used as the initial value for
150 .BR getprotobyname_r ()
153 the program retries with larger buffer sizes.
154 The following shell session shows a couple of sample runs:
158 .RB "$" " ./a.out tcp 1"
159 ERANGE! Retrying with larger buffer
160 getprotobyname_r() returned: 0 (success) (buflen=78)
161 p_name=tcp; p_proto=6; aliases=TCP
162 .RB "$" " ./a.out xxx 1"
163 ERANGE! Retrying with larger buffer
164 getprotobyname_r() returned: 0 (success) (buflen=100)
165 Call failed/record not found
170 .\" SRC BEGIN (getprotoent_r.c)
180 #define MAX_BUF 10000
183 main(int argc, char *argv[])
185 int buflen, erange_cnt, s;
186 struct protoent result_buf;
187 struct protoent *result;
191 printf("Usage: %s proto\-name [buflen]\en", argv[0]);
197 buflen = atoi(argv[2]);
199 if (buflen > MAX_BUF) {
200 printf("Exceeded buffer limit (%d)\en", MAX_BUF);
206 s = getprotobyname_r(argv[1], &result_buf,
207 buf, buflen, &result);
210 printf("ERANGE! Retrying with larger buffer\en");
213 /* Increment a byte at a time so we can see exactly
214 what size buffer was required. */
218 if (buflen > MAX_BUF) {
219 printf("Exceeded buffer limit (%d)\en", MAX_BUF);
223 } while (s == ERANGE);
225 printf("getprotobyname_r() returned: %s (buflen=%d)\en",
226 (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" :
227 strerror(s), buflen);
229 if (s != 0 || result == NULL) {
230 printf("Call failed/record not found\en");
234 printf("p_name=%s; p_proto=%d; aliases=",
235 result_buf.p_name, result_buf.p_proto);
236 for (char **p = result_buf.p_aliases; *p != NULL; p++)