auto_ef_str(3EXT) (man pages section 3: Extended Library Functions, Volume 1)

man pages section 3: Extended Library Functions, Volume 1

auto_ef_str(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