lib/libc/gen/getnetgrent.3

   1 .\" Copyright (c) 1992, 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 .\"     @(#)getnetgrent.3       8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/gen/getnetgrent.3,v 1.6.2.5 2003/03/13 18:05:37 trhodes Exp $
  34 .\" $DragonFly: src/lib/libc/gen/getnetgrent.3,v 1.3 2006/02/17 19:35:06 swildner Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt GETNETGRENT 3
  38 .Os
  39 .Sh NAME
  40 .Nm getnetgrent ,
  41 .Nm innetgr ,
  42 .Nm setnetgrent ,
  43 .Nm endnetgrent
  44 .Nd netgroup database operations
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In netdb.h
  49 .Ft int
  50 .Fn getnetgrent "char **host" "char **user" "char **domain"
  51 .Ft int
  52 .Fn innetgr "const char *netgroup" "const char *host" "const char *user" "const char *domain"
  53 .Ft void
  54 .Fn setnetgrent "const char *netgroup"
  55 .Ft void
  56 .Fn endnetgrent void
  57 .Sh DESCRIPTION
  58 These functions operate on the netgroup database file
  59 .Pa /etc/netgroup
  60 which is described
  61 in
  62 .Xr netgroup 5 .
  63 The database defines a set of netgroups, each made up of one or more triples:
  64 .Bd -literal -offset indent
  65 (host, user, domain)
  66 .Ed
  67 that defines a combination of host, user and domain.
  68 Any of the three fields may be specified as ``wildcards'' that match any
  69 string.
  70 .Pp
  71 The function
  72 .Fn getnetgrent
  73 sets the three pointer arguments to the strings of the next member of the
  74 current netgroup.
  75 If any of the string pointers are
  76 .Dv NULL
  77 that field is considered a wildcard.
  78 .Pp
  79 The functions
  80 .Fn setnetgrent
  81 and
  82 .Fn endnetgrent
  83 set the current netgroup and terminate the current netgroup respectively.
  84 If
  85 .Fn setnetgrent
  86 is called with a different netgroup than the previous call, an implicit
  87 .Fn endnetgrent
  88 is implied.
  89 The
  90 .Fn setnetgrent
  91 function
  92 also sets the offset to the first member of the netgroup.
  93 .Pp
  94 The function
  95 .Fn innetgr
  96 searches for a match of all fields within the specified group.
  97 If any of the
  98 .Fa host ,
  99 .Fa user ,
 100 or
 101 .Fa domain
 102 arguments are
 103 .Dv NULL
 104 those fields will match any string value in the netgroup member.
 105 .Sh RETURN VALUES
 106 The function
 107 .Fn getnetgrent
 108 returns 0 for ``no more netgroup members'' and 1 otherwise.
 109 The function
 110 .Fn innetgr
 111 returns 1 for a successful match and 0 otherwise.
 112 The functions
 113 .Fn setnetgrent
 114 and
 115 .Fn endnetgrent
 116 have no return value.
 117 .Sh FILES
 118 .Bl -tag -width /etc/netgroup -compact
 119 .It Pa /etc/netgroup
 120 netgroup database file
 121 .El
 122 .Sh COMPATIBILITY
 123 The netgroup members have three string fields to maintain compatibility
 124 with other vendor implementations, however it is not obvious what use the
 125 .Fa domain
 126 string has within
 127 .Bx .
 128 .Sh SEE ALSO
 129 .Xr netgroup 5
 130 .Sh BUGS
 131 The function
 132 .Fn getnetgrent
 133 returns pointers to dynamically allocated data areas that are freed when
 134 the function
 135 .Fn endnetgrent
 136 is called.