Debian Codegraph @

upstream/debian-trixie/man3/getprotoent_r.3

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