1.\" $NetBSD: pw_init.3,v 1.12 2003/08/07 16:45:00 agc 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 December 15, 1995 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_scan , 43.Nm pw_error 44.Nd utility functions for interactive passwd file updates 45.Sh LIBRARY 46.Lb libutil 47.Sh SYNOPSIS 48.In pwd.h 49.In util.h 50.Ft void 51.Fn pw_init "void" 52.Ft void 53.Fn pw_edit "int notsetuid" "const char *filename" 54.Ft void 55.Fn pw_prompt "void" 56.Ft void 57.Fn pw_copy "int ffd" "int tfd" "struct passwd *pw" "struct passwd *old_pw" 58.Ft int 59.Fn pw_scan "char *bp" "struct passwd *pw" "int *flags" 60.Ft void 61.Fn pw_error "const char *name" "int err" "int eval" 62.Sh DESCRIPTION 63These functions are designed as conveniences for interactive programs 64which update the passwd file and do nothing else. 65They generally handle errors by printing out a message to the standard error 66stream and possibly aborting the process. 67.Pp 68The 69.Fn pw_init 70function prepares for a passwd update by unlimiting all resource 71constraints, disabling core dumps (thus preventing dumping the 72contents of the passwd database into a world-readable file), and 73disabling most signals. 74.Pp 75The 76.Fn pw_edit 77function runs an editor (named by the environment variable EDITOR, or 78.Pa /usr/bin/vi 79if EDITOR is not set) on the file 80.Fa filename 81(or 82.Pa /etc/ptmp 83if 84.Fa filename 85is NULL). 86If 87.Fa notsetuid 88is nonzero, 89.Fn pw_edit 90will set the effective user and group ID to the real user and group ID 91before running the editor. 92.Pp 93The 94.Fn pw_prompt 95function asks the user whether he or she wants to re-edit the password 96file; if the answer is no, 97.Fn pw_prompt 98deletes the lock file and exits the process. 99.Pp 100The 101.Fn pw_copy 102function reads a passwd file from 103.Fa ffd 104and writes it to 105.Fa tfd , 106updating the entry corresponding to pw-\*[Gt]pw_name with the information 107in 108.Fa pw . 109If 110.Fa old_pw 111is not NULL, it checks to make sure the old entry is the same as 112the one described in 113.Fa old_pw 114or the process is aborted. 115If an entry is not found to match 116.Fa pw , 117a new entry is appended to the passwd file only if the real user 118ID is 0. 119.Pp 120The 121.Fn pw_scan 122function accepts in 123.Fa bp 124a passwd entry as it would be represented in 125.Pa /etc/master.passwd 126and fills in 127.Fa pw 128with corresponding values; string fields in 129.Fa pw 130will be pointers into 131.Fa bp . 132Some characters in 133.Fa bp 134will be overwritten with 0s in order to terminate the strings pointed 135to by 136.Fa pw . 137If 138.Fa flags 139is non-null, it should be cleared and the following options 140enabled if required: 141.Bl -tag -offset indent -width _PASSWORD_OLDFMT 142.It Dv _PASSWORD_NOWARN 143Don't print warnings. 144.It Dv _PASSWORD_OLDFMT 145Parse 146.Fa bp 147as an old format entry as found in 148.Pa /etc/passwd . 149.El 150.Pp 151Upon return it is cleared, and filled in with the following flags: 152.Bl -tag -offset indent -width _PASSWORD_NOGID 153.It Dv _PASSWORD_NOUID 154The uid field of 155.Fa bp 156is empty. 157.It Dv _PASSWORD_NOGID 158The gid field of 159.Fa bp 160is empty. 161.It Dv _PASSWORD_NOCHG 162The change field of 163.Fa bp 164is empty. 165.It Dv _PASSWORD_NOEXP 166The expire field of 167.Fa bp 168is empty. 169.El 170.Pp 171The 172.Fn pw_error 173function displays an error message, aborts the current passwd update, 174and exits the current process. 175If 176.Fa err 177is non-zero, a warning message beginning with 178.Fa name 179is printed for the current value of 180.Va errno . 181The process exits with status 182.Fa eval . 183.Sh RETURN VALUES 184The 185.Fn pw_scan 186function prints a warning message and returns 0 if the string in the 187.Fa bp 188argument is not a valid passwd string. 189Otherwise, 190.Fn pw_scan 191returns 1. 192.Sh FILES 193.Bl -tag -width /etc/master.passwd -compact 194.It Pa /etc/master.passwd 195.It Pa /etc/ptmp 196.El 197.Sh SEE ALSO 198.Xr pw_lock 3 , 199.Xr passwd 5 200