1GETPROTOENT_R(3)           Linux Programmer's Manual          GETPROTOENT_R(3)
2
3
4

NAME

6       getprotoent_r,  getprotobyname_r,  getprotobynumber_r  -  get  protocol
7       entry (reentrant)
8

SYNOPSIS

10       #include <netdb.h>
11
12       int getprotoent_r(struct protoent *result_buf, char *buf,
13                       size_t buflen, struct protoent **result);
14
15       int getprotobyname_r(const char *name,
16                       struct protoent *result_buf, char *buf,
17                       size_t buflen, struct protoent **result);
18
19       int getprotobynumber_r(int proto,
20                       struct protoent *result_buf, char *buf,
21                       size_t buflen, struct protoent **result);
22
23   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
24
25       getprotoent_r(), getprotobyname_r(), getprotobynumber_r():
26           Since glibc 2.19:
27               _DEFAULT_SOURCE
28           Glibc 2.19 and earlier:
29               _BSD_SOURCE || _SVID_SOURCE
30

DESCRIPTION

32       The getprotoent_r(), getprotobyname_r(), and getprotobynumber_r() func‐
33       tions  are  the reentrant equivalents of, respectively, getprotoent(3),
34       getprotobyname(3), and getprotobynumber(3).  They  differ  in  the  way
35       that  the  protoent  structure is returned, and in the function calling
36       signature and return value.  This manual page describes just  the  dif‐
37       ferences from the nonreentrant functions.
38
39       Instead  of  returning  a  pointer  to  a statically allocated protoent
40       structure as the function result, these functions  copy  the  structure
41       into the location pointed to by result_buf.
42
43       The  buf  array  is  used  to store the string fields pointed to by the
44       returned protoent  structure.   (The  nonreentrant  functions  allocate
45       these  strings in static storage.)  The size of this array is specified
46       in buflen.  If buf is too small, the call fails with the error  ERANGE,
47       and  the  caller  must  try  again  with a larger buffer.  (A buffer of
48       length 1024 bytes should be sufficient for most applications.)
49
50       If the function call  successfully  obtains  a  protocol  record,  then
51       *result  is  set  pointing  to result_buf; otherwise, *result is set to
52       NULL.
53

RETURN VALUE

55       On success, these functions return 0.  On error, they return one of the
56       positive error numbers listed in ERRORS.
57
58       On  error, record not found (getprotobyname_r(), getprotobynumber_r()),
59       or end of input (getprotoent_r()) result is set to NULL.
60

ERRORS

62       ENOENT (getprotoent_r()) No more records in database.
63
64       ERANGE buf is too small.  Try again with a larger buffer (and increased
65              buflen).
66

ATTRIBUTES

68       For   an   explanation   of   the  terms  used  in  this  section,  see
69       attributes(7).
70
71       ┌─────────────────────┬───────────────┬────────────────┐
72Interface            Attribute     Value          
73       ├─────────────────────┼───────────────┼────────────────┤
74getprotoent_r(),     │ Thread safety │ MT-Safe locale │
75getprotobyname_r(),  │               │                │
76getprotobynumber_r() │               │                │
77       └─────────────────────┴───────────────┴────────────────┘
78

CONFORMING TO

80       These functions are GNU extensions.  Functions with similar names exist
81       on  some  other systems, though typically with different calling signa‐
82       tures.
83

EXAMPLE

85       The program below uses  getprotobyname_r()  to  retrieve  the  protocol
86       record for the protocol named in its first command-line argument.  If a
87       second (integer) command-line argument is supplied, it is used  as  the
88       initial  value  for  buflen; if getprotobyname_r() fails with the error
89       ERANGE, the program retries with larger buffer  sizes.   The  following
90       shell session shows a couple of sample runs:
91
92           $ ./a.out tcp 1
93           ERANGE! Retrying with larger buffer
94           getprotobyname_r() returned: 0 (success)  (buflen=78)
95           p_name=tcp; p_proto=6; aliases=TCP
96           $ ./a.out xxx 1
97           ERANGE! Retrying with larger buffer
98           getprotobyname_r() returned: 0 (success)  (buflen=100)
99           Call failed/record not found
100
101   Program source
102
103       #define _GNU_SOURCE
104       #include <ctype.h>
105       #include <netdb.h>
106       #include <stdlib.h>
107       #include <stdio.h>
108       #include <errno.h>
109       #include <string.h>
110
111       #define MAX_BUF 10000
112
113       int
114       main(int argc, char *argv[])
115       {
116           int buflen, erange_cnt, s;
117           struct protoent result_buf;
118           struct protoent *result;
119           char buf[MAX_BUF];
120           char **p;
121
122           if (argc < 2) {
123               printf("Usage: %s proto-name [buflen]\n", argv[0]);
124               exit(EXIT_FAILURE);
125           }
126
127           buflen = 1024;
128           if (argc > 2)
129               buflen = atoi(argv[2]);
130
131           if (buflen > MAX_BUF) {
132               printf("Exceeded buffer limit (%d)\n", MAX_BUF);
133               exit(EXIT_FAILURE);
134           }
135
136           erange_cnt = 0;
137           do {
138               s = getprotobyname_r(argv[1], &result_buf,
139                            buf, buflen, &result);
140               if (s == ERANGE) {
141                   if (erange_cnt == 0)
142                       printf("ERANGE! Retrying with larger buffer\n");
143                   erange_cnt++;
144
145                   /* Increment a byte at a time so we can see exactly
146                      what size buffer was required */
147
148                   buflen++;
149
150                   if (buflen > MAX_BUF) {
151                       printf("Exceeded buffer limit (%d)\n", MAX_BUF);
152                       exit(EXIT_FAILURE);
153                   }
154               }
155           } while (s == ERANGE);
156
157           printf("getprotobyname_r() returned: %s  (buflen=%d)\n",
158                   (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" :
159                   strerror(s), buflen);
160
161           if (s != 0 || result == NULL) {
162               printf("Call failed/record not found\n");
163               exit(EXIT_FAILURE);
164           }
165
166           printf("p_name=%s; p_proto=%d; aliases=",
167                       result_buf.p_name, result_buf.p_proto);
168           for (p = result_buf.p_aliases; *p != NULL; p++)
169               printf("%s ", *p);
170           printf("\n");
171
172           exit(EXIT_SUCCESS);
173       }
174

SEE ALSO

176       getprotoent(3), protocols(5)
177

COLOPHON

179       This  page  is  part of release 4.16 of the Linux man-pages project.  A
180       description of the project, information about reporting bugs,  and  the
181       latest     version     of     this    page,    can    be    found    at
182       https://www.kernel.org/doc/man-pages/.
183
184
185
186GNU                               2017-09-15                  GETPROTOENT_R(3)
Impressum