lib/libutil/pw_getconf.3

   1 .\"     $NetBSD: pw_getconf.3,v 1.12 2010/05/04 06:41:27 jruoho Exp $
   2 .\"
   3 .\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
   4 .\" 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. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"      This product includes software developed by Niels Provos.
  17 .\" 4. The name of the author may not be used to endorse or promote products
  18 .\"    derived from this software without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  21 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  22 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  25 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  29 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .\" from OpenBSD: pw_getconf.3,v 1.5 1999/09/21 04:52:46 csapuntz Exp
  32 .\"
  33 .Dd May 4, 2010
  34 .Dt PW_GETCONF 3
  35 .Os
  36 .Sh NAME
  37 .Nm pw_getconf ,
  38 .Nm pw_getpwconf
  39 .Nd password encryption configuration access function
  40 .Sh LIBRARY
  41 .Lb libutil
  42 .Sh SYNOPSIS
  43 .In util.h
  44 .Ft void
  45 .Fn pw_getconf "char *data" "size_t len" "const char *key" "const char *option"
  46 .Ft void
  47 .Fn pw_getpwconf "char *data" "size_t len" "const struct passwd *pwd" "const char *option"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn pw_getconf
  51 function reads
  52 .Pa /etc/passwd.conf
  53 and retrieves the value of the option specified
  54 by
  55 .Pa option
  56 from the section given by
  57 .Pa key .
  58 If no suitable entry is found
  59 for the
  60 .Pa key
  61 an empty string will be returned in data.
  62 .Pp
  63 To retrieve default values the key
  64 .Pa default
  65 can be used.
  66 In this case, if
  67 .Pa /etc/passwd.conf
  68 does not exist or does not contain a
  69 .Pa default
  70 section, the built-in defaults will be returned.
  71 They are as follows:
  72 .Bl -column localcipher data -offset indent
  73 .It Sy option   data
  74 .It ypcipher    old
  75 .It localcipher old
  76 .El
  77 .Pp
  78 An empty string is returned for all errors.
  79 .Pp
  80 .Fn pw_getpwconf
  81 returns the value for the option specified for the particular user
  82 specified in
  83 .Ar pwd .
  84 If that option is not found, then it tries to find the option in
  85 the primary group of that user, and if that fails, then it returns
  86 the default entry.
  87 .Sh FILES
  88 .Bl -tag -width /etc/passwd.conf -compact
  89 .It Pa /etc/passwd.conf
  90 .El
  91 .Sh ERRORS
  92 .Fn pw_getconf
  93 and
  94 .Fn pw_getpwconf
  95 will fail if:
  96 .Bl -tag -width Er
  97 .It Bq Er ENOENT
  98 There is no option named
  99 .Pa option
 100 in the specified key.
 101 .It Bq Er ENOTDIR
 102 There is no key in
 103 .Pa /etc/passwd.conf
 104 named
 105 .Pa key .
 106 .El
 107 .Sh SEE ALSO
 108 .Xr passwd 5 ,
 109 .Xr passwd.conf 5
 110 .Sh HISTORY
 111 The
 112 .Fn pw_getconf
 113 function first appeared in
 114 .Nx 1.6 .