|Return to pw_init.3 CVS log||Up to [cvs.NetBSD.org] / src / lib / libutil|
|File: [cvs.NetBSD.org] / src / lib / libutil / pw_init.3 (download)
Revision 1.15, Wed May 5 22:05:31 2010 UTC (9 years, 10 months ago) by wiz
Mark up NULL with Dv.
.\" $NetBSD: pw_init.3,v 1.15 2010/05/05 22:05:31 wiz Exp $ .\" .\" Copyright (c) 1995 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software developed by the Computer Systems .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract .\" BG 91-66 and contributed to Berkeley. .\" .\" 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. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. .\" .Dd August 1, 2004 .Dt PW_INIT 3 .Os .Sh NAME .Nm pw_init , .Nm pw_edit , .Nm pw_prompt , .Nm pw_copy , .Nm pw_copyx , .Nm pw_scan , .Nm pw_error .Nd utility functions for interactive passwd file updates .Sh LIBRARY .Lb libutil .Sh SYNOPSIS .In pwd.h .In util.h .Ft void .Fn pw_init "void" .Ft void .Fn pw_edit "int notsetuid" "const char *filename" .Ft void .Fn pw_prompt "void" .Ft void .Fn pw_copy "int ffd" "int tfd" "struct passwd *pw" "struct passwd *old_pw" .Ft int .Fn pw_copyx "int ffd" "int tfd" "struct passwd *pw" "struct passwd *old_pw" \ "char *errbuf" "size_t errbufsz" .Ft int .Fn pw_scan "char *bp" "struct passwd *pw" "int *flags" .Ft void .Fn pw_error "const char *name" "int err" "int eval" .Sh DESCRIPTION These functions are designed as conveniences for interactive programs which update the passwd file and do nothing else. They generally handle errors by printing out a message to the standard error stream and possibly aborting the process. .Pp The .Fn pw_init function prepares for a passwd update by unlimiting all resource constraints, disabling core dumps (thus preventing dumping the contents of the passwd database into a world-readable file), and disabling most signals. .Pp The .Fn pw_edit function runs an editor (named by the environment variable EDITOR, or .Pa /usr/bin/vi if EDITOR is not set) on the file .Fa filename (or .Pa /etc/ptmp if .Fa filename is .Dv NULL ) . If .Fa notsetuid is nonzero, .Fn pw_edit will set the effective user and group ID to the real user and group ID before running the editor. .Pp The .Fn pw_prompt function asks the user whether he or she wants to re-edit the password file; if the answer is no, .Fn pw_prompt deletes the lock file and exits the process. .Pp The .Fn pw_copy function reads a passwd file from .Fa ffd and writes it to .Fa tfd , updating the entry corresponding to pw-\*[Gt]pw_name with the information in .Fa pw . If .Fa old_pw is not .Dv NULL , it checks to make sure the old entry is the same as the one described in .Fa old_pw or the process is aborted. If an entry is not found to match .Fa pw , a new entry is appended to the passwd file only if the real user ID is 0. If an error occurs, .Fn pw_copy will display a message on .Dv stderr and call .Fn pw_error . .Pp The .Fn pw_copyx function performs the same operation as .Fn pw_copy with the exception of error handling. Upon an error, .Fn pw_copyx will write an error message into the buffer pointed to by .Fa errbuf which has the size .Fa errbufsz . .Pp The .Fn pw_scan function accepts in .Fa bp a passwd entry as it would be represented in .Pa /etc/master.passwd and fills in .Fa pw with corresponding values; string fields in .Fa pw will be pointers into .Fa bp . Some characters in .Fa bp will be overwritten with 0s in order to terminate the strings pointed to by .Fa pw . If .Fa flags is non-null, it should be cleared and the following options enabled if required: .Bl -tag -offset indent -width _PASSWORD_OLDFMT .It Dv _PASSWORD_NOWARN Don't print warnings. .It Dv _PASSWORD_OLDFMT Parse .Fa bp as an old format entry as found in .Pa /etc/passwd . .El .Pp Upon return it is cleared, and filled in with the following flags: .Bl -tag -offset indent -width _PASSWORD_NOGID .It Dv _PASSWORD_NOUID The uid field of .Fa bp is empty. .It Dv _PASSWORD_NOGID The gid field of .Fa bp is empty. .It Dv _PASSWORD_NOCHG The change field of .Fa bp is empty. .It Dv _PASSWORD_NOEXP The expire field of .Fa bp is empty. .El .Pp The .Fn pw_error function displays an error message, aborts the current passwd update, and exits the current process. If .Fa err is non-zero, a warning message beginning with .Fa name is printed for the current value of .Va errno . The process exits with status .Fa eval . .Sh RETURN VALUES The .Fn pw_copyx function returns 1 if the new password entry was successfully written to the destination file, and 0 otherwise. .Pp The .Fn pw_scan function prints a warning message and returns 0 if the string in the .Fa bp argument is not a valid passwd string. Otherwise, .Fn pw_scan returns 1. .Sh FILES .Bl -tag -width /etc/master.passwd -compact .It Pa /etc/master.passwd .It Pa /etc/ptmp .El .Sh SEE ALSO .Xr pw_lock 3 , .Xr passwd 5