lib/libutil/pw_init.3

   1 .\"     $NetBSD: pw_init.3,v 1.13 2004/08/03 23:29:05 thorpej 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 NULL).
  90 If
  91 .Fa notsetuid
  92 is nonzero,
  93 .Fn pw_edit
  94 will set the effective user and group ID to the real user and group ID
  95 before running the editor.
  96 .Pp
  97 The
  98 .Fn pw_prompt
  99 function asks the user whether he or she wants to re-edit the password
 100 file; if the answer is no,
 101 .Fn pw_prompt
 102 deletes the lock file and exits the process.
 103 .Pp
 104 The
 105 .Fn pw_copy
 106 function reads a passwd file from
 107 .Fa ffd
 108 and writes it to
 109 .Fa tfd ,
 110 updating the entry corresponding to pw-\*[Gt]pw_name with the information
 111 in
 112 .Fa pw .
 113 If
 114 .Fa old_pw
 115 is not NULL, it checks to make sure the old entry is the same as
 116 the one described in
 117 .Fa old_pw
 118 or the process is aborted.
 119 If an entry is not found to match
 120 .Fa pw ,
 121 a new entry is appended to the passwd file only if the real user
 122 ID is 0.
 123 If an error occurs,
 124 .Fn pw_copy
 125 will display a message on
 126 .Dv stderr
 127 and call
 128 .Fn pw_error .
 129 .Pp
 130 The
 131 .Fn pw_copyx
 132 function performs the same operation as
 133 .Fn pw_copy
 134 with the exception of error handling.
 135 Upon an error,
 136 .Fn pw_copyx
 137 will write an error message into the buffer pointed to by
 138 .Fa errbuf
 139 which has the size
 140 .Fa errbufsz .
 141 .Pp
 142 The
 143 .Fn pw_scan
 144 function accepts in
 145 .Fa bp
 146 a passwd entry as it would be represented in
 147 .Pa /etc/master.passwd
 148 and fills in
 149 .Fa pw
 150 with corresponding values; string fields in
 151 .Fa pw
 152 will be pointers into
 153 .Fa bp .
 154 Some characters in
 155 .Fa bp
 156 will be overwritten with 0s in order to terminate the strings pointed
 157 to by
 158 .Fa pw .
 159 If
 160 .Fa flags
 161 is non-null, it should be cleared and the following options
 162 enabled if required:
 163 .Bl -tag -offset indent -width _PASSWORD_OLDFMT
 164 .It Dv _PASSWORD_NOWARN
 165 Don't print warnings.
 166 .It Dv _PASSWORD_OLDFMT
 167 Parse
 168 .Fa bp
 169 as an old format entry as found in
 170 .Pa /etc/passwd .
 171 .El
 172 .Pp
 173 Upon return it is cleared, and filled in with the following flags:
 174 .Bl -tag -offset indent -width _PASSWORD_NOGID
 175 .It Dv _PASSWORD_NOUID
 176 The uid field of
 177 .Fa bp
 178 is empty.
 179 .It Dv _PASSWORD_NOGID
 180 The gid field of
 181 .Fa bp
 182 is empty.
 183 .It Dv _PASSWORD_NOCHG
 184 The change field of
 185 .Fa bp
 186 is empty.
 187 .It Dv _PASSWORD_NOEXP
 188 The expire field of
 189 .Fa bp
 190 is empty.
 191 .El
 192 .Pp
 193 The
 194 .Fn pw_error
 195 function displays an error message, aborts the current passwd update,
 196 and exits the current process.
 197 If
 198 .Fa err
 199 is non-zero, a warning message beginning with
 200 .Fa name
 201 is printed for the current value of
 202 .Va errno .
 203 The process exits with status
 204 .Fa eval .
 205 .Sh RETURN VALUES
 206 The
 207 .Fn pw_copyx
 208 function returns 1 if the new password entry was successfully written
 209 to the destination file, and 0 otherwise.
 210 .Pp
 211 The
 212 .Fn pw_scan
 213 function prints a warning message and returns 0 if the string in the
 214 .Fa bp
 215 argument is not a valid passwd string.
 216 Otherwise,
 217 .Fn pw_scan
 218 returns 1.
 219 .Sh FILES
 220 .Bl -tag -width /etc/master.passwd -compact
 221 .It Pa /etc/master.passwd
 222 .It Pa /etc/ptmp
 223 .El
 224 .Sh SEE ALSO
 225 .Xr pw_lock 3 ,
 226 .Xr passwd 5