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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)getnetent.3 8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/net/getnetent.3,v 1.11.2.4 2001/12/14 18:33:55 ru Exp $
  34 .\" $DragonFly: src/lib/libc/net/getnetent.3,v 1.2 2003/06/17 04:26:44 dillon Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt GETNETENT 3
  38 .Os
  39 .Sh NAME
  40 .Nm getnetent ,
  41 .Nm getnetbyaddr ,
  42 .Nm getnetbyname ,
  43 .Nm setnetent ,
  44 .Nm endnetent
  45 .Nd get network entry
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In netdb.h
  50 .Ft struct netent *
  51 .Fn getnetent void
  52 .Ft struct netent *
  53 .Fn getnetbyname "const char *name"
  54 .Ft struct netent *
  55 .Fn getnetbyaddr "unsigned long net" "int type"
  56 .Ft void
  57 .Fn setnetent "int stayopen"
  58 .Ft void
  59 .Fn endnetent void
  60 .Sh DESCRIPTION
  61 The
  62 .Fn getnetent ,
  63 .Fn getnetbyname ,
  64 and
  65 .Fn getnetbyaddr
  66 functions
  67 each return a pointer to an object with the
  68 following structure
  69 containing the broken-out
  70 fields of a line in the network data base,
  71 .Pa /etc/networks .
  72 .Bd -literal -offset indent
  73 struct  netent {
  74         char            *n_name;        /* official name of net */
  75         char            **n_aliases;    /* alias list */
  76         int             n_addrtype;     /* net number type */
  77         unsigned long   n_net;          /* net number */
  78 };
  79 .Ed
  80 .Pp
  81 The members of this structure are:
  82 .Bl -tag -width n_addrtype
  83 .It Fa n_name
  84 The official name of the network.
  85 .It Fa n_aliases
  86 A zero terminated list of alternate names for the network.
  87 .It Fa n_addrtype
  88 The type of the network number returned; currently only AF_INET.
  89 .It Fa n_net
  90 The network number.  Network numbers are returned in machine byte
  91 order.
  92 .El
  93 .Pp
  94 The
  95 .Fn getnetent
  96 function
  97 reads the next line of the file, opening the file if necessary.
  98 .Pp
  99 The
 100 .Fn setnetent
 101 function
 102 opens and rewinds the file.  If the
 103 .Fa stayopen
 104 flag is non-zero,
 105 the net data base will not be closed after each call to
 106 .Fn getnetbyname
 107 or
 108 .Fn getnetbyaddr .
 109 .Pp
 110 The
 111 .Fn endnetent
 112 function
 113 closes the file.
 114 .Pp
 115 The
 116 .Fn getnetbyname
 117 function
 118 and
 119 .Fn getnetbyaddr
 120 sequentially search from the beginning
 121 of the file until a matching
 122 net name or
 123 net address and type is found,
 124 or until
 125 .Dv EOF
 126 is encountered.
 127 The
 128 .Fa type
 129 must be
 130 .Dv AF_INET .
 131 Network numbers are supplied in host order.
 132 .Sh FILES
 133 .Bl -tag -width /etc/networks -compact
 134 .It Pa /etc/networks
 135 .El
 136 .Sh DIAGNOSTICS
 137 Null pointer
 138 (0) returned on
 139 .Dv EOF
 140 or error.
 141 .Sh SEE ALSO
 142 .Xr networks 5
 143 .Pp
 144 .%T RFC 1101
 145 .Sh HISTORY
 146 The
 147 .Fn getnetent ,
 148 .Fn getnetbyaddr ,
 149 .Fn getnetbyname ,
 150 .Fn setnetent ,
 151 and
 152 .Fn endnetent
 153 functions appeared in
 154 .Bx 4.2 .
 155 .Sh BUGS
 156 The data space used by
 157 these functions is static; if future use requires the data, it should be
 158 copied before any subsequent calls to these functions overwrite it.
 159 Only Internet network
 160 numbers are currently understood.
 161 Expecting network numbers to fit
 162 in no more than 32 bits is probably
 163 naive.