lib/libc/net/getnetent.3

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)getnetent.3 8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD: src/lib/libc/net/getnetent.3,v 1.23 2007/01/09 00:28:02 imp Exp $
  30 .\"
  31 .Dd May 6, 2019
  32 .Dt GETNETENT 3
  33 .Os
  34 .Sh NAME
  35 .Nm getnetent ,
  36 .Nm getnetent_r ,
  37 .Nm getnetbyaddr ,
  38 .Nm getnetbyaddr_r ,
  39 .Nm getnetbyname ,
  40 .Nm getnetbyname_r ,
  41 .Nm setnetent ,
  42 .Nm endnetent
  43 .Nd get network entry
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In netdb.h
  48 .Ft struct netent *
  49 .Fn getnetent void
  50 .Ft int
  51 .Fn getnetent_r "struct netent *ne" "char *buffer" "size_t buflen" "struct netent **result" "int *h_errnop"
  52 .Ft struct netent *
  53 .Fn getnetbyname "const char *name"
  54 .Ft int
  55 .Fn getnetbyname_r "const char *name" "struct netent *ne" "char *buffer" "size_t buflen" "struct netent **result" "int *h_errnop"
  56 .Ft struct netent *
  57 .Fn getnetbyaddr "uint32_t net" "int type"
  58 .Ft int
  59 .Fn getnetbyaddr_r "uint32_t addr" "int af" "struct netent *ne" "char *buffer" "size_t buflen" "struct netent **result" "int *h_errnop"
  60 .Ft void
  61 .Fn setnetent "int stayopen"
  62 .Ft void
  63 .Fn endnetent void
  64 .Sh DESCRIPTION
  65 The
  66 .Fn getnetent ,
  67 .Fn getnetbyname ,
  68 and
  69 .Fn getnetbyaddr
  70 functions
  71 each return a pointer to an object with the
  72 following structure describing an internet network.
  73 This structure contains either the information obtained
  74 from the nameserver,
  75 .Xr named 8 ,
  76 broken-out fields of a line in the network data base
  77 .Pa /etc/networks ,
  78 or entries supplied by the
  79 .Xr yp 8
  80 system.
  81 The order of the lookups is controlled by the
  82 `networks' entry in
  83 .Xr nsswitch.conf 5 .
  84 .Bd -literal -offset indent
  85 struct  netent {
  86         char            *n_name;        /* official name of net */
  87         char            **n_aliases;    /* alias list */
  88         int             n_addrtype;     /* net number type */
  89         uint32_t        n_net;          /* net number */
  90 };
  91 .Ed
  92 .Pp
  93 The members of this structure are:
  94 .Bl -tag -width n_addrtype
  95 .It Fa n_name
  96 The official name of the network.
  97 .It Fa n_aliases
  98 A zero terminated list of alternate names for the network.
  99 .It Fa n_addrtype
 100 The type of the network number returned; currently only AF_INET.
 101 .It Fa n_net
 102 The network number.
 103 Network numbers are returned in machine byte
 104 order.
 105 .El
 106 .Pp
 107 The
 108 .Fn getnetent
 109 function
 110 reads the next line of the file, opening the file if necessary.
 111 .Pp
 112 The
 113 .Fn setnetent
 114 function
 115 opens and rewinds the file.
 116 If the
 117 .Fa stayopen
 118 flag is non-zero,
 119 the net data base will not be closed after each call to
 120 .Fn getnetbyname
 121 or
 122 .Fn getnetbyaddr .
 123 .Pp
 124 The
 125 .Fn endnetent
 126 function
 127 closes the file.
 128 .Pp
 129 The
 130 .Fn getnetbyname
 131 function
 132 and
 133 .Fn getnetbyaddr
 134 sequentially search from the beginning
 135 of the file until a matching
 136 net name or
 137 net address and type is found,
 138 or until
 139 .Dv EOF
 140 is encountered.
 141 The
 142 .Fa type
 143 argument
 144 must be
 145 .Dv AF_INET .
 146 Network numbers are supplied in host order.
 147 .Pp
 148 The
 149 .Fn getnetent_r ,
 150 .Fn getnetbyaddr_r ,
 151 and
 152 .Fn getnetbyname_r
 153 functions are reentrant versions of the above functions that take a
 154 pointer to a
 155 .Vt netent
 156 structure which is used to store state information.
 157 The structure must be zero-filled before it is used
 158 and should be considered opaque for the sake of portability.
 159 These functions also take a pointer to another
 160 .Vt netent
 161 structure which is used to store the results of the database lookup.
 162 .Sh RETURN VALUES
 163 The
 164 .Fn getnetent ,
 165 .Fn getnetbyaddr ,
 166 and
 167 .Fn getnetbyname
 168 functions return a pointer to a
 169 .Vt netent
 170 structure on success or a null pointer if end-of-file
 171 is reached or an error occurs.
 172 .Pp
 173 The
 174 .Fn getnetent_r ,
 175 .Fn getnetbyaddr_r ,
 176 and
 177 .Fn getnetbyname_r
 178 functions return 0 on success or \-1 if end-of-file
 179 is reached or an error occurs.
 180 .Sh FILES
 181 .Bl -tag -width ".Pa /etc/nsswitch.conf" -compact
 182 .It Pa /etc/networks
 183 .It Pa /etc/nsswitch.conf
 184 .It Pa /etc/resolv.conf
 185 .El
 186 .Sh SEE ALSO
 187 .Xr networks 5
 188 .Pp
 189 .%T RFC 1101
 190 .Sh STANDARDS
 191 The
 192 .Fn getnetent ,
 193 .Fn getnetbyaddr ,
 194 .Fn getnetbyname ,
 195 .Fn setnetent ,
 196 and
 197 .Fn endnetent
 198 functions conform to
 199 .St -p1003.1-2004 .
 200 .Pp
 201 The
 202 .Fn getnetent_r ,
 203 .Fn getnetbyaddr_r ,
 204 and
 205 .Fn getnetbyname_r
 206 functions are not currently standardized.
 207 .Sh HISTORY
 208 The
 209 .Fn getnetent ,
 210 .Fn getnetbyaddr ,
 211 .Fn getnetbyname ,
 212 .Fn setnetent ,
 213 and
 214 .Fn endnetent
 215 functions appeared in
 216 .Bx 4.2 .
 217 .Pp
 218 The
 219 .Fn getnetent_r ,
 220 .Fn getnetbyaddr_r ,
 221 and
 222 .Fn getnetbyname_r
 223 functions appeared in
 224 .Dx 2.1 .
 225 .Sh BUGS
 226 The data space used by
 227 these functions is thread-specific; if future use requires the data, it should be
 228 copied before any subsequent calls to these functions overwrite it.
 229 Only Internet network
 230 numbers are currently understood.
 231 Expecting network numbers to fit
 232 in no more than 32 bits is probably
 233 naive.