From 4bbfc763331d34fd432e7089f3859587ee7281cd Mon Sep 17 00:00:00 2001 From: bapt Date: Tue, 30 Oct 2012 22:18:08 +0000 Subject: [PATCH] Document the pw_util(3) functions Reviewed by: des, gjb --- lib/libutil/Makefile | 15 ++- lib/libutil/pw_util.3 | 285 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 299 insertions(+), 1 deletion(-) create mode 100644 lib/libutil/pw_util.3 diff --git a/lib/libutil/Makefile b/lib/libutil/Makefile index 413ba0bfd0c4..582cceffba4e 100644 --- a/lib/libutil/Makefile +++ b/lib/libutil/Makefile @@ -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 diff --git a/lib/libutil/pw_util.3 b/lib/libutil/pw_util.3 new file mode 100644 index 000000000000..bb84f943d796 --- /dev/null +++ b/lib/libutil/pw_util.3 @@ -0,0 +1,285 @@ +.\" Copyright (c) 2012 Baptiste Daroussin +.\" 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 .