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)