1.\" $NetBSD: pw_init.3,v 1.8 2002/02/07 07:00:52 ross 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. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.Dd December 15, 1995 39.Dt PW_INIT 3 40.Os 41.Sh NAME 42.Nm pw_init , 43.Nm pw_edit , 44.Nm pw_prompt , 45.Nm pw_copy , 46.Nm pw_scan , 47.Nm pw_error 48.Nd utility functions for interactive passwd file updates 49.Sh LIBRARY 50.Lb libutil 51.Sh SYNOPSIS 52.Fd #include \*[Lt]pwd.h\*[Gt] 53.Fd #include \*[Lt]util.h\*[Gt] 54.Ft void 55.Fn pw_init "void" 56.Ft void 57.Fn pw_edit "int notsetuid" "const char *filename" 58.Ft void 59.Fn pw_prompt "void" 60.Ft void 61.Fn pw_copy "int ffd" "int tfd" "struct passwd *pw" "struct passwd *old_pw" 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 67These functions are designed as conveniences for interactive programs 68which update the passwd file and do nothing else. They generally 69handle errors by printing out a message to the standard error stream 70and possibly aborting the process. 71.Pp 72The 73.Fn pw_init 74function prepares for a passwd update by unlimiting all resource 75constraints, disabling core dumps (thus preventing dumping the 76contents of the passwd database into a world-readable file), and 77disabling most signals. 78.Pp 79The 80.Fn pw_edit 81function runs an editor (named by the environment variable EDITOR, or 82.Pa /usr/bin/vi 83if EDITOR is not set) on the file 84.Fa filename 85(or 86.Pa /etc/ptmp 87if 88.Fa filename 89is NULL). If 90.Fa notsetuid 91is nonzero, 92.Fn pw_edit 93will set the effective user and group ID to the real user and group ID 94before running the editor. 95.Pp 96The 97.Fn pw_prompt 98function asks the user whether he or she wants to re-edit the password 99file; if the answer is no, 100.Fn pw_prompt 101deletes the lock file and exits the process. 102.Pp 103The 104.Fn pw_copy 105function reads a passwd file from 106.Fa ffd 107and writes it to 108.Fa tfd , 109updating the entry corresponding to pw-\*[Gt]pw_name with the information 110in 111.Fa pw . 112If 113.Fa old_pw 114is not NULL, it checks to make sure the old entry is the same as 115the one described in 116.Fa old_pw 117or the process is aborted. If an entry is not found to match 118.Fa pw , 119a new entry is appended to the passwd file only if the real user 120ID is 0. 121.Pp 122The 123.Fn pw_scan 124function accepts in 125.Fa bp 126a passwd entry as it would be represented in 127.Pa /etc/master.passwd 128and fills in 129.Fa pw 130with corresponding values; string fields in 131.Fa pw 132will be pointers into 133.Fa bp . 134Some characters in 135.Fa bp 136will be overwritten with 0s in order to terminate the strings pointed 137to by 138.Fa pw . 139If 140.Fa flags 141is non-null, it should be cleared and the following options 142enabled if required: 143.Bl -tag -offset indent -width _PASSWORD_OLDFMT 144.It Dv _PASSWORD_NOWARN 145Don't print warnings. 146.It Dv _PASSWORD_OLDFMT 147Parse 148.Fa bp 149as an old format entry as found in 150.Pa /etc/passwd . 151.El 152.Pp 153Upon return it is cleared, and filled in with the following flags: 154.Bl -tag -offset indent -width _PASSWORD_NOGID 155.It Dv _PASSWORD_NOUID 156The uid field of 157.Fa bp 158is empty. 159.It Dv _PASSWORD_NOGID 160The gid field of 161.Fa bp 162is empty. 163.It Dv _PASSWD_NOCHG 164The change field of 165.Fa bp 166is empty. 167.It Dv _PASSWD_NOEXP 168The expire field of 169.Fa bp 170is empty. 171.El 172.Pp 173The 174.Fn pw_error 175function displays an error message, aborts the current passwd update, 176and exits the current process. If 177.Fa err 178is non-zero, a warning message beginning with 179.Fa name 180is printed for the current value of 181.Va errno . 182The process exits with status 183.Fa eval . 184.Sh RETURN VALUES 185The 186.Fn pw_scan 187function prints a warning message and returns 0 if the string in the 188.Fa bp 189argument is not a valid passwd string. Otherwise, 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