man3/getnetent.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu)
  11 .TH getnetent 3 (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 getnetent, getnetbyname, getnetbyaddr, setnetent, endnetent \-
  14 get network entry
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <netdb.h>
  21 .PP
  22 .B struct netent *getnetent(void);
  23 .PP
  24 .BI "struct netent *getnetbyname(const char *" name );
  25 .BI "struct netent *getnetbyaddr(uint32_t " net ", int " type );
  26 .PP
  27 .BI "void setnetent(int " stayopen );
  28 .B void endnetent(void);
  29 .fi
  30 .SH DESCRIPTION
  31 The
  32 .BR getnetent ()
  33 function reads the next entry from the networks database
  34 and returns a
  35 .I netent
  36 structure containing
  37 the broken-out fields from the entry.
  38 A connection is opened to the database if necessary.
  39 .PP
  40 The
  41 .BR getnetbyname ()
  42 function returns a
  43 .I netent
  44 structure
  45 for the entry from the database
  46 that matches the network
  47 .IR name .
  48 .PP
  49 The
  50 .BR getnetbyaddr ()
  51 function returns a
  52 .I netent
  53 structure
  54 for the entry from the database
  55 that matches the network number
  56 .I net
  57 of type
  58 .IR type .
  59 The
  60 .I net
  61 argument must be in host byte order.
  62 .PP
  63 The
  64 .BR setnetent ()
  65 function opens a connection to the database,
  66 and sets the next entry to the first entry.
  67 If
  68 .I stayopen
  69 is nonzero,
  70 then the connection to the database
  71 will not be closed between calls to one of the
  72 .BR getnet* ()
  73 functions.
  74 .PP
  75 The
  76 .BR endnetent ()
  77 function closes the connection to the database.
  78 .PP
  79 The
  80 .I netent
  81 structure is defined in
  82 .I <netdb.h>
  83 as follows:
  84 .PP
  85 .in +4n
  86 .EX
  87 struct netent {
  88     char      *n_name;     /* official network name */
  89     char     **n_aliases;  /* alias list */
  90     int        n_addrtype; /* net address type */
  91     uint32_t   n_net;      /* network number */
  92 }
  93 .EE
  94 .in
  95 .PP
  96 The members of the
  97 .I netent
  98 structure are:
  99 .TP
 100 .I n_name
 101 The official name of the network.
 102 .TP
 103 .I n_aliases
 104 A NULL-terminated list of alternative names for the network.
 105 .TP
 106 .I n_addrtype
 107 The type of the network number; always
 108 .BR AF_INET .
 109 .TP
 110 .I n_net
 111 The network number in host byte order.
 112 .SH RETURN VALUE
 113 The
 114 .BR getnetent (),
 115 .BR getnetbyname (),
 116 and
 117 .BR getnetbyaddr ()
 118 functions return a pointer to a
 119 statically allocated
 120 .I netent
 121 structure, or a null pointer if an
 122 error occurs or the end of the file is reached.
 123 .SH FILES
 124 .TP
 125 .I /etc/networks
 126 networks database file
 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 lb lb lbx
 135 l l l.
 136 Interface       Attribute       Value
 137 T{
 138 .BR getnetent ()
 139 T}      Thread safety   T{
 140 MT-Unsafe race:netent
 141 race:netentbuf env locale
 142 T}
 143 T{
 144 .BR getnetbyname ()
 145 T}      Thread safety   T{
 146 MT-Unsafe race:netbyname
 147 env locale
 148 T}
 149 T{
 150 .BR getnetbyaddr ()
 151 T}      Thread safety   T{
 152 MT-Unsafe race:netbyaddr
 153 locale
 154 T}
 155 T{
 156 .BR setnetent (),
 157 .BR endnetent ()
 158 T}      Thread safety   T{
 159 MT-Unsafe race:netent env
 160 locale
 161 T}
 162 .TE
 163 .hy
 164 .ad
 165 .sp 1
 166 In the above table,
 167 .I netent
 168 in
 169 .I race:netent
 170 signifies that if any of the functions
 171 .BR setnetent (),
 172 .BR getnetent (),
 173 or
 174 .BR endnetent ()
 175 are used in parallel in different threads of a program,
 176 then data races could occur.
 177 .SH STANDARDS
 178 POSIX.1-2001, POSIX.1-2008, 4.3BSD.
 179 .SH NOTES
 180 Before glibc 2.2, the
 181 .I net
 182 argument of
 183 .BR getnetbyaddr ()
 184 was of type
 185 .IR long .
 186 .SH SEE ALSO
 187 .BR getnetent_r (3),
 188 .BR getprotoent (3),
 189 .BR getservent (3)
 190 .\" .BR networks (5)
 191 .br
 192 RFC\ 1101