1.\" Copyright (c) 2012 Baptiste Daroussin <bapt@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd October 30, 2012 28.Dt PW_UTIL 3 29.Os 30.Sh NAME 31.Nm pw_copy , 32.Nm pw_dup , 33.Nm pw_edit , 34.Nm pw_equal , 35.Nm pw_fini , 36.Nm pw_init , 37.Nm pw_make , 38.Nm pw_make_v7 , 39.Nm pw_mkdb , 40.Nm pw_lock , 41.Nm pw_scan , 42.Nm pw_tempname , 43.Nm pw_tmp 44.Nd "functions for passwd file handling" 45.Sh LIBRARY 46.Lb libutil 47.Sh SYNOPSIS 48.In pwd.h 49.In libutil.h 50.Ft int 51.Fn pw_copy "int ffd" "int tfd" "const struct passwd *pw" "struct passwd *oldpw" 52.Ft "struct passwd *" 53.Fn pw_dup "const struct passwd *pw" 54.Ft int 55.Fn pw_edit "int nosetuid" 56.Ft int 57.Fn pw_equal "const struct passwd *pw1" "const struct passwd *pw2" 58.Ft void 59.Fn pw_fini "void" 60.Ft int 61.Fn pw_init "const char *dir" const char *master" 62.Ft "char *" 63.Fn pw_make "const struct passwd *pw" 64.Ft "char *" 65.Fn pw_make_v7 "const struct passwd *pw" 66.Ft int 67.Fn pw_mkdb "const char *user" 68.Ft int 69.Fn pw_lock "void" 70.Ft "struct passwd *" 71.Fn pw_scan "const char *line" "int flags" 72.Ft "const char *" 73.Fn pw_tempname "void" 74.Ft int 75.Fn pw_tmp "int mfd" 76.Sh DESCRIPTION 77The 78.Fn pw_copy 79function reads a password file from 80.Vt ffd 81and writes it back out to 82.Vt tfd 83possibly with modifications: 84.Bl -dash 85.It 86If 87.Fa pw 88is 89.Dv NULL 90and 91.Fa oldpw 92is not 93.Dv NULL , 94then the record represented by 95.Fa oldpw 96will not be copied (corresponding to user deletion). 97.It 98If 99.Fa pw 100and 101.Fa oldpw 102are not 103.Dv NULL 104then the record corresponding to 105.Fa pw 106will be replaced by the record corresponding to 107.Fa oldpw . 108.It 109If 110.Vt pw 111is set and 112.Vt oldpw 113is 114.Dv NULL 115then the record corresponding to 116.Vt pw 117will be appended (corresponding to user addition). 118.El 119.Pp 120The 121.Fn pw_copy 122function returns -1 in case of failure otherwise 0. 123.Pp 124The 125.Fn pw_dup 126function duplicates the 127.Vt struct passwd 128pointed to by 129.Fa pw 130and returns a pointer to the copy, or 131.Dv NULL 132in case of failure. 133The new 134.Vt struct passwd 135is allocated with 136.Xr malloc 3 , 137and it is the caller's responsibility to free it with 138.Xr free 3 . 139.Pp 140The 141.Fn pw_edit 142function invokes the command specified by the 143.Ev EDITOR 144environment variable (or 145.Pa /usr/bin/vi 146if 147.Ev EDITOR 148is not defined) 149on a temporary copy of the master password file created by 150.Fn pw_tmp . 151If the file was modified, 152.Fn pw_edit 153installs it and regenerates the password database. 154The 155.Fn pw_edit 156function returns -1 in case of failure, 0 if the file was not modified, 157and a non-zero positive number if the file was modified and successfully 158installed. 159.Pp 160The 161.Fn pw_equal 162function compares two 163.Vt struct passwd 164and returns 0 if they are equal. 165.Pp 166The 167.Fn pw_fini 168function destroy the temporary file created by 169.Fn pw_tmp 170if any, 171kills any running instance of 172.Ev EDITOR 173executed by 174.Fn pw_edit 175if any, 176and closes the lock created by 177.Fn pw_lock 178if any. 179.Pp 180The 181.Fn pw_init 182initialize the static variable representing the path a password file. 183.Fa dir 184is the directory where the password file is located. 185If set to 186.Dv NULL , 187it will default to 188.Pa /etc . 189.Fa master 190is the name of the password file. 191If set to 192.Dv NULL? 193it will default to 194.Pa master.passwd 195.Pp 196The 197.Fn pw_make 198function creates a properly formatted 199.Bx 200.Xr passwd 5 201line from a 202.Vt struct passwd , 203and returns a pointer to the resulting string. 204The string is allocated with 205.Xr malloc 3 , 206and it is the caller's responsibility to free it with 207.Xr free 3 . 208.Pp 209The 210.Fn pw_make_v7 211function creates a properly formatted 212.Ux V7 213.Xr passwd 5 214line from a 215.Vt struct passwd , 216and returns a pointer to the resulting string. 217The string is allocated with 218.Xr malloc 3 , 219and it is the caller's responsibility to free it with 220.Xr free 3 . 221.Pp 222The 223.Fn pw_mkdb 224function regenerates the password database by running 225.Xr pw_mkdb 8 . 226If 227.Fa user 228only the record corresponding to that user will be updated. 229The 230.Fn pw_mkdb 231function returns 0 in case of success and -1 in case of failure. 232.Pp 233The 234.Fn pw_lock 235function locks the master password file. 236It returns 0 in case of success and -1 in case of failure. 237.Pp 238The 239.Fn pw_scan 240function is a wrapper around the internal libc function 241.Fn __pw_scan . 242It scans the master password file for a line corresponding to the 243.Fa line 244provided and return a 245.Vt struct passwd 246if it matched an existing record. 247In case of failure, it returns 248.Dv NULL . 249Otherwise, it returns a pointer to a 250.Vt struct passwd 251containing the matching record. 252The 253.Vt struct passwd 254is allocated with 255.Xr malloc 3 , 256and it is the caller's responsibility to free it with 257.Xr free 3 . 258.Pp 259The 260.Fn pw_tempname 261function returns the temporary name of the masterfile created via 262.Fn pw_tmp . 263.Pp 264The 265.Fn pw_tmp 266creates and opens a presumably safe temporary password file. 267If 268.Fa mfd 269is a file descriptor to an open password file, it will be read and 270written back to the temporary password file. 271Otherwise if should be set -1. 272The 273.Fn pw_tmp 274returns an open file descriptor to the temporary password file or -1 in case of 275failure. 276.Sh AUTHORS 277Portions of this software were developed for the 278.Fx 279Project by ThinkSec AS and Network Associates Laboratories, the 280Security Research Division of Network Associates, Inc.\& under 281DARPA/SPAWAR contract N66001-01-C-8035 282.Pq Dq CBOSS , 283as part of the DARPA CHATS research program. 284.Pp 285This manual page was written by 286.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org . 287