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.72.0 <http://docbook.sf.net/>
   7 .\"      Date: 07/21/2007
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"
  11 .TH "AUTH_ENUMERATE" "3" "07/21/2007" "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 .RS 4
  38 \h'-04'\(bu\h'+03'Account name.
  39 .RE
  40 .RS 4
  41 \h'-04'\(bu\h'+03'Account's numeric userid.
  42 .RE
  43 .RS 4
  44 \h'-04'\(bu\h'+03'Account's numeric groupid.
  45 .RE
  46 .RS 4
  47 \h'-04'\(bu\h'+03'Account's home directory.
  48 .RE
  49 .RS 4
  50 \h'-04'\(bu\h'+03'Account's mailbox (if defined, may be
  51 NULL, which indicates the default mailbox location).
  52 .RE
  53 .RS 4
  54 \h'-04'\(bu\h'+03'Account's options string (if defined, may be
  55 NULL)
  56 .RE
  57 .RS 4
  58 \h'-04'\(bu\h'+03'
  59 \fIcallback_arg\fR, verbatim.
  60 .RE
  61 .PP
  62 After invoking
  63 \fBcallback_func\fR
  64 for the last account,
  65 \fBauth_enumerate\fR
  66 invokes
  67 \fBcallback_func\fR
  68 one more time with all parameters set to
  69 NULL
  70 or 0.
  71 .PP
  72 If
  73 \fBauth_enumerate\fR
  74 encounters an error it will terminate without calling
  75 \fBcallback_func\fR
  76 with all
  77 NULL
  78 or 0 parameters. This can be used to determine whether a partial list of accounts was received.
  79 .sp
  80 .it 1 an-trap
  81 .nr an-no-space-flag 1
  82 .nr an-break-flag 1
  83 .br
  84 \fBNote\fR
  85 .PP
  86 Some back\-end Courier authentication modules do not implement account enumeration, so this function may not be available in all configurations.
  87 .SH "SEE ALSO"
  88 .PP
  89
  90 \fI\fBauthlib\fR(3)\fR\&[1],
  91 \fI\fBauth_generic\fR(3)\fR\&[2],
  92 \fI\fBauth_login\fR(3)\fR\&[3],
  93 \fI\fBauth_getuserinfo\fR(3)\fR\&[4],
  94 \fI\fBauth_passwd\fR(3)\fR\&[5].
  95 .SH "REFERENCES"
  96 .IP " 1." 4
  97 \fBauthlib\fR(3)
  98 .RS 4
  99 \%authlib.html
 100 .RE
 101 .IP " 2." 4
 102 \fBauth_generic\fR(3)
 103 .RS 4
 104 \%auth_generic.html
 105 .RE
 106 .IP " 3." 4
 107 \fBauth_login\fR(3)
 108 .RS 4
 109 \%auth_login.html
 110 .RE
 111 .IP " 4." 4
 112 \fBauth_getuserinfo\fR(3)
 113 .RS 4
 114 \%auth_getuserinfo.html
 115 .RE
 116 .IP " 5." 4
 117 \fBauth_passwd\fR(3)
 118 .RS 4
 119 \%auth_passwd.html
 120 .RE