283 lines
6.3 KiB
Groff
283 lines
6.3 KiB
Groff
|
.\" Copyright (c) 2012 Baptiste Daroussin <bapt@FreeBSD.org>
|
||
|
|
.\" All rights reserved.
|
||
|
|
.\"
|
||
|
|
.\" Redistribution and use in source and binary forms, with or without
|
||
|
|
.\" modification, are permitted provided that the following conditions
|
||
|
|
.\" are met:
|
||
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer.
|
||
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
||
|
|
.\" documentation and/or other materials provided with the distribution.
|
||
|
|
.\"
|
||
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
|
||
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
|
||
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||
|
|
.\" SUCH DAMAGE.
|
||
|
|
.\"
|
||
|
|
.\" $FreeBSD$
|
||
|
|
.\"
|
||
|
|
.Dd October 30, 2012
|
||
|
|
.Dt PW_UTIL 3
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm pw_copy ,
|
||
|
|
.Nm pw_dup ,
|
||
|
|
.Nm pw_edit ,
|
||
|
|
.Nm pw_equal ,
|
||
|
|
.Nm pw_fini ,
|
||
|
|
.Nm pw_init ,
|
||
|
|
.Nm pw_make ,
|
||
|
|
.Nm pw_make_v7 ,
|
||
|
|
.Nm pw_mkdb ,
|
||
|
|
.Nm pw_lock ,
|
||
|
|
.Nm pw_scan ,
|
||
|
|
.Nm pw_tempname ,
|
||
|
|
.Nm pw_tmp
|
||
|
|
.Nd "functions for passwd file handling"
|
||
|
|
.Sh LIBRARY
|
||
|
|
.Lb libutil
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.In pwd.h
|
||
|
|
.In libutil.h
|
||
|
|
.Ft int
|
||
|
|
.Fn pw_copy "int ffd" "int tfd" "const struct passwd *pw" "const struct paddwd *oldpw"
|
||
|
|
.Ft "struct passwd *"
|
||
|
|
.Fn pw_dup "const struct passwd *pw"
|
||
|
|
.Ft int
|
||
|
|
.Fn pw_edit "int nosetuid"
|
||
|
|
.Ft int
|
||
|
|
.Fn pw_equal "const struct passwd *pw1" "const struct passwd pw2"
|
||
|
|
.Ft void
|
||
|
|
.Fn pw_fini "void"
|
||
|
|
.Ft int
|
||
|
|
.Fn pw_init "const char *dir" const char *master"
|
||
|
|
.Ft "char *"
|
||
|
|
.Fn pw_make "const struct passwd *pw"
|
||
|
|
.Ft "char *"
|
||
|
|
.Fn pw_make_v7 "const struct passwd *pw"
|
||
|
|
.Ft int
|
||
|
|
.Fn pw_mkdb "const char *user"
|
||
|
|
.Ft int
|
||
|
|
.Fn pw_lock "void"
|
||
|
|
.Ft "struct passwd *"
|
||
|
|
.Fn pw_scan "const char *line" "int flags"
|
||
|
|
.Ft "const char *"
|
||
|
|
.Fn pw_tempname "void"
|
||
|
|
.Ft int
|
||
|
|
.Fn pw_tmp "int mfd"
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_copy
|
||
|
|
function reads a password file from
|
||
|
|
.Vt ffd
|
||
|
|
and writes it back out to
|
||
|
|
.Vt tfd
|
||
|
|
possibly with modifications:
|
||
|
|
.Bl -dash
|
||
|
|
.It
|
||
|
|
If
|
||
|
|
.Fa pw
|
||
|
|
is
|
||
|
|
.Dv NULL
|
||
|
|
and
|
||
|
|
.Fa oldpw
|
||
|
|
is not
|
||
|
|
.Dv NULL ,
|
||
|
|
then the record represented by
|
||
|
|
.Fa oldpw
|
||
|
|
will not be copied (corresponding to user deletion).
|
||
|
|
.It
|
||
|
|
If
|
||
|
|
.Fa pw
|
||
|
|
and
|
||
|
|
.Fa oldpw
|
||
|
|
are not
|
||
|
|
.Dv NULL
|
||
|
|
then the record corresponding to
|
||
|
|
.Fa pw
|
||
|
|
will be replace by the record corresponding to
|
||
|
|
.Fa oldpw .
|
||
|
|
.It
|
||
|
|
If
|
||
|
|
.Vt pw
|
||
|
|
is set and
|
||
|
|
.Vt oldpw
|
||
|
|
is
|
||
|
|
.Dv NULL
|
||
|
|
then the record corresponding to
|
||
|
|
.Vt pw
|
||
|
|
will be appended (corresponding to user addition).
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_copy
|
||
|
|
function returns -1 in case of failure otherwise 0.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_dup
|
||
|
|
function duplicates the
|
||
|
|
.Vt struct passwd
|
||
|
|
pointed to by
|
||
|
|
.Fa pw
|
||
|
|
and returns a pointer to the copy, or
|
||
|
|
.Dv NULL
|
||
|
|
in case of failure.
|
||
|
|
The new
|
||
|
|
.Vt struct passwd
|
||
|
|
is allocated with
|
||
|
|
.Xr malloc 3 ,
|
||
|
|
and it is the caller's responsibility to free it with
|
||
|
|
.Xr free 3 .
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_edit
|
||
|
|
function invokes the command specified by the
|
||
|
|
.Ev EDITOR
|
||
|
|
environment variable (or
|
||
|
|
.Pa /usr/bin/vi
|
||
|
|
if
|
||
|
|
.Ev EDITOR
|
||
|
|
is not defined)
|
||
|
|
on a temporary copy of the master password file created by
|
||
|
|
.Fn pw_tmp .
|
||
|
|
If the file was modified,
|
||
|
|
.Fn pw_edit
|
||
|
|
installs it and regenerates the password database.
|
||
|
|
The
|
||
|
|
.Fn pw_edit
|
||
|
|
function returns -1 in case of failure, 0 if the file was not modified,
|
||
|
|
and a non-zero positive number if the file was modified and successfully
|
||
|
|
installed.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_equal
|
||
|
|
function compares two
|
||
|
|
.Vt struct passwd
|
||
|
|
and returns 0 if they are equal.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_fini
|
||
|
|
function destroy the temporary file created by
|
||
|
|
.Fn pw_tmp
|
||
|
|
if any,
|
||
|
|
kills any running instance of
|
||
|
|
.Ev EDITOR
|
||
|
|
excuted by
|
||
|
|
.Fn pw_edit
|
||
|
|
if any,
|
||
|
|
and closes the lock created by
|
||
|
|
.Fn pw_lock
|
||
|
|
if any.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_init
|
||
|
|
initialize the static variable representing the path a password file.
|
||
|
|
.Fa dir
|
||
|
|
is the directory where the password file is located.
|
||
|
|
If set to
|
||
|
|
.Dv NULL ,
|
||
|
|
it will default to
|
||
|
|
.Pa /etc .
|
||
|
|
.Fa master
|
||
|
|
is the name of the password file.
|
||
|
|
If set to
|
||
|
|
.Dv NULL?
|
||
|
|
it will default to
|
||
|
|
.Pa master.passwd
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_make
|
||
|
|
function creates a properly formatted
|
||
|
|
.Bx
|
||
|
|
.Xr passwd 5
|
||
|
|
line from a
|
||
|
|
.Vt struct passwd ,
|
||
|
|
and returns a pointer to the resulting string.
|
||
|
|
The string is allocated with
|
||
|
|
.Xr malloc 3 ,
|
||
|
|
and it is the caller's responsibility to free it with
|
||
|
|
.Xr free 3 .
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_make_v7
|
||
|
|
function creates a properly formatted
|
||
|
|
.Ux V7
|
||
|
|
.Xr passwd 5
|
||
|
|
line from a
|
||
|
|
.Vt struct passwd ,
|
||
|
|
and returns a pointer to the resulting string.
|
||
|
|
The string is allocated with
|
||
|
|
.Xr malloc 3 ,
|
||
|
|
and it is the caller's responsibility to free it with
|
||
|
|
.Xr free 3 .
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_mkdb
|
||
|
|
function regenerates the password database by running
|
||
|
|
.Xr pw_mkdb 8 .
|
||
|
|
If
|
||
|
|
.Fa user
|
||
|
|
only the record corresponding to that user will be updated.
|
||
|
|
The
|
||
|
|
.Fn pw_mkdb
|
||
|
|
function returns 0 in case of success and -1 in case of failure.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_lock
|
||
|
|
function locks the master password file.
|
||
|
|
It returns 0 in case of success and -1 in case of failure.
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_scan
|
||
|
|
function is a wrapper around the internal libc function
|
||
|
|
.Fn __pw_scan .
|
||
|
|
It scans the master password file for a line corresponding to the
|
||
|
|
.Fa line
|
||
|
|
provided and return a
|
||
|
|
.Vt struct passwd
|
||
|
|
if it matched an existing record.
|
||
|
|
In case of failure, it returns
|
||
|
|
.Dv NULL .
|
||
|
|
Otherwise, it returns a pointer to a
|
||
|
|
.Vt struct passwd
|
||
|
|
containing the matching record.
|
||
|
|
The
|
||
|
|
.Vt struct passwd
|
||
|
|
is allocated with
|
||
|
|
.Xr malloc 3 ,
|
||
|
|
and it is the caller's responsibility to free it with
|
||
|
|
.Xr free 3 .
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_tempname
|
||
|
|
function returns the temporary name of the masterfile created via
|
||
|
|
.Fn pw_tmp .
|
||
|
|
.Pp
|
||
|
|
The
|
||
|
|
.Fn pw_tmp
|
||
|
|
creates and opens a presumably safe temporary password file.
|
||
|
|
If
|
||
|
|
.Fa mfd
|
||
|
|
is a file descriptor to an open password file, it will be read and
|
||
|
|
written back to the temporary password file.
|
||
|
|
Otherwise if should be set -1.
|
||
|
|
The
|
||
|
|
.Fn pw_tmp
|
||
|
|
returns an open file descriptor to the temporary password file or -1 in case of
|
||
|
|
failure.
|
||
|
|
.Sh AUTHORS
|
||
|
|
.Nm pw_util
|
||
|
|
was written by
|
||
|
|
.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
|
||
|
|
This manual page was written by
|
||
|
|
.An Baptiste Daroussin Aq bapt@FreeBSD.org .
|