1.\" $OpenBSD: pw_lock.3,v 1.11 2005/03/07 23:01:40 jmc 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 20, 2001 35.Dt PW_LOCK 3 36.Os 37.Sh NAME 38.Nm pw_lock , 39.Nm pw_mkdb , 40.Nm pw_abort 41.Nd passwd file update functions 42.Sh SYNOPSIS 43.Fd #include <util.h> 44.Ft int 45.Fn pw_lock "int retries" 46.Ft int 47.Fn pw_mkdb "char *username" "int pwflags" 48.Ft void 49.Fn pw_abort 50.Sh DESCRIPTION 51The 52.Fn pw_lock , 53.Fn pw_mkdb , 54and 55.Fn pw_abort 56functions allow a program to update the system passwd database. 57.Pp 58The 59.Fn pw_lock 60function attempts to lock the passwd database by creating the file 61.Pa /etc/ptmp 62with an exclusive lock (using 63.Xr flock 2 64semantics) and returns the file descriptor of that file. 65If 66.Fa retries 67is greater than zero, 68.Fn pw_lock 69will try multiple times to open 70.Pa /etc/ptmp , 71waiting one second between tries. 72In addition to being a lock file, 73.Pa /etc/ptmp 74will also hold the contents of the new passwd file. 75.Pp 76The 77.Fn pw_mkdb 78function updates the passwd file from the contents of 79.Pa /etc/ptmp 80via 81.Xr pwd_mkdb 8 . 82If a 83.Fa username 84is specified, only the record for the specified user will be updated. 85The 86.Fa pwflags 87are specified by 88.Tn OR Ns 'ing 89the following values: 90.Pp 91.Bl -tag -width _PASSWORD_SECUREONLY -offset "xxxx" -compact 92.It Dv _PASSWORD_SECUREONLY 93only update the secure database file 94.Pq Pa /etc/spwd.db . 95.It Dv _PASSWORD_OMITV7 96do not update the Version 7 format password file 97.Pq Pa /etc/passwd . 98.El 99.Pp 100By default the secure, insecure and Version 7 format password databases 101are updated. 102You should finish writing to and close the file descriptor returned by 103.Fn pw_lock 104before calling 105.Fn pw_mkdb . 106If 107.Fn pw_mkdb 108fails and you do not wish to retry, you should make sure to call 109.Fn pw_abort 110to clean up the lock file. 111.Pp 112The 113.Fn pw_abort 114function aborts a passwd file update by deleting 115.Pa /etc/ptmp . 116The passwd database remains unchanged. 117.Sh RETURN VALUES 118The 119.Fn pw_lock 120and 121.Fn pw_mkdb 122functions return \-1 if they are unable to complete properly. 123.Sh FILES 124.Bl -tag -width /etc/master.passwd -compact 125.It Pa /etc/master.passwd 126current password file 127.It Pa /etc/ptmp 128password lock file 129.It Pa /etc/passwd 130a Version 7 format password file 131.It Pa /etc/pwd.db 132insecure password database file 133.It Pa /etc/spwd.db 134secure password database file 135.El 136.Sh SEE ALSO 137.Xr flock 2 , 138.Xr pw_init 3 , 139.Xr pwd_mkdb 8 140