'\" te
.\"  Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
.TH AUTO_EF 3EXT "Sep 22, 2003"
.SH NAME
auto_ef, auto_ef_file, auto_ef_str, auto_ef_free, auto_ef_get_encoding,
auto_ef_get_score \- auto encoding finder functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag \fR... ] \fIfile\fR... \fB-lauto_ef\fR [ \fIlibrary\fR... ]
#include <auto_ef.h>

\fBsize_t\fR \fBauto_ef_file\fR(\fBauto_ef_t **\fR\fIinfo\fR, \fBconst char *\fR\fIfilename\fR, \fBint\fR \fIflags\fR);
.fi

.LP
.nf
\fBsize_t\fR \fBauto_ef_str\fR(\fBauto_ef_t **\fR\fIinfo\fR, \fBconst char *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR,
     \fBint\fR \fIflags\fR);
.fi

.LP
.nf
\fBvoid\fR \fBauto_ef_free\fR(\fBauto_ef_t *\fR\fIinfo\fR);
.fi

.LP
.nf
\fBchar *\fR\fBauto_ef_get_encoding\fR(\fBauto_ef_t\fR \fIinfo\fR);
.fi

.LP
.nf
\fBdouble\fR \fBauto_ef_get_score\fR(\fBauto_ef_t\fR \fIinfo\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Auto encoding finder provides functions that find the encoding of given file or
string.
.sp
.LP
The \fBauto_ef_file()\fR function examines text in the file specified with
\fIfilename\fR and returns information on possible encodings.
.sp
.LP
The \fIinfo\fR argument is a pointer to a pointer to an \fBauto_ef_t\fR, the
location at which the pointer to the \fBauto_ef_t\fR array is stored upon
return.
.sp
.LP
The \fIflags\fR argument specifies the level of examination. Currently only one
set of flags, exclusive each other, is available: \fBAE_LEVEL_0\fR,
\fBAE_LEVEL_1\fR, \fBAE_LEVEL_2\fR, and \fBAE_LEVEL_3\fR. The \fBAE_LEVEL_0\fR
level is fastest but the result can be less accurate. The \fBAE_LEVEL_3\fR
level produces best result but can be slow. If the \fIflags\fR argument is
unspecified, the default is \fBAE_LEVEL_0\fR. When another flag or set of flags
are defined in the future, use the inclusive-bitwise OR operation to specify
multiple flags.
.sp
.LP
Information about encodings are stored in data type\fBauto_ef_t\fR in the order
of possibility with the most possible encoding stored first. To examine the
information, use the \fBauto_ef_get_encoding()\fR and \fBauto_ef_get_score()\fR
access functions. For a list of encodings with which \fBauto_ef_file()\fR can
examine text, see \fBauto_ef\fR(1).
.sp
.LP
If \fBauto_ef_file()\fR cannot determine the encoding of text, it returns 0 and
stores \fINULL\fR at the location pointed by \fIinfo\fR.
.sp
.LP
The \fBauto_ef_get_encoding()\fR function returns the name of the encoding. The
returned string is vaild until until the location pointed to by \fIinfo\fR is
freed with \fBauto_ef_free()\fR. Applications should not use \fBfree\fR(3C) to
free the pointer returned by \fBauto_ef_get_encoding()\fR.
.sp
.LP
The \fBauto_ef_get_score()\fR function returns the score of this encoding in
the range between 0.0 and 1.0.
.sp
.LP
The \fBauto_ef_str()\fR function is identical to \fBauto_ef_file()\fR, except
that it examines text in the buffer specified by \fIbuffer\fR with a maximum
size of \fIbufsize\fR bytes, instead of text in a file.
.sp
.LP
The \fBauto_ef_free()\fR function frees the area allocated by
\fBauto_ef_file()\fR or by \fBauto_ef_str()\fR, taking as its argument the
pointer stored at the location pointed to by \fIinfo\fR.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, the \fBauto_ef_file()\fR and \fBauto_ef_str()\fR
functions return the number of possible encodings for which information is
stored. Otherwise, \(mi1 is returned.
.sp
.LP
The \fBauto_ef_get_encoding()\fR function returns the string that stores the
encoding name.
.sp
.LP
the \fBauto_ef_get_score()\fR function returns the score value for encoding the
name with the examined text data.
.SH ERRORS
.sp
.LP
The \fBauto_ef_file()\fR and \fBauto_ef_str()\fR will fail if:
.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 10n
Search permission is denied on a component of the path prefix, the file exists
and the permissions specified by mode are denied, the file does not exist and
write permission is denied for the parent directory of the file to be created,
or \fBlibauto_ef\fR cannot find the internal hashtable.
.RE

.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 10n
A signal was caught during the execution.
.RE

.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
Failed to allocate area to store the result.
.RE

.sp
.ne 2
.na
\fB\fBEMFILE\fR\fR
.ad
.RS 10n
Too many files descriptors are currently open in the calling process.
.RE

.sp
.ne 2
.na
\fB\fBENFILE\fR\fR
.ad
.RS 10n
Too many files are currently open in the system.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRSpecify the array index to examine stored information.
.sp
.LP
Since \fBauto_ef_file()\fR stores the array whose elements hold information on
each possible encoding, the following example specifies the array index to
examine the stored information.

.sp
.in +2
.nf
#include <auto_ef.h>
auto_ef_t       *array_info;
size_t          number;
char            *encoding;

number = auto_ef_file(&array_info, filename, flags);
encoding = auto_ef_get_encoding(array_info[0]);
auto_ef_free(array_info);
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Stable
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBauto_ef\fR(1), \fBlibauto_ef\fR(3LIB), \fBattributes\fR(5)