1.\" $OpenBSD: pw_init.3,v 1.4 1999/09/23 04:12:01 alex 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_setdir , 44.Nm pw_file , 45.Nm pw_edit , 46.Nm pw_prompt , 47.Nm pw_copy , 48.Nm pw_scan , 49.Nm pw_error 50.Nd utility functions for interactive passwd file updates 51.Sh SYNOPSIS 52.Fd #include <pwd.h> 53.Fd #include <util.h> 54.Ft void 55.Fn pw_init 56.Ft void 57.Fn pw_setdir "const char *directory" 58.Ft char * 59.Fn pw_file "const char *filename" 60.Ft void 61.Fn pw_edit "int notsetuid" "const char *filename" 62.Ft void 63.Fn pw_prompt 64.Ft void 65.Fn pw_copy "int ffd" "int tfd" "struct passwd *pw" 66.Ft int 67.Fn pw_scan "char *bp" "struct passwd *pw" "int *flags" 68.Ft void 69.Fn pw_error "const char *name" "int err" "int eval" 70.Sh DESCRIPTION 71These functions are designed as conveniences for interactive programs 72which update the passwd file and do nothing else. They generally 73handle errors by printing out a message to the standard error stream 74and possibly aborting the process. 75.Pp 76The 77.Fn pw_init 78function prepares for a passwd update by unlimiting all resource 79constraints, disabling core dumps (thus preventing dumping the 80contents of the passwd database into a world-readable file), and 81disabling most signals. 82.Pp 83The 84.Fn pw_setdir 85function sets an alternative directory where the rest of the functions looks 86for password-related files. Use this if you are writing utilities that should 87be able to handle password files outside of /etc. 88.Pp 89The 90.Fn pw_file 91function transforms filenames so that they end up in the directory specified 92to the latest 93.Fn pw_setdir 94call. The rule is that all directories are stripped off 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). If 108.Fa notsetuid 109is nonzero, 110.Fn pw_edit 111will set the effective user and group ID to the real user and group ID 112before running the editor. 113.Pp 114The 115.Fn pw_prompt 116function asks the user whether he or she wants to re-edit the password 117file; if the answer is no, 118.Fn pw_prompt 119deletes the lock file and exits the process. 120.Pp 121The 122.Fn pw_copy 123function reads a passwd file from 124.Fa ffd 125and writes it to 126.Fa tfd , 127updating the entry corresponding to pw->pw_name with the information 128in 129.Fa pw . 130.Pp 131The 132.Fn pw_scan 133function accepts in 134.Fa bp 135a passwd entry as it would be represented in 136.Pa /etc/master.passwd 137and fills in 138.Fa pw 139with corresponding values; string fields in 140.Fa pw 141will be pointers into 142.Fa bp . 143Some characters in 144.Fa bp 145will be overwritten with 0s in order to terminate the strings pointed 146to by 147.Fa pw . 148If 149.Fa flags 150is non-null, it is filled in with the following flags: 151.Bl -tag -width _PASSWORD_NOGIDxxx 152.It Dv _PASSWORD_NOUID 153The uid field of 154.Fa bp 155is empty. 156.It Dv _PASSWORD_NOGID 157The gid field of 158.Fa bp 159is empty. 160.It Dv _PASSWD_NOCHG 161The change field of 162.Fa bp 163is empty. 164.It Dv _PASSWD_NOEXP 165The expire field of 166.Fa bp 167is empty. 168.El 169.Pp 170The 171.Fn pw_error 172function displays an error message, aborts the current passwd update, 173and exits the current process. If 174.Fa err 175is non-zero, a warning message beginning with 176.Fa name 177is printed for the current value of 178.Va errno . 179The process exits with status 180.Fa eval . 181.Sh RETURN VALUES 182The 183.Fn pw_scan 184function prints a warning message and returns 0 if the string in the 185.Fa bp 186argument is not a valid passwd string. Otherwise, 187.Fn pw_scan 188returns 1. 189.Sh FILES 190.Bl -tag -width /etc/master.passwd -compact 191.It Pa /etc/master.passwd 192.It Pa /etc/ptmp 193.El 194.Sh SEE ALSO 195.Xr pw_lock 3 , 196.Xr passwd 5 197