Extended Library Functions                          autoef(3EXT)



NAME
     autoef,    autoeffile,     autoefstr,     autoeffree,
     autoefgetencoding,   autoefgetscore  -  auto  encoding
     finder functions

SYNOPSIS
     cc [ flag ... ] file... -lautoef [ library... ]
     #include 

     sizet autoeffile(autoeft **info, const char *filename, int flags);


     sizet autoefstr(autoeft **info, const char *buffer, sizet bufsize,
          int flags);


     void autoeffree(autoeft *info);


     char *autoefgetencoding(autoeft info);


     double autoefgetscore(autoeft info);


DESCRIPTION
     Auto encoding finder provides functions that find the encod-
     ing of given file or string.


     The autoeffile() function examines text in the file speci-
     fied  with  filename  and  returns  information  on possible
     encodings.


     The info argument is a pointer to a pointer to an autoeft,
     the  location at which the pointer to the autoeft array is
     stored upon return.


     The flags  argument  specifies  the  level  of  examination.
     Currently  only  one  set of flags, exclusive each other, is
     available:   AELEVEL0,   AELEVEL1,    AELEVEL2,    and
     AELEVEL3.  The  AELEVEL0 level is fastest but the result
     can be less accurate. The  AELEVEL3  level  produces  best
     result  but  can  be slow. If the flags argument is unspeci-
     fied, the default is AELEVEL0. When another flag or set of
     flags  are  defined in the future, use the inclusive-bitwise
     OR operation to specify multiple flags.






SunOS 5.11          Last change: 22 Sep 2003                    1






Extended Library Functions                          autoef(3EXT)



     Information about encodings are stored in data typeautoeft
     in  the order of possibility with the most possible encoding
     stored  first.  To  examine   the   information,   use   the
     autoefgetencoding()  and autoefgetscore() access func-
     tions. For a list of encodings with which autoeffile() can
     examine text, see autoef(1).


     If autoeffile() cannot determine the encoding of text,  it
     returns 0 and stores NUL at the location pointed by info.


     The autoefgetencoding() function returns the name of  the
     encoding. The returned string is vaild until until the loca-
     tion pointed to by info is freed with autoeffree(). Appli-
     cations should not use free(3C) to free the pointer returned
     by autoefgetencoding().


     The autoefgetscore() function returns the score  of  this
     encoding in the range between 0.0 and 1.0.


     The autoefstr() function is identical  to  autoeffile(),
     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 autoeffree() function  frees  the  area  allocated  by
     autoeffile()  or  by autoefstr(), taking as its argument
     the pointer stored at the location pointed to by info.

RETURN VALUES
     Upon   successful   completion,   the   autoeffile()   and
     autoefstr() functions return the number of possible encod-
     ings for which  information  is  stored.  Otherwise,  -1  is
     returned.


     The autoefgetencoding() function returns the string  that
     stores the encoding name.


     the autoefgetscore() function returns the score value for
     encoding the name with the examined text data.

ERORS
     The autoeffile() and autoefstr() will fail if:

     EACES    Search permission is denied on a component of  the
               path  prefix,  the file exists and the permissions



SunOS 5.11          Last change: 22 Sep 2003                    2






Extended Library Functions                          autoef(3EXT)



               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
               libautoef 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 informa-
     tion.


     Since autoeffile() stores the array  whose  elements  hold
     information on each possible encoding, the following example
     specifies the array index to examine the stored information.


       #include 
       autoeft       *arrayinfo;
       sizet          number;
       char            *encoding;

       number = autoeffile(&arrayinfo, filename, flags);
       encoding = autoefgetencoding(arrayinfo[0]);
       autoeffree(arrayinfo);


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:













SunOS 5.11          Last change: 22 Sep 2003                    3






Extended Library Functions                          autoef(3EXT)



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


SEE ALSO
     autoef(1), libautoef(3LIB), attributes(5)












































SunOS 5.11          Last change: 22 Sep 2003                    4