auth_enumerate.3

   1 '\" t
   2 .\"  <!-- Copyright 2004 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: auth_enumerate
   5 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   6 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   7 .\"      Date: 09/08/2017
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"  Language: English
  11 .\"
  12 .TH "AUTH_ENUMERATE" "3" "09/08/2017" "Double Precision, Inc." "Double Precision, Inc."
  13 .\" -----------------------------------------------------------------
  14 .\" * Define some portability stuff
  15 .\" -----------------------------------------------------------------
  16 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  17 .\" http://bugs.debian.org/507673
  18 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  19 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  20 .ie \n(.g .ds Aq \(aq
  21 .el       .ds Aq '
  22 .\" -----------------------------------------------------------------
  23 .\" * set default formatting
  24 .\" -----------------------------------------------------------------
  25 .\" disable hyphenation
  26 .nh
  27 .\" disable justification (adjust text to left margin only)
  28 .ad l
  29 .\" -----------------------------------------------------------------
  30 .\" * MAIN CONTENT STARTS HERE *
  31 .\" -----------------------------------------------------------------
  32 .SH "NAME"
  33 auth_enumerate \- Obtain list of accounts
  34 .SH "SYNOPSIS"
  35 .sp
  36 .nf
  37 #include <courierauth\&.h>
  38 .fi
  39 .HP \w'auth_enumerate('u
  40 .BI "auth_enumerate(int\ " "(*callback_func)" "\ (const\ char\ *,\ uid_t,\ gid_t,\ const\ char\ *,\ const\ char\ *,\ const\ char\ *,\ void\ *), void\ *" "callback_arg" ");"
  41 .SH "DESCRIPTION"
  42 .PP
  43 \fBauth_enumerate\fR
  44 enumerates all of the available accounts\&.
  45 \fBauth_enumerate\fR
  46 repeatedly calls
  47 \fBcallback_func\fR, once for each account\&.
  48 \fBcallback_func\fR
  49 receives the following arguments:
  50 .sp
  51 .RS 4
  52 .ie n \{\
  53 \h'-04'\(bu\h'+03'\c
  54 .\}
  55 .el \{\
  56 .sp -1
  57 .IP \(bu 2.3
  58 .\}
  59 Account name\&.
  60 .RE
  61 .sp
  62 .RS 4
  63 .ie n \{\
  64 \h'-04'\(bu\h'+03'\c
  65 .\}
  66 .el \{\
  67 .sp -1
  68 .IP \(bu 2.3
  69 .\}
  70 Account\*(Aqs numeric userid\&.
  71 .RE
  72 .sp
  73 .RS 4
  74 .ie n \{\
  75 \h'-04'\(bu\h'+03'\c
  76 .\}
  77 .el \{\
  78 .sp -1
  79 .IP \(bu 2.3
  80 .\}
  81 Account\*(Aqs numeric groupid\&.
  82 .RE
  83 .sp
  84 .RS 4
  85 .ie n \{\
  86 \h'-04'\(bu\h'+03'\c
  87 .\}
  88 .el \{\
  89 .sp -1
  90 .IP \(bu 2.3
  91 .\}
  92 Account\*(Aqs home directory\&.
  93 .RE
  94 .sp
  95 .RS 4
  96 .ie n \{\
  97 \h'-04'\(bu\h'+03'\c
  98 .\}
  99 .el \{\
 100 .sp -1
 101 .IP \(bu 2.3
 102 .\}
 103 Account\*(Aqs mailbox (if defined, may be
 104 NULL, which indicates the default mailbox location)\&.
 105 .RE
 106 .sp
 107 .RS 4
 108 .ie n \{\
 109 \h'-04'\(bu\h'+03'\c
 110 .\}
 111 .el \{\
 112 .sp -1
 113 .IP \(bu 2.3
 114 .\}
 115 Account\*(Aqs options string (if defined, may be
 116 NULL)
 117 .RE
 118 .sp
 119 .RS 4
 120 .ie n \{\
 121 \h'-04'\(bu\h'+03'\c
 122 .\}
 123 .el \{\
 124 .sp -1
 125 .IP \(bu 2.3
 126 .\}
 127 \fIcallback_arg\fR, verbatim\&.
 128 .RE
 129 .PP
 130 After invoking
 131 \fBcallback_func\fR
 132 for the last account,
 133 \fBauth_enumerate\fR
 134 invokes
 135 \fBcallback_func\fR
 136 one more time with all parameters set to
 137 NULL
 138 or 0\&.
 139 .PP
 140 If
 141 \fBauth_enumerate\fR
 142 encounters an error it will terminate without calling
 143 \fBcallback_func\fR
 144 with all
 145 NULL
 146 or 0 parameters\&. This can be used to determine whether a partial list of accounts was received\&.
 147 .if n \{\
 148 .sp
 149 .\}
 150 .RS 4
 151 .it 1 an-trap
 152 .nr an-no-space-flag 1
 153 .nr an-break-flag 1
 154 .br
 155 .ps +1
 156 \fBNote\fR
 157 .ps -1
 158 .br
 159 .PP
 160 Some back\-end Courier authentication modules do not implement account enumeration, so this function may not be available in all configurations\&.
 161 .sp .5v
 162 .RE
 163 .SH "SEE ALSO"
 164 .PP
 165 \m[blue]\fB\fBauthlib\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2,
 166 \m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[2]\d\s+2,
 167 \m[blue]\fB\fBauth_login\fR(3)\fR\m[]\&\s-2\u[3]\d\s+2,
 168 \m[blue]\fB\fBauth_getuserinfo\fR(3)\fR\m[]\&\s-2\u[4]\d\s+2,
 169 \m[blue]\fB\fBauth_passwd\fR(3)\fR\m[]\&\s-2\u[5]\d\s+2\&.
 170 .SH "NOTES"
 171 .IP " 1." 4
 172 \fBauthlib\fR(3)
 173 .RS 4
 174 \%http://www.courier-mta.org/authlib/authlib.html
 175 .RE
 176 .IP " 2." 4
 177 \fBauth_generic\fR(3)
 178 .RS 4
 179 \%http://www.courier-mta.org/authlib/auth_generic.html
 180 .RE
 181 .IP " 3." 4
 182 \fBauth_login\fR(3)
 183 .RS 4
 184 \%http://www.courier-mta.org/authlib/auth_login.html
 185 .RE
 186 .IP " 4." 4
 187 \fBauth_getuserinfo\fR(3)
 188 .RS 4
 189 \%http://www.courier-mta.org/authlib/auth_getuserinfo.html
 190 .RE
 191 .IP " 5." 4
 192 \fBauth_passwd\fR(3)
 193 .RS 4
 194 \%http://www.courier-mta.org/authlib/auth_passwd.html
 195 .RE