auto_ef_get_encoding(3ext)

1auto_ef(3EXT)             Extended Library Functions             auto_ef(3EXT)
2
3
4

NAME

6       auto_ef, auto_ef_file, auto_ef_str, auto_ef_free, auto_ef_get_encoding,
7       auto_ef_get_score - auto encoding finder functions
8

SYNOPSIS

10       cc [ flag ... ] file... -lauto_ef [ library... ]
11       #include <auto_ef.h>
12
13       size_t auto_ef_file(auto_ef_t **info, const char *filename, int flags);
14
15
16       size_t auto_ef_str(auto_ef_t **info, const char *buffer, size_t bufsize,
17            int flags);
18
19
20       void auto_ef_free(auto_ef_t *info);
21
22
23       char *auto_ef_get_encoding(auto_ef_t info);
24
25
26       double auto_ef_get_score(auto_ef_t info);
27
28

DESCRIPTION

30       Auto encoding finder provides functions that find the encoding of given
31       file or string.
32
33
34       The  auto_ef_file()  function  examines text in the file specified with
35       filename and returns information on possible encodings.
36
37
38       The info argument is a pointer to a pointer to an auto_ef_t, the  loca‐
39       tion at which the pointer to the auto_ef_t array is stored upon return.
40
41
42       The  flags  argument specifies the level of examination. Currently only
43       one set of flags,  exclusive  each  other,  is  available:  AE_LEVEL_0,
44       AE_LEVEL_1, AE_LEVEL_2, and AE_LEVEL_3. The AE_LEVEL_0 level is fastest
45       but the result can be less accurate. The AE_LEVEL_3 level produces best
46       result  but  can  be  slow.  If  the flags argument is unspecified, the
47       default is AE_LEVEL_0. When another flag or set of flags are defined in
48       the  future, use the inclusive-bitwise OR operation to specify multiple
49       flags.
50
51
52       Information about encodings are stored in  data  typeauto_ef_t  in  the
53       order  of  possibility with the most possible encoding stored first. To
54       examine   the   information,   use   the   auto_ef_get_encoding()   and
55       auto_ef_get_score()  access  functions.  For  a  list of encodings with
56       which auto_ef_file() can examine text, see auto_ef(1).
57
58
59       If auto_ef_file() cannot determine the encoding of text, it  returns  0
60       and stores NULL at the location pointed by info.
61
62
63       The  auto_ef_get_encoding()  function returns the name of the encoding.
64       The returned string is vaild until until the  location  pointed  to  by
65       info is freed with auto_ef_free(). Applications should not use free(3C)
66       to free the pointer returned by auto_ef_get_encoding().
67
68
69       The auto_ef_get_score() function returns the score of this encoding  in
70       the range between 0.0 and 1.0.
71
72
73       The  auto_ef_str() function is identical to auto_ef_file(), except that
74       it examines text in the buffer specified by buffer with a maximum  size
75       of bufsize bytes, instead of text in a file.
76
77
78       The  auto_ef_free() function frees the area allocated by auto_ef_file()
79       or by auto_ef_str(), taking as its argument the pointer stored  at  the
80       location pointed to by info.
81

RETURN VALUES

83       Upon  successful completion, the auto_ef_file() and auto_ef_str() func‐
84       tions return the number of possible encodings for which information  is
85       stored. Otherwise, −1 is returned.
86
87
88       The  auto_ef_get_encoding() function returns the string that stores the
89       encoding name.
90
91
92       the auto_ef_get_score() function returns the score value  for  encoding
93       the name with the examined text data.
94

ERRORS

96       The auto_ef_file() and auto_ef_str() will fail if:
97
98       EACCES    Search  permission  is denied on a component of the path pre‐
99                 fix, the file exists and the permissions  specified  by  mode
100                 are  denied,  the file does not exist and write permission is
101                 denied for the parent directory of the file to be created, or
102                 libauto_ef cannot find the internal hashtable.
103
104
105       EINTR     A signal was caught during the execution.
106
107
108       ENOMEM    Failed to allocate area to store the result.
109
110
111       EMFILE    Too  many files descriptors are currently open in the calling
112                 process.
113
114
115       ENFILE    Too many files are currently open in the system.
116
117

EXAMPLES

119       Example 1 Specify the array index to examine stored information.
120
121
122       Since auto_ef_file() stores the array whose elements  hold  information
123       on  each  possible  encoding, the following example specifies the array
124       index to examine the stored information.
125
126
127         #include <auto_ef.h>
128         auto_ef_t       *array_info;
129         size_t          number;
130         char            *encoding;
131
132         number = auto_ef_file(&array_info, filename, flags);
133         encoding = auto_ef_get_encoding(array_info[0]);
134         auto_ef_free(array_info);
135
136

ATTRIBUTES

138       See attributes(5) for descriptions of the following attributes:
139
140
141
142
143       ┌─────────────────────────────┬─────────────────────────────┐
144       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
145       ├─────────────────────────────┼─────────────────────────────┤
146       │Interface Stability          │Stable                       │
147       ├─────────────────────────────┼─────────────────────────────┤
148       │MT-Level                     │MT-Safe                      │
149       └─────────────────────────────┴─────────────────────────────┘
150