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

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