external/bsd/libbind/dist/doc/getnetent.man3

   1 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
   2 .\" Copyright (c) 1995,1996,1999 by Internet Software Consortium
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  14 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .\" Id: getnetent.man3,v 1.2 2009/01/21 00:12:34 each Exp
  17 .\"
  18 .Dd May 20, 1996
  19 .Dt GETNETENT 3
  20 .Os BSD 4
  21 .Sh NAME
  22 .Nm getnetent ,
  23 .Nm getnetbyaddr ,
  24 .Nm getnetbyname ,
  25 .Nm setnetent ,
  26 .Nm endnetent
  27 .Nd get networks entry
  28 .Sh SYNOPSIS
  29 .Fd #include <netdb.h>
  30 .Ft struct netent *
  31 .Fn getnetent
  32 .Ft struct netent *
  33 .Fn getnetbyname "char name"
  34 .Ft struct netent *
  35 .Fn getnetbyaddr "unsigned long net" "int type"
  36 .Ft void
  37 .Fn setnetent "int stayopen"
  38 .Ft void
  39 .Fn endnetent
  40 .Sh DESCRIPTION
  41 The
  42 .Fn getnetent ,
  43 .Fn getnetbyname ,
  44 and
  45 .Fn getnetbyaddr
  46 subroutines
  47 each return a pointer to an object with the following structure
  48 containing the broken-out fields of a line in the
  49 .Pa networks
  50 database.
  51 .Bd -literal -offset indent
  52 struct  netent {
  53         char    *n_name;        /* official name of net */
  54         char    **n_aliases;    /* alias list */
  55         int     n_addrtype;     /* net number type */
  56         long    n_net;          /* net number */
  57 };
  58 .Ed
  59 .Pp
  60 The members of this structure are:
  61 .Bl -tag -width "n_addrtype"
  62 .It n_name
  63 The official name of the network.
  64 .It n_aliases
  65 A zero-terminated list of alternate names for the network.
  66 .It n_addrtype
  67 The type of the network number returned:
  68 .Dv AF_INET .
  69 .It n_net
  70 The network number.  Network numbers are returned in machine byte
  71 order.
  72 .El
  73 .Pp
  74 If the
  75 .Fa stayopen
  76 flag on a
  77 .Fn setnetent
  78 subroutine is NULL, the
  79 .Pa networks
  80 database is opened.  Otherwise, the
  81 .Fn setnetent
  82 has the effect of rewinding the
  83 .Pa networks
  84 database.
  85 The
  86 .Fn endnetent
  87 subroutine may be called to
  88 close the
  89 .Pa networks
  90 database when processing is complete.
  91 .Pp
  92 The
  93 .Fn getnetent
  94 subroutine simply reads the next
  95 line while
  96 .Fn getnetbyname
  97 and
  98 .Fn getnetbyaddr
  99 search until a matching
 100 .Fa name
 101 or
 102 .Fa net
 103 number is found
 104 (or until
 105 .Dv EOF
 106 is encountered).  The
 107 .Fa type must be
 108 .Dv AF_INET .
 109 The
 110 .Fn getnetent
 111 subroutine keeps a pointer in the database, allowing
 112 successive calls to be used to search the entire file.
 113 .Pp
 114 Before a
 115 .Ic while
 116 loop using
 117 .Fn getnetent ,
 118 a call to
 119 .Fn setnetent
 120 must be made
 121 in order to perform initialization; a call to
 122 .Fn endnetent
 123 must be used after the loop.  Both
 124 .Fn getnetbyname
 125 and
 126 .Fn getnetbyaddr
 127 make calls to
 128 .Fn setnetent
 129 and
 130 .Fn endnetent .
 131 .Sh FILES
 132 .Pa /etc/networks
 133 .Sh DIAGNOSTICS
 134 Null pointer (0) returned on
 135 .Dv EOF
 136 or error.
 137 .Sh SEE ALSO
 138 .Xr networks 5 ,
 139 RFC 1101.
 140 .Sh HISTORY
 141 The
 142 .Fn "getnetent" ,
 143 .Fn "getnetbyaddr" ,
 144 .Fn "getnetbyname" ,
 145 .Fn "setnetent" ,
 146 and
 147 .Fn "endnetent"
 148 functions appeared in
 149 .Bx 4.2 .
 150 .Sh BUGS
 151 The data space used by these functions is static; if future use requires the
 152 data, it should be copied before any subsequent calls to these functions
 153 overwrite it.  Only Internet network numbers are currently understood.
 154 Expecting network numbers to fit in no more than 32 bits is probably naive.