.\" Hey Emacs! This file is -*- nroff -*- source.
.\" $Id$
.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
.TH PAM_START 3 "1997 Feb 15" "Linux-PAM 0.56" "Application Programmers' Manual"
.SH NAME

pam_start, pam_end \- activating Linux-PAM

.SH SYNOPSIS
.B #include <security/pam_appl.h>
.sp
.BI "int pam_start(const char " *service ", const char " *user ", const struct pam_conv " *conv ", pam_handle_t " **pamh_p ");"
.sp
.BI "int pam_end(pam_handle_t " *pamh ", int " pam_status ");"
.sp 2
.SH DESCRIPTION
.TP
.B pam_start
Initialize the
.I Linux-PAM
library.  Identifying the application with a particular
.IR service
name.  The
.IR user "name"
can take the value
.IR NULL ", "
if not known at the time the interface is initialized.  The
conversation structure is passed to the library via the
.IR conv
argument.  (For a complete description of this and other structures
the reader is directed to the more verbose
.IR Linux-PAM
application developers' guide).  Upon successful initialization, an
opaque pointer-handle for future access to the library is returned
through the contents of the
.IR pamh_p
pointer.

.TP
.B pam_end
Terminate the
.B Linux-PAM
library.  The service application associated with the
.IR pamh
handle, is terminated.  The argument,
.IR pam_status ", "
passes the value most recently returned to the application from the
library; it indicates the manner in which the library should be
shutdown.  Besides carrying a return value, this argument may be
logically OR'd with
.IR PAM_DATA_SILENT
to indicate that the module should not treat the call too
seriously. It is generally used to indicate that the current closing
of the library is in a
.IR fork "(2)ed"
process, and that the parent will take care of cleaning up things that
exist outside of the current process space (files etc.).

.SH "RETURN VALUE"
.TP
.B pam_start
.TP
.B pam_end
On success,
.BR PAM_SUCCESS
is returned

.SH ERRORS
May be translated to text with
.BR pam_strerror "(3). "

.SH "CONFORMING TO"
DCE-RFC 86.0, October 1995.
.sp
Note, the 
.BR PAM_DATA_SILENT
flag is pending acceptance with the DCE (as of 1996/12/4).

.SH BUGS
.sp 2
None known.

.SH "SEE ALSO"

.BR fork "(2), "
.BR pam_authenticate "(3), "
.BR pam_acct_mgmt "(3), "
.BR pam_open_session "(3), "
and
.BR pam_chauthtok "(3)."

Also, see the three
.BR Linux-PAM
Guides, for
.BR "System administrators" ", "
.BR "module developers" ", "
and
.BR "application developers" ". "