Return to pw_lock.3 CVS log

Up to [cvs.NetBSD.org] / src / lib / libutil

Annotation of src/lib/libutil/pw_lock.3, Revision 1.14

1.14    ! wiz         1: .\"    $NetBSD: pw_lock.3,v 1.13 2007/02/17 09:37:55 wiz Exp $
1.3       perry       2: .\"
1.1       jtc         3: .\" Copyright (c) 1995
                      4: .\"    The Regents of the University of California.  All rights reserved.
                      5: .\"
                      6: .\" This code is derived from software developed by the Computer Systems
                      7: .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
                      8: .\" BG 91-66 and contributed to Berkeley.
                      9: .\"
                     10: .\" Redistribution and use in source and binary forms, with or without
                     11: .\" modification, are permitted provided that the following conditions
                     12: .\" are met:
                     13: .\" 1. Redistributions of source code must retain the above copyright
                     14: .\"    notice, this list of conditions and the following disclaimer.
                     15: .\" 2. Redistributions in binary form must reproduce the above copyright
                     16: .\"    notice, this list of conditions and the following disclaimer in the
                     17: .\"    documentation and/or other materials provided with the distribution.
1.12      agc        18: .\" 3. Neither the name of the University nor the names of its contributors
1.1       jtc        19: .\"    may be used to endorse or promote products derived from this software
                     20: .\"    without specific prior written permission.
                     21: .\"
                     22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     25: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     32: .\" SUCH DAMAGE.
                     33: .\"
1.13      wiz        34: .Dd February 17, 2007
1.1       jtc        35: .Dt PW_LOCK 3
                     36: .Os
                     37: .Sh NAME
                     38: .Nm pw_lock ,
                     39: .Nm pw_mkdb ,
1.6       tron       40: .Nm pw_abort ,
                     41: .Nm pw_setprefix ,
                     42: .Nm pw_getprefix
1.1       jtc        43: .Nd passwd file update functions
1.4       perry      44: .Sh LIBRARY
                     45: .Lb libutil
1.1       jtc        46: .Sh SYNOPSIS
1.11      wiz        47: .In util.h
1.1       jtc        48: .Ft int
                     49: .Fn pw_lock "int retries"
                     50: .Ft int
1.9       wiz        51: .Fn pw_mkdb "const char *username" "int secureonly"
1.1       jtc        52: .Ft void
1.5       ad         53: .Fn pw_abort "void"
1.6       tron       54: .Ft int
                     55: .Fn pw_setprefix "const char *new_prefix"
                     56: .Ft "const char *"
                     57: .Fn pw_getprefix "void"
1.1       jtc        58: .Sh DESCRIPTION
                     59: The
                     60: .Fn pw_lock ,
                     61: .Fn pw_mkdb ,
                     62: and
                     63: .Fn pw_abort
                     64: functions allow a program to update the system passwd database.
                     65: .Pp
                     66: The
                     67: .Fn pw_lock
                     68: function attempts to lock the passwd database by creating the file
                     69: .Pa /etc/ptmp ,
1.10      wiz        70: and returns the file descriptor of that file.
                     71: If
1.1       jtc        72: .Fa retries
                     73: is greater than zero,
                     74: .Fn pw_lock
                     75: will try multiple times to open
                     76: .Pa /etc/ptmp ,
1.10      wiz        77: waiting one second between tries.
                     78: In addition to being a lock file,
1.1       jtc        79: .Pa /etc/ptmp
                     80: will also hold the contents of the new passwd file.
                     81: .Pp
                     82: The
                     83: .Fn pw_mkdb
                     84: function updates the passwd file from the contents of
                     85: .Pa /etc/ptmp .
                     86: You should finish writing to and close the file descriptor returned by
                     87: .Fn pw_lock
                     88: before calling
                     89: .Fn pw_mkdb .
1.2       ghudson    90: If
                     91: .Fn pw_mkdb
                     92: fails and you do not wish to retry, you should make sure to call
                     93: .Fn pw_abort
1.10      wiz        94: to clean up the lock file.
                     95: If the
1.7       ad         96: .Ar username
1.14    ! wiz        97: argument is not
        !            98: .Dv NULL ,
        !            99: only database entries pertaining to the specified user
1.10      wiz       100: will be modified.
                    101: If the
1.7       ad        102: .Ar secureonly
                    103: argument is non-zero, only the secure database will be updated.
1.1       jtc       104: .Pp
                    105: The
                    106: .Fn pw_abort
                    107: function aborts a passwd file update by deleting
                    108: .Pa /etc/ptmp .
                    109: The passwd database remains unchanged.
1.6       tron      110: .Pp
                    111: The
                    112: .Fn pw_setprefix
1.10      wiz       113: function defines the root directory used for passwd file updates.
                    114: If the prefix is set to
1.6       tron      115: .Pa /newroot
                    116: .Fn pw_lock
                    117: will operate on
                    118: .Pa /newroot/etc/ptmp
1.10      wiz       119: afterwards.
                    120: The default prefix is an empty string.
1.6       tron      121: .Pp
                    122: The
                    123: .Fn pw_getprefix
                    124: function returns the root directory which is currently used for passwd file
                    125: updates.
1.1       jtc       126: .Sh RETURN VALUES
                    127: The
                    128: .Fn pw_lock
                    129: and
                    130: .Fn pw_mkdb
                    131: functions return -1 if they are unable to complete properly.
                    132: .Sh FILES
                    133: .Bl -tag -width /etc/master.passwd -compact
                    134: .It Pa /etc/master.passwd
                    135: .It Pa /etc/ptmp
                    136: .El
                    137: .Sh SEE ALSO
1.7       ad        138: .Xr pw_init 3 ,
1.9       wiz       139: .Xr pwd_mkdb 8