Debian Codegraph @

upstream/debian-unstable/man3/getprotoent_r.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH getprotoent_r 3 2025-09-21 "Linux man-pages 6.18"
7 .SH NAME
8 getprotoent_r, getprotobyname_r, getprotobynumber_r \- get
9 protocol entry (reentrant)
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <netdb.h>
16 .P
17 .BR "int getprotoent_r(" "size_t size;"
18 .BI " struct protoent *restrict " result_buf ,
19 .BI " char " buf "[restrict " size "], size_t " size ,
20 .BI " struct protoent **restrict " result );
21 .BR "int getprotobyname_r(" "size_t size;"
22 .BI " const char *restrict " name ,
23 .BI " struct protoent *restrict " result_buf ,
24 .BI " char " buf "[restrict " size "], size_t " size ,
25 .BI " struct protoent **restrict " result );
26 .BR "int getprotobynumber_r(" "size_t size;"
27 .BI " int " proto ,
28 .BI " struct protoent *restrict " result_buf ,
29 .BI " char " buf "[restrict " size "], size_t " size ,
30 .BI " struct protoent **restrict " result );
31 .P
32 .fi
33 .RS -4
34 Feature Test Macro Requirements for glibc (see
35 .BR feature_test_macros (7)):
36 .RE
37 .P
38 .BR getprotoent_r (),
39 .BR getprotobyname_r (),
40 .BR getprotobynumber_r ():
41 .nf
42 Since glibc 2.19:
43 _DEFAULT_SOURCE
44 glibc 2.19 and earlier:
45 _BSD_SOURCE || _SVID_SOURCE
46 .fi
47 .SH DESCRIPTION
48 The
49 .BR getprotoent_r (),
50 .BR getprotobyname_r (),
51 and
52 .BR getprotobynumber_r ()
53 functions are the reentrant equivalents of, respectively,
54 .BR getprotoent (3),
55 .BR getprotobyname (3),
56 and
57 .BR getprotobynumber (3).
58 They differ in the way that the
59 .I protoent
60 structure is returned,
61 and in the function calling signature and return value.
62 This manual page describes just the differences from
63 the nonreentrant functions.
64 .P
65 Instead of returning a pointer to a statically allocated
66 .I protoent
67 structure as the function result,
68 these functions copy the structure into the location pointed to by
69 .IR result_buf .
70 .P
71 The
72 .I buf
73 array is used to store the string fields pointed to by the returned
74 .I protoent
75 structure.
76 (The nonreentrant functions allocate these strings in static storage.)
77 The size of this array is specified in
78 .IR size .
79 If
80 .I buf
81 is too small, the call fails with the error
82 .BR ERANGE ,
83 and the caller must try again with a larger buffer.
84 (A buffer of size 1024 bytes should be sufficient for most applications.)
85 .\" I can find no information on the required/recommended buffer size;
86 .\" the nonreentrant functions use a 1024 byte buffer.
87 .\" The 1024 byte value is also what the Solaris man page suggests. -- mtk
88 .P
89 If the function call successfully obtains a protocol record, then
90 .I *result
91 is set pointing to
92 .IR result_buf ;
93 otherwise,
94 .I *result
95 is set to NULL.
96 .SH RETURN VALUE
97 On success, these functions return 0.
98 On error, they return one of the positive error numbers listed in ERRORS.
99 .P
100 On error, record not found
101 .RB ( getprotobyname_r (),
102 .BR getprotobynumber_r ()),
103 or end of input
104 .RB ( getprotoent_r ())
105 .I result
106 is set to NULL.
107 .SH ERRORS
108 .TP
109 .B ENOENT
110 .RB ( getprotoent_r ())
111 No more records in database.
112 .TP
113 .B ERANGE
114 .I buf
115 is too small.
116 Try again with a larger buffer
117 (and increased
118 .IR size ).
119 .SH ATTRIBUTES
120 For an explanation of the terms used in this section, see
121 .BR attributes (7).
122 .TS
123 allbox;
124 lbx lb lb
125 l l l.
126 Interface Attribute Value
127 T{
128 .na
129 .nh
130 .BR getprotoent_r (),
131 .BR getprotobyname_r (),
132 .BR getprotobynumber_r ()
133 T} Thread safety MT-Safe locale
134 .TE
135 .SH VERSIONS
136 Functions with similar names exist on some other systems,
137 though typically with different calling signatures.
138 .SH STANDARDS
139 GNU.
140 .SH EXAMPLES
141 The program below uses
142 .BR getprotobyname_r ()
143 to retrieve the protocol record for the protocol named
144 in its first command-line argument.
145 If a second (integer) command-line argument is supplied,
146 it is used as the initial value for
147 .IR size ;
148 if
149 .BR getprotobyname_r ()
150 fails with the error
151 .BR ERANGE ,
152 the program retries with larger buffer sizes.
153 The following shell session shows a couple of sample runs:
154 .P
155 .in +4n
156 .EX
157 .RB "$" " ./a.out tcp 1"
158 ERANGE! Retrying with larger buffer
159 getprotobyname_r() returned: 0 (success) (size=78)
160 p_name=tcp; p_proto=6; aliases=TCP
161 .RB "$" " ./a.out xxx 1"
162 ERANGE! Retrying with larger buffer
163 getprotobyname_r() returned: 0 (success) (size=100)
164 Call failed/record not found
165 .EE
166 .in
167 .SS Program source
168 \&
169 .\" SRC BEGIN (getprotoent_r.c)
170 .EX
171 #define _GNU_SOURCE
172 #include <ctype.h>
173 #include <errno.h>
174 #include <netdb.h>
175 #include <stdio.h>
176 #include <stdlib.h>
177 #include <string.h>
178 \&
179 #define MAX_BUF 10000
180 \&
181 int
182 main(int argc, char *argv[])
183 {
184 int size, erange_cnt, s;
185 struct protoent result_buf;
186 struct protoent *result;
187 char buf[MAX_BUF];
188 \&
189 if (argc < 2) {
190 printf("Usage: %s proto\-name [size]\[rs]n", argv[0]);
191 exit(EXIT_FAILURE);
192 }
193 \&
194 size = 1024;
195 if (argc > 2)
196 size = atoi(argv[2]);
197 \&
198 if (size > MAX_BUF) {
199 printf("Exceeded buffer limit (%d)\[rs]n", MAX_BUF);
200 exit(EXIT_FAILURE);
201 }
202 \&
203 erange_cnt = 0;
204 do {
205 s = getprotobyname_r(argv[1], &result_buf,
206 buf, size, &result);
207 if (s == ERANGE) {
208 if (erange_cnt == 0)
209 printf("ERANGE! Retrying with larger buffer\[rs]n");
210 erange_cnt++;
211 \&
212 /* Increment a byte at a time so we can see exactly
213 what size buffer was required. */
214 \&
215 size++;
216 \&
217 if (size > MAX_BUF) {
218 printf("Exceeded buffer limit (%d)\[rs]n", MAX_BUF);
219 exit(EXIT_FAILURE);
220 }
221 }
222 } while (s == ERANGE);
223 \&
224 printf("getprotobyname_r() returned: %s (size=%d)\[rs]n",
225 (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" :
226 strerror(s), size);
227 \&
228 if (s != 0 || result == NULL) {
229 printf("Call failed/record not found\[rs]n");
230 exit(EXIT_FAILURE);
231 }
232 \&
233 printf("p_name=%s; p_proto=%d; aliases=",
234 result_buf.p_name, result_buf.p_proto);
235 for (char **p = result_buf.p_aliases; *p != NULL; p++)
236 printf("%s ", *p);
237 printf("\[rs]n");
238 \&
239 exit(EXIT_SUCCESS);
240 }
241 .EE
242 .\" SRC END
243 .SH SEE ALSO
244 .BR getprotoent (3),
245 .BR protocols (5)