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