Document the pw_util(3) functions
Reviewed by: des, gjb
This commit is contained in:
bapt
parent
20b6928158
commit
4bbfc76333
@ -30,7 +30,7 @@ MAN+= expand_number.3 flopen.3 fparseln.3 hexdump.3 \
|
||||
kinfo_getproc.3 kinfo_getvmmap.3 kld.3 login_auth.3 login_cap.3 \
|
||||
login_class.3 login_ok.3 login_times.3 login_tty.3 pidfile.3 \
|
||||
property.3 pty.3 quotafile.3 realhostname.3 realhostname_sa.3 \
|
||||
_secure_path.3 trimdomain.3 uucplock.3
|
||||
_secure_path.3 trimdomain.3 uucplock.3 pw_util.3
|
||||
MAN+= login.conf.5
|
||||
MLINKS+= kld.3 kld_isloaded.3 kld.3 kld_load.3
|
||||
MLINKS+=login_auth.3 auth_cat.3 login_auth.3 auth_checknologin.3
|
||||
@ -67,5 +67,18 @@ MLINKS+=quotafile.3 quota_close.3 \
|
||||
quotafile.3 quota_write_usage.3
|
||||
MLINKS+=uucplock.3 uu_lock.3 uucplock.3 uu_lock_txfr.3 \
|
||||
uucplock.3 uu_lockerr.3 uucplock.3 uu_unlock.3
|
||||
MLINKS+=pw_util.3 pw_copy.3 \
|
||||
pw_util.3 pw_dup.3 \
|
||||
pw_util.3 pw_edit.3 \
|
||||
pw_util.3 pw_equal.3 \
|
||||
pw_util.3 pw_fini.3 \
|
||||
pw_util.3 pw_init.3 \
|
||||
pw_util.3 pw_make.3 \
|
||||
pw_util.3 pw_make_v7.3 \
|
||||
pw_util.3 pw_mkdb.3 \
|
||||
pw_util.3 pw_lock.3 \
|
||||
pw_util.3 pw_scan.3 \
|
||||
pw_util.3 pw_tempname.3 \
|
||||
pw_util.3 pw_tmp.3
|
||||
|
||||
.include <bsd.lib.mk>
|
||||
|
||||
285
lib/libutil/pw_util.3
Normal file
285
lib/libutil/pw_util.3
Normal file
@ -0,0 +1,285 @@
|
||||
.\" Copyright (c) 2012 Baptiste Daroussin <bapt@FreeBSD.org>
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" This software was developed by Pawel Jakub Dawidek under sponsorship from
|
||||
.\" the FreeBSD Foundation.
|
||||
.\"
|
||||
.\" 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 .
|
||||
Loading…
Reference in New Issue
Block a user