auth_enumerate.3

   1 .\"  <!-- $Id: auth_enumerate.sgml,v 1.5 2007/07/21 20:05:53 mrsam Exp $ -->
   2 .\"  <!-- Copyright 2004 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: auth_enumerate
   5 .\"    Author:
   6 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
   7 .\"      Date: 08/23/2008
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"
  11 .TH "AUTH_ENUMERATE" "3" "08/23/2008" "Double Precision, Inc." "Double Precision, Inc."
  12 .\" disable hyphenation
  13 .nh
  14 .\" disable justification (adjust text to left margin only)
  15 .ad l
  16 .SH "NAME"
  17 auth_enumerate - Obtain list of accounts
  18 .SH "SYNOPSIS"
  19 .sp
  20 .RS 4
  21 .nf
  22 #include <courierauth\.h>
  23 .fi
  24 .RE
  25 .HP 15
  26 .BI "auth_enumerate(int\ " "(*callback_func)" "\ (const\ char\ *,\ uid_t,\ gid_t,\ const\ char\ *,\ const\ char\ *,\ const\ char\ *,\ void\ *), void\ *" "callback_arg" ");"
  27 .SH "DESCRIPTION"
  28 .PP
  29
  30 \fBauth_enumerate\fR
  31 enumerates all of the available accounts\.
  32 \fBauth_enumerate\fR
  33 repeatedly calls
  34 \fBcallback_func\fR, once for each account\.
  35 \fBcallback_func\fR
  36 receives the following arguments:
  37 .sp
  38 .RS 4
  39 \h'-04'\(bu\h'+03'Account name\.
  40 .RE
  41 .sp
  42 .RS 4
  43 \h'-04'\(bu\h'+03'Account\'s numeric userid\.
  44 .RE
  45 .sp
  46 .RS 4
  47 \h'-04'\(bu\h'+03'Account\'s numeric groupid\.
  48 .RE
  49 .sp
  50 .RS 4
  51 \h'-04'\(bu\h'+03'Account\'s home directory\.
  52 .RE
  53 .sp
  54 .RS 4
  55 \h'-04'\(bu\h'+03'Account\'s mailbox (if defined, may be
  56 NULL, which indicates the default mailbox location)\.
  57 .RE
  58 .sp
  59 .RS 4
  60 \h'-04'\(bu\h'+03'Account\'s options string (if defined, may be
  61 NULL)
  62 .RE
  63 .sp
  64 .RS 4
  65 \h'-04'\(bu\h'+03'
  66 \fIcallback_arg\fR, verbatim\.
  67 .RE
  68 .PP
  69 After invoking
  70 \fBcallback_func\fR
  71 for the last account,
  72 \fBauth_enumerate\fR
  73 invokes
  74 \fBcallback_func\fR
  75 one more time with all parameters set to
  76 NULL
  77 or 0\.
  78 .PP
  79 If
  80 \fBauth_enumerate\fR
  81 encounters an error it will terminate without calling
  82 \fBcallback_func\fR
  83 with all
  84 NULL
  85 or 0 parameters\. This can be used to determine whether a partial list of accounts was received\.
  86 .sp
  87 .it 1 an-trap
  88 .nr an-no-space-flag 1
  89 .nr an-break-flag 1
  90 .br
  91 Note
  92 .PP
  93 Some back\-end Courier authentication modules do not implement account enumeration, so this function may not be available in all configurations\.
  94 .SH "SEE ALSO"
  95 .PP
  96
  97 \fI\fBauthlib\fR(3)\fR\&[1],
  98 \fI\fBauth_generic\fR(3)\fR\&[2],
  99 \fI\fBauth_login\fR(3)\fR\&[3],
 100 \fI\fBauth_getuserinfo\fR(3)\fR\&[4],
 101 \fI\fBauth_passwd\fR(3)\fR\&[5]\.
 102 .SH "NOTES"
 103 .IP " 1." 4
 104 \fBauthlib\fR(3)
 105 .RS 4
 106 \%authlib.html
 107 .RE
 108 .IP " 2." 4
 109 \fBauth_generic\fR(3)
 110 .RS 4
 111 \%auth_generic.html
 112 .RE
 113 .IP " 3." 4
 114 \fBauth_login\fR(3)
 115 .RS 4
 116 \%auth_login.html
 117 .RE
 118 .IP " 4." 4
 119 \fBauth_getuserinfo\fR(3)
 120 .RS 4
 121 \%auth_getuserinfo.html
 122 .RE
 123 .IP " 5." 4
 124 \fBauth_passwd\fR(3)
 125 .RS 4
 126 \%auth_passwd.html
 127 .RE