1.\" $OpenBSD: pw_init.3,v 1.7 2003/06/02 20:18:42 millert 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_setdir , 40.Nm pw_file , 41.Nm pw_edit , 42.Nm pw_prompt , 43.Nm pw_copy , 44.Nm pw_scan , 45.Nm pw_error 46.Nd utility functions for interactive passwd file updates 47.Sh SYNOPSIS 48.Fd #include <pwd.h> 49.Fd #include <util.h> 50.Ft void 51.Fn pw_init 52.Ft void 53.Fn pw_setdir "const char *directory" 54.Ft char * 55.Fn pw_file "const char *filename" 56.Ft void 57.Fn pw_edit "int notsetuid" "const char *filename" 58.Ft void 59.Fn pw_prompt 60.Ft void 61.Fn pw_copy "int ffd" "int tfd" "struct passwd *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. 69They generally 70handle errors by printing out a message to the standard error stream 71and possibly aborting the process. 72.Pp 73The 74.Fn pw_init 75function prepares for a passwd update by unlimiting all resource 76constraints, disabling core dumps (thus preventing dumping the 77contents of the passwd database into a world-readable file), and 78disabling most signals. 79.Pp 80The 81.Fn pw_setdir 82function sets an alternative directory where the rest of the functions look 83for password-related files. 84Use this if you are writing utilities that should 85be able to handle password files outside of 86.Pa /etc . 87.Pp 88The 89.Fn pw_file 90function transforms filenames so that they end up in the directory specified 91to the latest 92.Fn pw_setdir 93call. 94The rule is that all directories are stripped of the given name and 95only the filename is appended to the directory. 96.Pp 97The 98.Fn pw_edit 99function runs an editor (named by the environment variable EDITOR, or 100.Pa /usr/bin/vi 101if EDITOR is not set) on the file 102.Fa filename 103(or 104.Pa /etc/ptmp 105if 106.Fa filename 107is NULL). 108If 109.Fa notsetuid 110is nonzero, 111.Fn pw_edit 112will set the effective user and group ID to the real user and group ID 113before running the editor. 114.Pp 115The 116.Fn pw_prompt 117function asks the user whether he or she wants to re-edit the password 118file; if the answer is no, 119.Fn pw_prompt 120deletes the lock file and exits the process. 121.Pp 122The 123.Fn pw_copy 124function reads a passwd file from 125.Fa ffd 126and writes it to 127.Fa tfd , 128updating the entry corresponding to pw->pw_name with the information 129in 130.Fa pw . 131.Pp 132The 133.Fn pw_scan 134function accepts in 135.Fa bp 136a passwd entry as it would be represented in 137.Pa /etc/master.passwd 138and fills in 139.Fa pw 140with corresponding values; string fields in 141.Fa pw 142will be pointers into 143.Fa bp . 144Some characters in 145.Fa bp 146will be overwritten with 0s in order to terminate the strings pointed 147to by 148.Fa pw . 149If 150.Fa flags 151is non-null, it is filled in with the following flags: 152.Bl -tag -width _PASSWORD_NOGIDxxx 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 _PASSWD_NOCHG 162The change field of 163.Fa bp 164is empty. 165.It Dv _PASSWD_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