hcoop release

[hcoop/debian/courier-authlib.git] / auth_enumerate.3

'\" t
.\"  <!-- Copyright 2004 Double Precision, Inc.  See COPYING for -->
.\"  <!-- distribution information. -->
.\"     Title: auth_enumerate
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/08/2017
.\"    Manual: Double Precision, Inc.
.\"    Source: Double Precision, Inc.
.\"  Language: English
.\"
.TH "AUTH_ENUMERATE" "3" "09/08/2017" "Double Precision, Inc." "Double Precision, Inc."
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
auth_enumerate \- Obtain list of accounts
.SH "SYNOPSIS"
.sp
.nf
#include <courierauth\&.h>
.fi
.HP \w'auth_enumerate('u
.BI "auth_enumerate(int\ " "(*callback_func)" "\ (const\ char\ *,\ uid_t,\ gid_t,\ const\ char\ *,\ const\ char\ *,\ const\ char\ *,\ void\ *), void\ *" "callback_arg" ");"
.SH "DESCRIPTION"
.PP
\fBauth_enumerate\fR
enumerates all of the available accounts\&.
\fBauth_enumerate\fR
repeatedly calls
\fBcallback_func\fR, once for each account\&.
\fBcallback_func\fR
receives the following arguments:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Account name\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Account\*(Aqs numeric userid\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Account\*(Aqs numeric groupid\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Account\*(Aqs home directory\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Account\*(Aqs mailbox (if defined, may be
NULL, which indicates the default mailbox location)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Account\*(Aqs options string (if defined, may be
NULL)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIcallback_arg\fR, verbatim\&.
.RE
.PP
After invoking
\fBcallback_func\fR
for the last account,
\fBauth_enumerate\fR
invokes
\fBcallback_func\fR
one more time with all parameters set to
NULL
or 0\&.
.PP
If
\fBauth_enumerate\fR
encounters an error it will terminate without calling
\fBcallback_func\fR
with all
NULL
or 0 parameters\&. This can be used to determine whether a partial list of accounts was received\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Some back\-end Courier authentication modules do not implement account enumeration, so this function may not be available in all configurations\&.
.sp .5v
.RE
.SH "SEE ALSO"
.PP
\m[blue]\fB\fBauthlib\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2,
\m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fB\fBauth_login\fR(3)\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fB\fBauth_getuserinfo\fR(3)\fR\m[]\&\s-2\u[4]\d\s+2,
\m[blue]\fB\fBauth_passwd\fR(3)\fR\m[]\&\s-2\u[5]\d\s+2\&.
.SH "NOTES"
.IP " 1." 4
\fBauthlib\fR(3)
.RS 4
\%http://www.courier-mta.org/authlib/authlib.html
.RE
.IP " 2." 4
\fBauth_generic\fR(3)
.RS 4
\%http://www.courier-mta.org/authlib/auth_generic.html
.RE
.IP " 3." 4
\fBauth_login\fR(3)
.RS 4
\%http://www.courier-mta.org/authlib/auth_login.html
.RE
.IP " 4." 4
\fBauth_getuserinfo\fR(3)
.RS 4
\%http://www.courier-mta.org/authlib/auth_getuserinfo.html
.RE
.IP " 5." 4
\fBauth_passwd\fR(3)
.RS 4
\%http://www.courier-mta.org/authlib/auth_passwd.html
.RE