Merge branch 'debian'

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

.\"  <!-- $Id: auth_getoption.sgml,v 1.3 2007/04/01 00:21:34 mrsam Exp $ -->
.\"  <!-- Copyright 2004 Double Precision, Inc.  See COPYING for -->
.\"  <!-- distribution information. -->
.\"     Title: auth_getoption
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
.\"      Date: 08/23/2008
.\"    Manual: Double Precision, Inc.
.\"    Source: Double Precision, Inc.
.\"
.TH "AUTH_GETOPTION" "3" "08/23/2008" "Double Precision, Inc." "Double Precision, Inc."
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
auth_getoption - Search an option string
.SH "SYNOPSIS"
.sp
.RS 4
.nf
#include <courierauth\.h>
.fi
.RE
.HP 27
.BI "char *value=auth_getoption(const\ char\ *" "options" ", const\ char\ *" "keyword" ");"
.SH "DESCRIPTION"
.PP
This is a convenience function for parsing account options, as received by the callback function invoked by
\fI\fBauth_generic\fR(3)\fR\&[1],
\fI\fBauth_login\fR(3)\fR\&[2],
\fI\fBauth_getuserinfo\fR(3)\fR\&[3], and
\fI\fBauth_passwd\fR(3)\fR\&[4]\.
.PP

\fIoptions\fR
is the
options
field from
authinfo
(which can be
NULL)\. As described in
\fI\fBauth_generic\fR(3)\fR\&[1]
(and the others), it is a comma\-separated list of
\(lq\fIkeyword\fR=\fIvalue\fR\(rq
pairs\.
.PP

\fBauth_getoption\fR
searches
\fIoptions\fR
for a
\fIkeyword\fR\.
.SH "RETURNS"
.PP
If
\fIoptions\fR
does not have the
\fIkeyword\fR,
\fBauth_getoption\fR
returns
NULL
with
\fIerrno\fR
set to
ENOENT\. Otherwise
\fBauth_getoption\fR
allocates a buffer for
\fIvalue\fR, and returns it\. It is the caller\'s responsibility to
\fBfree\fR(3)
the returned buffer\.
.PP

\fBauth_getoption\fR
returns
NULL
with
\fIerrno\fR
set to
ENOMEM
if it cannot allocate a buffer\.
.SH "SEE ALSO"
.PP

\fI\fBauthlib\fR(3)\fR\&[5],
\fI\fBauth_generic\fR(3)\fR\&[1],
\fI\fBauth_login\fR(3)\fR\&[2],
\fI\fBauth_getuserinfo\fR(3)\fR\&[3]\.
.SH "NOTES"
.IP " 1." 4
\fBauth_generic\fR(3)
.RS 4
\%auth_generic.html
.RE
.IP " 2." 4
\fBauth_login\fR(3)
.RS 4
\%auth_login.html
.RE
.IP " 3." 4
\fBauth_getuserinfo\fR(3)
.RS 4
\%auth_getuserinfo.html
.RE
.IP " 4." 4
\fBauth_passwd\fR(3)
.RS 4
\%auth_passwd.html
.RE
.IP " 5." 4
\fBauthlib\fR(3)
.RS 4
\%authlib.html
.RE