lib/libc/gen/getnetgrent.3

   1 .\"     $NetBSD: getnetgrent.3,v 1.11 2003/04/16 13:34:37 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1992, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)getnetgrent.3       8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd January 16, 1999
  33 .Dt GETNETGRENT 3
  34 .Os
  35 .Sh NAME
  36 .Nm getnetgrent ,
  37 .Nm innetgr ,
  38 .Nm setnetgrent ,
  39 .Nm endnetgrent
  40 .Nd netgroup database operations
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In netgroup.h
  45 .Ft int
  46 .Fn getnetgrent "const char **host" "const char **user" "const char **domain"
  47 .Ft int
  48 .Fn innetgr "const char *netgroup" "const char *host" "const char *user" "const char *domain"
  49 .Ft void
  50 .Fn setnetgrent "const char *netgroup"
  51 .Ft void
  52 .Fn endnetgrent void
  53 .Sh DESCRIPTION
  54 These functions operate on the netgroup database file which is described in
  55 .Xr netgroup 5 .
  56 .Pp
  57 The database defines a set of netgroups, each made up of one or more triples:
  58 .Bd -literal -offset indent
  59 (host, user, domain)
  60 .Ed
  61 .Pp
  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 .Dv NULL
  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 .Fn setnetgrent
  85 also sets the offset to the first member of the netgroup.
  86 .Pp
  87 The function
  88 .Fn innetgr
  89 searches for a match of all fields within the specified group.
  90 If any of the
  91 .Sy host ,
  92 .Sy user ,
  93 or
  94 .Sy domain
  95 arguments are
  96 .Dv NULL
  97 those fields will match any string value in the netgroup member.
  98 .Sh RETURN VALUES
  99 The function
 100 .Fn getnetgrent
 101 returns 0 for ``no more netgroup members'' and 1 otherwise.
 102 The function
 103 .Fn innetgr
 104 returns 1 for a successful match and 0 otherwise.
 105 The functions
 106 .Fn setnetgrent
 107 and
 108 .Fn endnetgrent
 109 have no return value.
 110 .Sh FILES
 111 .Bl -tag -width /etc/netgroup -compact
 112 .It Pa /etc/netgroup
 113 netgroup database file
 114 .El
 115 .Sh SEE ALSO
 116 .Xr netgroup 5 ,
 117 .Xr nsswitch.conf 5
 118 .Sh BUGS
 119 The function
 120 .Fn getnetgrent
 121 returns pointers to dynamically allocated data areas that are free'd when
 122 the function
 123 .Fn endnetgrent
 124 is called.