lib/libutil/pw_init.3

   1 .\"     $NetBSD: pw_init.3,v 1.15 2010/05/05 22:05:31 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1995
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software developed by the Computer Systems
   7 .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
   8 .\" BG 91-66 and contributed to Berkeley.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .Dd August 1, 2004
  35 .Dt PW_INIT 3
  36 .Os
  37 .Sh NAME
  38 .Nm pw_init ,
  39 .Nm pw_edit ,
  40 .Nm pw_prompt ,
  41 .Nm pw_copy ,
  42 .Nm pw_copyx ,
  43 .Nm pw_scan ,
  44 .Nm pw_error
  45 .Nd utility functions for interactive passwd file updates
  46 .Sh LIBRARY
  47 .Lb libutil
  48 .Sh SYNOPSIS
  49 .In pwd.h
  50 .In util.h
  51 .Ft void
  52 .Fn pw_init "void"
  53 .Ft void
  54 .Fn pw_edit "int notsetuid" "const char *filename"
  55 .Ft void
  56 .Fn pw_prompt "void"
  57 .Ft void
  58 .Fn pw_copy "int ffd" "int tfd" "struct passwd *pw" "struct passwd *old_pw"
  59 .Ft int
  60 .Fn pw_copyx "int ffd" "int tfd" "struct passwd *pw" "struct passwd *old_pw" \
  61     "char *errbuf" "size_t errbufsz"
  62 .Ft int
  63 .Fn pw_scan "char *bp" "struct passwd *pw" "int *flags"
  64 .Ft void
  65 .Fn pw_error "const char *name" "int err" "int eval"
  66 .Sh DESCRIPTION
  67 These functions are designed as conveniences for interactive programs
  68 which update the passwd file and do nothing else.
  69 They generally handle errors by printing out a message to the standard error
  70 stream and possibly aborting the process.
  71 .Pp
  72 The
  73 .Fn pw_init
  74 function prepares for a passwd update by unlimiting all resource
  75 constraints, disabling core dumps (thus preventing dumping the
  76 contents of the passwd database into a world-readable file), and
  77 disabling most signals.
  78 .Pp
  79 The
  80 .Fn pw_edit
  81 function runs an editor (named by the environment variable EDITOR, or
  82 .Pa /usr/bin/vi
  83 if EDITOR is not set) on the file
  84 .Fa filename
  85 (or
  86 .Pa /etc/ptmp
  87 if
  88 .Fa filename
  89 is
  90 .Dv NULL ) .
  91 If
  92 .Fa notsetuid
  93 is nonzero,
  94 .Fn pw_edit
  95 will set the effective user and group ID to the real user and group ID
  96 before running the editor.
  97 .Pp
  98 The
  99 .Fn pw_prompt
 100 function asks the user whether he or she wants to re-edit the password
 101 file; if the answer is no,
 102 .Fn pw_prompt
 103 deletes the lock file and exits the process.
 104 .Pp
 105 The
 106 .Fn pw_copy
 107 function reads a passwd file from
 108 .Fa ffd
 109 and writes it to
 110 .Fa tfd ,
 111 updating the entry corresponding to pw-\*[Gt]pw_name with the information
 112 in
 113 .Fa pw .
 114 If
 115 .Fa old_pw
 116 is not
 117 .Dv NULL ,
 118 it checks to make sure the old entry is the same as
 119 the one described in
 120 .Fa old_pw
 121 or the process is aborted.
 122 If an entry is not found to match
 123 .Fa pw ,
 124 a new entry is appended to the passwd file only if the real user
 125 ID is 0.
 126 If an error occurs,
 127 .Fn pw_copy
 128 will display a message on
 129 .Dv stderr
 130 and call
 131 .Fn pw_error .
 132 .Pp
 133 The
 134 .Fn pw_copyx
 135 function performs the same operation as
 136 .Fn pw_copy
 137 with the exception of error handling.
 138 Upon an error,
 139 .Fn pw_copyx
 140 will write an error message into the buffer pointed to by
 141 .Fa errbuf
 142 which has the size
 143 .Fa errbufsz .
 144 .Pp
 145 The
 146 .Fn pw_scan
 147 function accepts in
 148 .Fa bp
 149 a passwd entry as it would be represented in
 150 .Pa /etc/master.passwd
 151 and fills in
 152 .Fa pw
 153 with corresponding values; string fields in
 154 .Fa pw
 155 will be pointers into
 156 .Fa bp .
 157 Some characters in
 158 .Fa bp
 159 will be overwritten with 0s in order to terminate the strings pointed
 160 to by
 161 .Fa pw .
 162 If
 163 .Fa flags
 164 is non-null, it should be cleared and the following options
 165 enabled if required:
 166 .Bl -tag -offset indent -width _PASSWORD_OLDFMT
 167 .It Dv _PASSWORD_NOWARN
 168 Don't print warnings.
 169 .It Dv _PASSWORD_OLDFMT
 170 Parse
 171 .Fa bp
 172 as an old format entry as found in
 173 .Pa /etc/passwd .
 174 .El
 175 .Pp
 176 Upon return it is cleared, and filled in with the following flags:
 177 .Bl -tag -offset indent -width _PASSWORD_NOGID
 178 .It Dv _PASSWORD_NOUID
 179 The uid field of
 180 .Fa bp
 181 is empty.
 182 .It Dv _PASSWORD_NOGID
 183 The gid field of
 184 .Fa bp
 185 is empty.
 186 .It Dv _PASSWORD_NOCHG
 187 The change field of
 188 .Fa bp
 189 is empty.
 190 .It Dv _PASSWORD_NOEXP
 191 The expire field of
 192 .Fa bp
 193 is empty.
 194 .El
 195 .Pp
 196 The
 197 .Fn pw_error
 198 function displays an error message, aborts the current passwd update,
 199 and exits the current process.
 200 If
 201 .Fa err
 202 is non-zero, a warning message beginning with
 203 .Fa name
 204 is printed for the current value of
 205 .Va errno .
 206 The process exits with status
 207 .Fa eval .
 208 .Sh RETURN VALUES
 209 The
 210 .Fn pw_copyx
 211 function returns 1 if the new password entry was successfully written
 212 to the destination file, and 0 otherwise.
 213 .Pp
 214 The
 215 .Fn pw_scan
 216 function prints a warning message and returns 0 if the string in the
 217 .Fa bp
 218 argument is not a valid passwd string.
 219 Otherwise,
 220 .Fn pw_scan
 221 returns 1.
 222 .Sh FILES
 223 .Bl -tag -width /etc/master.passwd -compact
 224 .It Pa /etc/master.passwd
 225 .It Pa /etc/ptmp
 226 .El
 227 .Sh SEE ALSO
 228 .Xr pw_lock 3 ,
 229 .Xr passwd 5