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 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);
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 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.
RETURN VALUES
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.
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 ALSO
auto_ef(1), libauto_ef(3LIB), attributes(5)
SunOS 5.10 22 Sep 2003 auto_ef(3EXT)