man3/getnetent_r.3

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