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
 101 .Dv AF_INET .
 102 .It Fa n_net
 103 The network number.
 104 Network numbers are returned in machine byte
 105 order.
 106 .El
 107 .Pp
 108 The
 109 .Fn getnetent
 110 function
 111 reads the next line of the file, opening the file if necessary.
 112 .Pp
 113 The
 114 .Fn setnetent
 115 function
 116 opens and rewinds the file.
 117 If the
 118 .Fa stayopen
 119 flag is non-zero,
 120 the net data base will not be closed after each call to
 121 .Fn getnetbyname
 122 or
 123 .Fn getnetbyaddr .
 124 .Pp
 125 The
 126 .Fn endnetent
 127 function
 128 closes the file.
 129 .Pp
 130 The
 131 .Fn getnetbyname
 132 function
 133 and
 134 .Fn getnetbyaddr
 135 sequentially search from the beginning
 136 of the file until a matching
 137 net name or
 138 net address and type is found,
 139 or until
 140 .Dv EOF
 141 is encountered.
 142 The
 143 .Fa type
 144 argument
 145 must be
 146 .Dv AF_INET .
 147 Network numbers are supplied in host order.
 148 .Pp
 149 The
 150 .Fn getnetent_r ,
 151 .Fn getnetbyaddr_r ,
 152 and
 153 .Fn getnetbyname_r
 154 functions are reentrant versions of the above functions that take a
 155 pointer to a
 156 .Vt netent
 157 structure which is used to store state information.
 158 The structure must be zero-filled before it is used
 159 and should be considered opaque for the sake of portability.
 160 These functions also take a pointer to another
 161 .Vt netent
 162 structure which is used to store the results of the database lookup.
 163 .Sh RETURN VALUES
 164 The
 165 .Fn getnetent ,
 166 .Fn getnetbyaddr ,
 167 and
 168 .Fn getnetbyname
 169 functions return a pointer to a
 170 .Vt netent
 171 structure on success or a null pointer if end-of-file
 172 is reached or an error occurs.
 173 .Pp
 174 The
 175 .Fn getnetent_r ,
 176 .Fn getnetbyaddr_r ,
 177 and
 178 .Fn getnetbyname_r
 179 functions return 0 on success or \-1 if end-of-file
 180 is reached or an error occurs.
 181 .Sh FILES
 182 .Bl -tag -width ".Pa /etc/nsswitch.conf" -compact
 183 .It Pa /etc/networks
 184 .It Pa /etc/nsswitch.conf
 185 .It Pa /etc/resolv.conf
 186 .El
 187 .Sh SEE ALSO
 188 .Xr networks 5
 189 .Pp
 190 .%T RFC 1101
 191 .Sh STANDARDS
 192 The
 193 .Fn getnetent ,
 194 .Fn getnetbyaddr ,
 195 .Fn getnetbyname ,
 196 .Fn setnetent ,
 197 and
 198 .Fn endnetent
 199 functions conform to
 200 .St -p1003.1-2004 .
 201 .Pp
 202 The
 203 .Fn getnetent_r ,
 204 .Fn getnetbyaddr_r ,
 205 and
 206 .Fn getnetbyname_r
 207 functions are not currently standardized.
 208 .Sh HISTORY
 209 The
 210 .Fn getnetent ,
 211 .Fn getnetbyaddr ,
 212 .Fn getnetbyname ,
 213 .Fn setnetent ,
 214 and
 215 .Fn endnetent
 216 functions appeared in
 217 .Bx 4.2 .
 218 .Pp
 219 The
 220 .Fn getnetent_r ,
 221 .Fn getnetbyaddr_r ,
 222 and
 223 .Fn getnetbyname_r
 224 functions appeared in
 225 .Dx 2.1 .
 226 .Sh BUGS
 227 The data space used by
 228 these functions is thread-specific; if future use requires the data, it should be
 229 copied before any subsequent calls to these functions overwrite it.
 230 Only Internet network
 231 numbers are currently understood.
 232 Expecting network numbers to fit
 233 in no more than 32 bits is probably
 234 naive.