auto_ef(3EXT) Extended Library Functions auto_ef(3EXT)NAME
auto_ef, auto_ef_file, auto_ef_str, auto_ef_free, auto_ef_get_encoding,
auto_ef_get_score - auto encoding finder functions
SYNOPSIS
cc [ flag ... ] file... -lauto_ef [ library... ]
#include <auto_ef.h>
size_t auto_ef_file(auto_ef_t **info, const char *filename, int flags);
size_t auto_ef_str(auto_ef_t **info, const char *buffer, size_t buf‐
size, int flags);
void auto_ef_free(auto_ef_t *info);
char *auto_ef_get_encoding(auto_ef_t info);
double auto_ef_get_score(auto_ef_t info);
DESCRIPTION
Auto encoding finder provides functions that find the encoding of given
file or string.
The auto_ef_file() function examines text in the file specified with
filename and returns information on possible encodings.
The info argument is a pointer to a pointer to an auto_ef_t, the loca‐
tion at which the pointer to the auto_ef_t array is stored upon return.
The flags argument specifies the level of examination. Currently only
one set of flags, exclusive each other, is available: AE_LEVEL_0,
AE_LEVEL_1, AE_LEVEL_2, and AE_LEVEL_3. The AE_LEVEL_0 level is fastest
but the result can be less accurate. The AE_LEVEL_3 level produces best
result but can be slow. If the flags argument is unspecified, the
default is AE_LEVEL_0. When another flag or set of flags are defined in
the future, use the inclusive-bitwise OR operation to specify multiple
flags.
Information about encodings are stored in data typeauto_ef_t in the
order of possibility with the most possible encoding stored first. To
examine the information, use the auto_ef_get_encoding() and
auto_ef_get_score() access functions. For a list of encodings with
which auto_ef_file() can examine text, see auto_ef(1).
If auto_ef_file() cannot determine the encoding of text, it returns 0
and stores NULL at the location pointed by info.
The auto_ef_get_encoding() function returns the name of the encoding.
The returned string is vaild until until the location pointed to by
info is freed with auto_ef_free(). Applications should not use free(3C)
to free the pointer returned by auto_ef_get_encoding().
The auto_ef_get_score() function returns the score of this encoding in
the range between 0.0 and 1.0.
The auto_ef_str() function is identical to auto_ef_file(), except that
it examines text in the buffer specified by buffer with a maximum size
of bufsize bytes, instead of text in a file.
The auto_ef_free() function frees the area allocated by auto_ef_file()
or by auto_ef_str(), taking as its argument the pointer stored at the
location pointed to by info.
RETURN VALUES
Upon successful completion, the auto_ef_file() and auto_ef_str() func‐
tions return the number of possible encodings for which information is
stored. Otherwise, −1 is returned.
The auto_ef_get_encoding() function returns the string that stores the
encoding name.
the auto_ef_get_score() function returns the score value for encoding
the name with the examined text data.
ERRORS
The auto_ef_file() and auto_ef_str() will fail if:
EACCES 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 libauto_ef cannot find the
internal hashtable.
EINTR A signal was caught during the execution.
ENOMEM Failed to allocate area to store the result.
EMFILE Too many files descriptors are currently open in the
calling process.
ENFILE Too many files are currently open in the system.
EXAMPLES
Example 1: Specify the array index to examine stored information.
Since auto_ef_file() stores the array whose elements hold information
on each possible encoding, the following example specifies the array
index to examine the stored information.
#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);
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Stable │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │MT-Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOauto_ef(1), libauto_ef(3LIB), attributes(5)SunOS 5.10 22 Sep 2003 auto_ef(3EXT)
