1.\" $OpenBSD: pw_lock.3,v 1.20 2016/08/14 14:57:16 tb 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 $Mdocdate: August 14 2016 $ 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.In 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 void 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 , 62and returns the file descriptor of that file. 63If 64.Fa retries 65is greater than zero, 66.Fn pw_lock 67will try multiple times to open 68.Pa /etc/ptmp , 69waiting one second between tries. 70In addition to being a lock file, 71.Pa /etc/ptmp 72will also hold the contents of the new passwd file. 73A different lock file can be specified with 74.Xr pw_file 3 . 75.Pp 76.Xr pw_init 3 77must be called before 78.Fn pw_lock . 79.Pp 80The 81.Fn pw_mkdb 82function updates the passwd file from the contents of 83.Pa /etc/ptmp 84via 85.Xr pwd_mkdb 8 . 86If a 87.Fa username 88is specified, only the record for the specified user will be updated. 89The 90.Fa pwflags 91are specified by OR'ing the following values: 92.Pp 93.Bl -tag -width _PASSWORD_SECUREONLY -offset "xxxx" -compact 94.It Dv _PASSWORD_SECUREONLY 95only update the secure database file 96.Pq Pa /etc/spwd.db . 97.It Dv _PASSWORD_OMITV7 98do not update the legacy password file 99.Pq Pa /etc/passwd . 100.El 101.Pp 102By default the secure and insecure password databases and 103the legacy password file 104.Pa /etc/passwd 105are updated. 106You should finish writing to and close the file descriptor returned by 107.Fn pw_lock 108before calling 109.Fn pw_mkdb . 110If 111.Fn pw_mkdb 112fails and you do not wish to retry, you should make sure to call 113.Fn pw_abort 114to clean up the lock file. 115.Pp 116The 117.Fn pw_abort 118function aborts a passwd file update by deleting 119.Pa /etc/ptmp . 120The passwd database remains unchanged. 121.Sh RETURN VALUES 122The 123.Fn pw_lock 124function returns \-1 on error and sets 125.Va errno . 126The 127.Fn pw_mkdb 128function returns \-1 if it is unable to complete properly. 129.Sh FILES 130.Bl -tag -width "/etc/master.passwdXXX" -compact 131.It Pa /etc/master.passwd 132Current password file. 133.It Pa /etc/passwd 134Legacy password file. 135.It Pa /etc/ptmp 136Password lock file. 137.It Pa /etc/pwd.db 138Insecure password database file. 139.It Pa /etc/spwd.db 140Secure password database file. 141.El 142.Sh ERRORS 143.Bl -tag -width Er 144.It Bq Er EINVAL 145.Fn pw_lock 146was called before 147.Xr pw_init 3 . 148.El 149.Pp 150.Fn pw_lock 151may also fail and set 152.Va errno 153for any of the errors specified for the routine 154.Xr open 2 . 155.Sh SEE ALSO 156.Xr pw_file 3 , 157.Xr pw_init 3 , 158.Xr pwd_mkdb 8 159