.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "LckPwdF 3"
.TH LckPwdF 3 "1999-10-13" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::LckPwdF \- Lock and unlock the passwd and shadow files with lckpwdf and ulckpwdf
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use File::LckPwdF;
\&
\& (lock_passwd(15)) || (die "Can\*(Aqt lock password file:\en$! stopped");
\&
\& # ... do stuff with the passwd file ...
\&
\& (unlock_passwd()) || (die "Can\*(Aqt unlock password file:\en$! stopped");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a perl module to use \fB\f(BIlckpwdf\fB\|(3)\fR and \fB\f(BIulckpwdf\fB\|(3)\fR to lock
the \fI/etc/passwd\fR and (if present) \fI/etc/shadow\fR files.
.SS "Functions exported automatically"
.IX Subsection "Functions exported automatically"
\&\fBlock_passwd($timeout)\fR
.PP
\&\fB\f(CB$timeout\fB\fR works as follows:
.IP "1. The initial time is checked." 4
.IX Item "1. The initial time is checked."
.PD 0
.ie n .IP "2. If \fB\fB$timeout\fB\fR is 0, it tries \fB\f(BIlckpwdf()\fB\fR until it succeeds, waiting a random time in between." 4
.el .IP "2. If \fB\f(CB$timeout\fB\fR is 0, it tries \fB\f(BIlckpwdf()\fB\fR until it succeeds, waiting a random time in between." 4
.IX Item "2. If $timeout is 0, it tries lckpwdf() until it succeeds, waiting a random time in between."
.ie n .IP "3. If \fB\fB$timeout\fB\fR is above 0, it tries \fB\f(BIlckpwdf()\fB\fR once. If that (or any following \fB\f(BIlckpwdf()\fB\fR) succeeds, it returns 1. It will try \fB\f(BIlckpwdf()\fB\fR until either it succeeds or the time is greater than the initial time plus \fB\fB$timeout\fB\fR. In the latter case, it returns 0. It waits a random time in between tries of \fB\f(BIlckpwdf()\fB\fR." 4
.el .IP "3. If \fB\f(CB$timeout\fB\fR is above 0, it tries \fB\f(BIlckpwdf()\fB\fR once. If that (or any following \fB\f(BIlckpwdf()\fB\fR) succeeds, it returns 1. It will try \fB\f(BIlckpwdf()\fB\fR until either it succeeds or the time is greater than the initial time plus \fB\f(CB$timeout\fB\fR. In the latter case, it returns 0. It waits a random time in between tries of \fB\f(BIlckpwdf()\fB\fR." 4
.IX Item "3. If $timeout is above 0, it tries lckpwdf() once. If that (or any following lckpwdf()) succeeds, it returns 1. It will try lckpwdf() until either it succeeds or the time is greater than the initial time plus $timeout. In the latter case, it returns 0. It waits a random time in between tries of lckpwdf()."
.PD
.PP
The random timeout is controlled by \fB\f(CB$File::LckPwdF::Rand_Wait\fB\fR,
which is exported on request. It is used via
.PP
.Vb 1
\& sleep int(rand($Rand_Wait) + 1);
.Ve
.PP
inside an until loop. This sleep is only done if
\&\fB\f(CB$File::LckPwdF::Rand_Wait\fB\fR is above 0.
.PP
\&\fB\f(CB$timeout\fB\fR defaults to \fB\f(CB$File::LckPwdF::Default_Timeout\fB\fR, which is
also exported on request; the initial setting of
\&\fB\f(CB$File::LckPwdF::Default_Timeout\fB\fR (the default default) is 15
seconds. The default setting for \fB\f(CB$File::LckPwdF::Rand_Wait\fB\fR is 10
seconds.
.PP
\&\fB\f(BIunlock_passwd()\fB\fR
.PP
This function uses \fB\f(BIulckpwdf()\fB\fR. If \fB\f(BIlock_passwd()\fB\fR has previously
been used to lock the passwd file, and \fB\f(BIunlock_passwd()\fB\fR has not been
used to lock it, then it will be used to unlock the passwd file in an
\&\s-1END:\s0 statement. (Admittedly, with many implementations of
\&\fB\f(BIlckpwdf()\fB\fR this is not necessary, since when a process exits it
loses the passwd file lock; it is present as a safety measure for
those systems for which this is not true.)
.SS "Functions exported by request"
.IX Subsection "Functions exported by request"
\&\fB\f(BIlckpwdf()\fB\fR
\&\fB\f(BIulckpwdf()\fB\fR
.PP
These are the xs-loaded versions of \fB\f(BIlckpwdf\fB\|(3)\fR and \fB\f(BIulckpwdf\fB\|(3)\fR,
respectively.
.SH "RETURN VALUE"
.IX Header "RETURN VALUE"
The \fB\f(BIlock_passwd()\fB\fR and \fB\f(BIunlock_passwd()\fB\fR functions return 1 on
success and 0 on failure. The return values for \fB\f(BIlckpwdf()\fB\fR and
\&\fB\f(BIulckpwdf()\fB\fR are the same as for the system versions (\fB\f(BIlckpwdf\fB\|(3)\fR
and \fB\f(BIulckpwdf\fB\|(3)\fR).
.SH "ERRORS"
.IX Header "ERRORS"
If the effective \s-1UID\s0 is not 0, then \fB\f(BIlock_passwd()\fB\fR and
\&\fB\f(BIunlock_passwd()\fB\fR set \fB$!\fR to \fB\s-1EACCES\s0\fR if they fail (they do try
once, just in case you've got a \fIreally\fR weird setup).
.PP
If the effective \s-1UID\s0 is 0, in the event of failure, \fB\f(BIlock_passwd()\fB\fR
sets \fB$!\fR to:
.IP "1. if you've already locked the file through \fB\f(BIlock_passwd()\fB\fR, \fB\s-1EALREADY\s0\fR" 4
.IX Item "1. if you've already locked the file through lock_passwd(), EALREADY"
.PD 0
.ie n .IP "2. \fB\s-1EAGAIN\s0\fR (or \fB\s-1EWOULDBLOCK\s0\fR, if \fB\s-1EAGAIN\s0\fR isn't present on your system and \fB\s-1EWOULDBLOCK\s0\fR is; \fB\fB$File::LckPwdF::EAGAIN\fB\fR, which is exported on request, is equal to the value returned)." 4
.el .IP "2. \fB\s-1EAGAIN\s0\fR (or \fB\s-1EWOULDBLOCK\s0\fR, if \fB\s-1EAGAIN\s0\fR isn't present on your system and \fB\s-1EWOULDBLOCK\s0\fR is; \fB\f(CB$File::LckPwdF::EAGAIN\fB\fR, which is exported on request, is equal to the value returned)." 4
.IX Item "2. EAGAIN (or EWOULDBLOCK, if EAGAIN isn't present on your system and EWOULDBLOCK is; $File::LckPwdF::EAGAIN, which is exported on request, is equal to the value returned)."
.PD
.PP
\&\fB\f(BIunlock_passwd()\fB\fR, in the event of failure, sets \fB$!\fR to:
.IP "1. if you've already unlocked the file via \fB\f(BIunlock_passwd()\fB\fR or haven't locked it via \fB\f(BIlock_passwd()\fB\fR, \fB\s-1EALREADY\s0\fR." 4
.IX Item "1. if you've already unlocked the file via unlock_passwd() or haven't locked it via lock_passwd(), EALREADY."
.PD 0
.IP "2. \fB\s-1EINVAL\s0\fR." 4
.IX Item "2. EINVAL."
.PD
.PP
If you try to use a negative number for \fB\f(CB$timeout\fB\fR with
\&\fBlock_passwd($timeout)\fR, it carps, returns 0, and sets \fB$!\fR to
\&\fB\s-1EINVAL\s0\fR.
.SH "CAVEATS"
.IX Header "CAVEATS"
This program only works if your system has \fB\f(BIlckpwdf\fB\|(3)\fR and
\&\fB\f(BIulckpwdf\fB\|(3)\fR. This should be true of \s-1SVR4\s0 systems; others will
vary. If you use \fB\f(BIlock_passwd()\fB\fR and \fB\f(BIunlock_passwd()\fB\fR,
\&\fB\f(BIlckpwdf\fB\|(3)\fR and \fB\f(BIulckpwdf\fB\|(3)\fR need to have return values of 0+ for
success and below 0 (usually \-1) for failure.
.PP
The timeout period for \fB\f(BIlock_passwd()\fB\fR is approximate, since many
versions of \fB\f(BIlckpwdf()\fB\fR will keep trying for a total of 15 seconds to
lock the passwd (and possibly shadow) files before they return an
appropriate value.
.PP
This module only keeps track on its own of whether the passwd file is
locked if you always use \fB\f(BIlock_passwd()\fB\fR and \fB\f(BIunlock_passwd()\fB\fR. If
you use \fB\f(BIlckpwdf()\fB\fR or \fB\f(BIulckpwdf()\fB\fR by themselves for locking and
unlocking, you will need to set \fB\f(CB$File::LckPwdF::Passwd_Locked\fB\fR to 1
for locked and 0 for unlocked yourself.
.SH "BUGS"
.IX Header "BUGS"
I haven't written any good automated tests for this program yet. If
anyone's interested, be my guest (or for any other improvements, of
course).
.SH "AUTHOR"
.IX Header "AUTHOR"
E. Allen Smith, <easmith@beatrice.rutgers.edu>. Copyright 1998. This
software may be used, distributed, modified, etcetera under the same
conditions as \fBperl\fR.
.SH "FILES"
.IX Header "FILES"
\&\fI/etc/passwd\fR, \fI/etc/shadow\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \fIlckpwdf\fR\|(3), \fIulckpwdf\fR\|(3)