openldap/doc/man/man3/ldap_friendly.3

.TH LDAP_FRIENDLY 3 "22 September 1998" "OpenLDAP LDVERSION"
.\" $OpenLDAP$
.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
.SH NAME
ldap_friendly_name, ldap_free_friendlymap \- LDAP unfriendly to friendly name mapping routine
.SH SYNOPSIS
.nf
.ft B
#include <ldap.h>
.LP
.ft B
typedef struct ldap_friendly {
        char *lf_unfriendly;
        char *lf_friendly;
} LDAPFriendlyMap;
.LP
.ft B
char *ldap_friendly_name(filename, name, map)
.ft
char *filename;
char *name;
LDAPFriendlyMap **map;
.LP
.ft B
void ldap_free_friendlymap(map)
.ft
LDAPFriendlyMap **map;
.SH DESCRIPTION
This routine is used to map one set of strings to another.  Typically,
this is done for country names, to map from the two-letter country
codes to longer more readable names.  The mechanism is general enough
to be used with other things, though.
.LP
\fIfilename\fP is the name of a file containing the unfriendly to
friendly mapping, \fIname\fP is the unfriendly name to map to a friendly
name, and \fImap\fP is a result-parameter that should be set to NULL
on the first call.  It is then used to hold the mapping in core so that
the file need not be read on subsequent calls.
.LP
For example:
.LP
.nf
.ft tt
        LDAPFriendlyMap *map = NULL;

        printf( "unfriendly %s => friendly %s\\n", name,
            ldap_friendly_name( "DATADIR/ldapfriendly", name, &map ) );
.ft
.fi
.LP
The mapping file should contain lines like this: unfriendlyname\\tfriendlyname.
Lines that begin with a '#' character are comments and are ignored.
.LP
The
.B ldap_free_friendlymap()
call is used to free structures allocated by
.B ldap_friendly_name()
when no more calls to
.B ldap_friendly_name()
are to be made.
.SH ERRORS
NULL is returned by
.B ldap_friendly_name()
if there is an error opening \fIfilename\fP, or if the file has a bad
format, or if the \fImap\fP parameter is NULL.
.SH FILES
DATADIR/ldapfriendly.conf
.SH SEE ALSO
.BR ldap (3)
.SH ACKNOWLEDGEMENTS
.B	OpenLDAP
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
.B	OpenLDAP
is derived from University of Michigan LDAP 3.3 Release.