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
auto_ef, auto_ef_file, auto_ef_str, auto_ef_free, auto_ef_get_encoding, auto_ef_get_score - auto encoding finder functions

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 bufsize,
 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);

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 location 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.

Upon successful completion, the auto_ef_file() and auto_ef_str() functions 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.

The auto_ef_file() and auto_ef_str() will fail if:

EACCES

EINTR

ENOMEM

EMFILE

ENFILE

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);

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Stable
MT-Level	MT-Safe

auto_ef(1), libauto_ef(3LIB), attributes(5)