Debian Codegraph @

upstream/debian-unstable/man3/getnetent_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 getnetent_r 3 2025-06-28 "Linux man-pages 6.18"
7 .SH NAME
8 getnetent_r, getnetbyname_r, getnetbyaddr_r \- get
9 network 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 getnetent_r(" "size_t size;"
18 .BI " struct netent *restrict " result_buf ,
19 .BI " char " buf "[restrict " size "], size_t " size ,
20 .BI " struct netent **restrict " result ,
21 .BI " int *restrict " h_errnop );
22 .BR "int getnetbyname_r(" "size_t size;"
23 .BI " const char *restrict " name ,
24 .BI " struct netent *restrict " result_buf ,
25 .BI " char " buf "[restrict " size "], size_t " size ,
26 .BI " struct netent **restrict " result ,
27 .BI " int *restrict " h_errnop );
28 .BR "int getnetbyaddr_r(" "size_t size;"
29 .BI " uint32_t " net ", int " type ,
30 .BI " struct netent *restrict " result_buf ,
31 .BI " char " buf "[restrict " size "], size_t " size ,
32 .BI " struct netent **restrict " result ,
33 .BI " int *restrict " h_errnop );
34 .P
35 .fi
36 .RS -4
37 Feature Test Macro Requirements for glibc (see
38 .BR feature_test_macros (7)):
39 .RE
40 .P
41 .BR getnetent_r (),
42 .BR getnetbyname_r (),
43 .BR getnetbyaddr_r ():
44 .nf
45 Since glibc 2.19:
46 _DEFAULT_SOURCE
47 glibc 2.19 and earlier:
48 _BSD_SOURCE || _SVID_SOURCE
49 .fi
50 .SH DESCRIPTION
51 The
52 .BR getnetent_r (),
53 .BR getnetbyname_r (),
54 and
55 .BR getnetbyaddr_r ()
56 functions are the reentrant equivalents of, respectively,
57 .BR getnetent (3),
58 .BR getnetbyname (3),
59 and
60 .BR getnetbynumber (3).
61 They differ in the way that the
62 .I netent
63 structure is returned,
64 and in the function calling signature and return value.
65 This manual page describes just the differences from
66 the nonreentrant functions.
67 .P
68 Instead of returning a pointer to a statically allocated
69 .I netent
70 structure as the function result,
71 these functions copy the structure into the location pointed to by
72 .IR result_buf .
73 .P
74 The
75 .I buf
76 array is used to store the string fields pointed to by the returned
77 .I netent
78 structure.
79 (The nonreentrant functions allocate these strings in static storage.)
80 The size of this array is specified in
81 .IR size .
82 If
83 .I buf
84 is too small, the call fails with the error
85 .BR ERANGE ,
86 and the caller must try again with a larger buffer.
87 (A buffer of size 1024 bytes should be sufficient for most applications.)
88 .\" I can find no information on the required/recommended buffer size;
89 .\" the nonreentrant functions use a 1024 byte buffer -- mtk.
90 .P
91 If the function call successfully obtains a network record, then
92 .I *result
93 is set pointing to
94 .IR result_buf ;
95 otherwise,
96 .I *result
97 is set to NULL.
98 .P
99 The buffer pointed to by
100 .I h_errnop
101 is used to return the value that would be stored in the global variable
102 .I h_errno
103 by the nonreentrant versions of these functions.
104 .\" getnetent.3 doesn't document any use of h_errno, but nevertheless
105 .\" the nonreentrant functions no seem to set h_errno.
106 .SH RETURN VALUE
107 On success, these functions return 0.
108 On error, they return one of the positive error numbers listed in ERRORS.
109 .P
110 On error, record not found
111 .RB ( getnetbyname_r (),
112 .BR getnetbyaddr_r ()),
113 or end of input
114 .RB ( getnetent_r ())
115 .I result
116 is set to NULL.
117 .SH ERRORS
118 .TP
119 .B ENOENT
120 .RB ( getnetent_r ())
121 No more records in database.
122 .TP
123 .B ERANGE
124 .I buf
125 is too small.
126 Try again with a larger buffer
127 (and increased
128 .IR size ).
129 .SH ATTRIBUTES
130 For an explanation of the terms used in this section, see
131 .BR attributes (7).
132 .TS
133 allbox;
134 lbx lb lb
135 l l l.
136 Interface Attribute Value
137 T{
138 .na
139 .nh
140 .BR getnetent_r (),
141 .BR getnetbyname_r (),
142 .BR getnetbyaddr_r ()
143 T} Thread safety MT-Safe locale
144 .TE
145 .SH VERSIONS
146 Functions with similar names exist on some other systems,
147 though typically with different calling signatures.
148 .SH STANDARDS
149 GNU.
150 .SH SEE ALSO
151 .BR getnetent (3),
152 .BR networks (5)