lookup.subproj/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 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)getnetgrent.3       8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD: src/lib/libc/gen/getnetgrent.3,v 1.13 2007/01/09 00:27:54 imp Exp $
  30 .\"
  31 .Dd June 4, 1993
  32 .Dt GETNETGRENT 3
  33 .Os
  34 .Sh NAME
  35 .Nm getnetgrent ,
  36 .Nm innetgr ,
  37 .Nm setnetgrent ,
  38 .Nm endnetgrent
  39 .Nd netgroup database operations
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In netdb.h
  44 .Ft int
  45 .Fn getnetgrent "char **host" "char **user" "char **domain"
  46 .Ft int
  47 .Fn innetgr "const char *netgroup" "const char *host" "const char *user" "const char *domain"
  48 .Ft void
  49 .Fn setnetgrent "const char *netgroup"
  50 .Ft void
  51 .Fn endnetgrent void
  52 .Sh DESCRIPTION
  53 These functions operate on the netgroup database file
  54 .Pa /etc/netgroup
  55 which is described
  56 in
  57 .Xr netgroup 5 .
  58 The database defines a set of netgroups, each made up of one or more triples:
  59 .Bd -literal -offset indent
  60 (host, user, domain)
  61 .Ed
  62 that defines a combination of host, user and domain.
  63 Any of the three fields may be specified as ``wildcards'' that match any
  64 string.
  65 .Pp
  66 The function
  67 .Fn getnetgrent
  68 sets the three pointer arguments to the strings of the next member of the
  69 current netgroup.
  70 If any of the string pointers are
  71 .Sy (char *)0
  72 that field is considered a wildcard.
  73 .Pp
  74 The functions
  75 .Fn setnetgrent
  76 and
  77 .Fn endnetgrent
  78 set the current netgroup and terminate the current netgroup respectively.
  79 If
  80 .Fn setnetgrent
  81 is called with a different netgroup than the previous call, an implicit
  82 .Fn endnetgrent
  83 is implied.
  84 The
  85 .Fn setnetgrent
  86 function
  87 also sets the offset to the first member of the netgroup.
  88 .Pp
  89 The function
  90 .Fn innetgr
  91 searches for a match of all fields within the specified group.
  92 If any of the
  93 .Sy host ,
  94 .Sy user ,
  95 or
  96 .Sy domain
  97 arguments are
  98 .Sy (char *)0
  99 those fields will match any string value in the netgroup member.
 100 .Sh RETURN VALUES
 101 The function
 102 .Fn getnetgrent
 103 returns 0 for ``no more netgroup members'' and 1 otherwise.
 104 The function
 105 .Fn innetgr
 106 returns 1 for a successful match and 0 otherwise.
 107 The functions
 108 .Fn setnetgrent
 109 and
 110 .Fn endnetgrent
 111 have no return value.
 112 .Sh FILES
 113 .Bl -tag -width /etc/netgroup -compact
 114 .It Pa /etc/netgroup
 115 netgroup database file
 116 .El
 117 .Sh COMPATIBILITY
 118 The netgroup members have three string fields to maintain compatibility
 119 with other vendor implementations, however it is not obvious what use the
 120 .Sy domain
 121 string has within
 122 .Bx .
 123 .Sh SEE ALSO
 124 .Xr netgroup 5
 125 .Sh BUGS
 126 The function
 127 .Fn getnetgrent
 128 returns pointers to dynamically allocated data areas that are freed when
 129 the function
 130 .Fn endnetgrent
 131 is called.