gen.subproj/getprotoent.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 .\"     @(#)getprotoent.3       8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/net/getprotoent.3,v 1.4.2.3 2001/08/17 15:42:38 ru Exp $
  34 .\"
  35 .Dd June 4, 1993
  36 .Dt GETPROTOENT 3
  37 .Os
  38 .Sh NAME
  39 .Nm endprotoent ,
  40 .Nm getprotobyname ,
  41 .Nm getprotobynumber ,
  42 .Nm getprotoent ,
  43 .Nm setprotoent
  44 .Nd get protocol entry
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .Fd #include <netdb.h>
  49 .Ft void
  50 .Fo endprotoent
  51 .Fa void
  52 .Fc
  53 .Ft struct protoent *
  54 .Fo getprotobyname
  55 .Fa "const char *name"
  56 .Fc
  57 .Ft struct protoent *
  58 .Fo getprotobynumber
  59 .Fa "int proto"
  60 .Fc
  61 .Ft struct protoent *
  62 .Fo getprotoent
  63 .Fa void
  64 .Fc
  65 .Ft void
  66 .Fo setprotoent
  67 .Fa "int stayopen"
  68 .Fc
  69 .Sh DESCRIPTION
  70 The
  71 .Fn getprotoent ,
  72 .Fn getprotobyname ,
  73 and
  74 .Fn getprotobynumber
  75 functions
  76 each return a pointer to an object with the
  77 following structure
  78 containing the broken-out
  79 fields of a line in the network protocol data base,
  80 .Pa /etc/protocols .
  81 .Bd -literal -offset indent
  82 .Pp
  83 struct  protoent {
  84         char    *p_name;        /* official name of protocol */
  85         char    **p_aliases;    /* alias list */
  86         int     p_proto;        /* protocol number */
  87 };
  88 .Ed
  89 .Pp
  90 The members of this structure are:
  91 .Bl -tag -width p_aliases
  92 .It Fa p_name
  93 The official name of the protocol.
  94 .It Fa p_aliases
  95 A zero terminated list of alternate names for the protocol.
  96 .It Fa p_proto
  97 The protocol number.
  98 .El
  99 .Pp
 100 The
 101 .Fn getprotoent
 102 function
 103 reads the next line of the file, opening the file if necessary.
 104 .Pp
 105 The
 106 .Fn setprotoent
 107 function
 108 opens and rewinds the file.  If the
 109 .Fa stayopen
 110 flag is non-zero,
 111 the net data base will not be closed after each call to
 112 .Fn getprotobyname
 113 or
 114 .Fn getprotobynumber .
 115 .Pp
 116 The
 117 .Fn endprotoent
 118 function
 119 closes the file.
 120 .Pp
 121 The
 122 .Fn getprotobyname
 123 function
 124 and
 125 .Fn getprotobynumber
 126 sequentially search from the beginning
 127 of the file until a matching
 128 protocol name or
 129 protocol number is found,
 130 or until
 131 .Dv EOF
 132 is encountered.
 133 .Sh RETURN VALUES
 134 Null pointer
 135 (0) returned on
 136 .Dv EOF
 137 or error.
 138 .Sh FILES
 139 .Bl -tag -width /etc/protocols -compact
 140 .It Pa /etc/protocols
 141 .El
 142 .Sh SEE ALSO
 143 .Xr protocols 5
 144 .Sh HISTORY
 145 The
 146 .Fn getprotoent ,
 147 .Fn getprotobynumber ,
 148 .Fn getprotobyname ,
 149 .Fn setprotoent ,
 150 and
 151 .Fn endprotoent
 152 functions appeared in
 153 .Bx 4.2 .
 154 .Sh BUGS
 155 These functions use a static data space;
 156 if the data is needed for future use, it should be
 157 copied before any subsequent calls overwrite it.
 158 Only the Internet
 159 protocols are currently understood.