.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "PW_AUTH" 3 "" "" ""
.SH NAME
pw_auth \- administrator defined password authentication routines
.SH "SYNTAX"

.PP
\fI#include <pwauth\&.h>\fR 

.PP
\fIint pw_auth (char\fR  \fI*command,\fR  \fIchar\fR  \fI*user,\fR  \fIint\fR  \fIreason,\fR  \fIchar\fR  \fI*input)\fR\fI;\fR 

.SH "DESCRIPTION"

.PP
\fIpw_auth\fR invokes the administrator defined functions for a given user\&.

.PP
\fIcommand\fR is the name of the authentication program\&. It is retrieved from the user's password file information\&. The string contains one or more executable file names, delimited by semi\-colons\&. Each program will be executed in the order given\&. The command line arguments are given for each of the reasons listed below\&.

.PP
\fIuser\fR is the name of the user to be authenticated, as given in the \fI/etc/passwd\fR file\&. User entries are indexed by username\&. This allows non\-unique user IDs to be present and for each different username associated with that user ID to have a different authentication program and information\&.

.PP
Each of the permissible authentication reasons is handled in a potentially differenent manner\&. Unless otherwise mentioned, the standard file descriptors 0, 1, and 2 are available for communicating with the user\&. The real user ID may be used to determine the identity of the user making the authentication request\&. \fIreason\fR is one of:

.TP
\fIPW_SU\fR
Perform authentication for the current real user ID attempting to switch real user ID to the named user\&. The authentication program will be invoked with a \fB\-s\fR option, followed by the username\&.

.TP
\fIPW_LOGIN\fR
Perform authentication for the named user creating a new login session\&. The authentication program will be invoked with a \fB\-l\fR option, followed by the username\&.

.TP
\fIPW_ADD\fR
Create a new entry for the named user\&. This allows an authentication program to initialize storage for a new user\&. The authentication program will be invoked with a \fB\-a\fR option, followed by the username\&.

.TP
\fIPW_CHANGE\fR
Alter an existing entry for the named user\&. This allows an authentication program to alter the authentication information for an existing user\&. The authentication program will be invoked with a \fB\-c\fR option, followed by the username\&.

.TP
\fIPW_DELETE\fR
Delete authentication information for the named user\&. This allows an authentication program to reclaim storage for a user which is no longer authenticated using the authentication program\&. The authentication program will be invoked with a \fB\-d\fR option, followed by the username\&.

.TP
\fIPW_TELNET\fR
Authenticate a user who is connecting to the system using the \fItelnet\fR command\&. The authentication program will be invoked with a \fB\-t\fR option, followed by the username\&.

.TP
\fIPW_RLOGIN\fR
Authenticate a user who is connecting to the system using the \fIrlogin\fR command\&. The authentication program will be invoked with a \fB\-r\fR option, followed by the username\&.

.TP
\fIPW_FTP\fR
Authenticate a user who is connecting to the system using the \fIftp\fR command\&. The authentication program will be invoked with a \fB\-f\fR option, followed by the username\&. The standard file descriptors are not available for communicating with the user\&. The standard input file descriptor will be connected to the parent process, while the other two output file descriptors will be connected to \fI/dev/null\fR\&. The \fIpw_auth\fR function will pipe a single line of data to the authentication program using file descriptor 0\&.

.TP
\fIPW_REXEC\fR
Authenticate a user who is connecting to the system using the \fIrexec\fR command\&. The authentication program will be invoked with a \fB\-x\fR option, followed by the username\&. The standard file descriptors are not available for communicating with the remote user\&. The standard input file descriptor will be connected to the parent process, while the other two output file descriptors will be connected to \fI/dev/null\fR\&. The \fIpw_auth\fR function will pipe a single line of data to the authentication program using file descriptor 0\&.

.PP
The last argument is the authentication data which is used by the \fIPW_FTP\fR and \fIPW_REXEC\fR reasons\&. It is treated as a single line of text which is piped to the authentication program\&. When the reason is \fIPW_CHANGE,\fR the value of \fIinput\fR is the value of previous user name if the user name is being changed\&.

.SH "CAVEATS"

.PP
This function does not create the actual session\&. It only indicates if the user should be allowed to create the session\&.

.PP
The network options are untested at this time\&.

.SH "DIAGNOSTICS"

.PP
The \fIpw_auth\fR function returns 0 if the authentication program exited with a 0 exit code, and a non\-zero value otherwise\&.

.SH "SEE ALSO"

.PP
\fBlogin\fR(1), \fBpasswd\fR(1), \fBsu\fR(1), \fBuseradd\fR(8), \fBuserdel\fR(8), \fBusermod\fR(8) 

.SH "AUTHOR"

.PP
Julianne Frances Haugh (jockgrrl@ix\&.netcom\&.com)