1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
'\" te
.\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
.TH AUTO_EF 3EXT "Sep 22, 2003"
.SH NAME
auto_ef, auto_ef_file, auto_ef_str, auto_ef_free, auto_ef_get_encoding,
auto_ef_get_score \- auto encoding finder functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag \fR... ] \fIfile\fR... \fB-lauto_ef\fR [ \fIlibrary\fR... ]
#include <auto_ef.h>
\fBsize_t\fR \fBauto_ef_file\fR(\fBauto_ef_t **\fR\fIinfo\fR, \fBconst char *\fR\fIfilename\fR, \fBint\fR \fIflags\fR);
.fi
.LP
.nf
\fBsize_t\fR \fBauto_ef_str\fR(\fBauto_ef_t **\fR\fIinfo\fR, \fBconst char *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR,
\fBint\fR \fIflags\fR);
.fi
.LP
.nf
\fBvoid\fR \fBauto_ef_free\fR(\fBauto_ef_t *\fR\fIinfo\fR);
.fi
.LP
.nf
\fBchar *\fR\fBauto_ef_get_encoding\fR(\fBauto_ef_t\fR \fIinfo\fR);
.fi
.LP
.nf
\fBdouble\fR \fBauto_ef_get_score\fR(\fBauto_ef_t\fR \fIinfo\fR);
.fi
.SH DESCRIPTION
.sp
.LP
Auto encoding finder provides functions that find the encoding of given file or
string.
.sp
.LP
The \fBauto_ef_file()\fR function examines text in the file specified with
\fIfilename\fR and returns information on possible encodings.
.sp
.LP
The \fIinfo\fR argument is a pointer to a pointer to an \fBauto_ef_t\fR, the
location at which the pointer to the \fBauto_ef_t\fR array is stored upon
return.
.sp
.LP
The \fIflags\fR argument specifies the level of examination. Currently only one
set of flags, exclusive each other, is available: \fBAE_LEVEL_0\fR,
\fBAE_LEVEL_1\fR, \fBAE_LEVEL_2\fR, and \fBAE_LEVEL_3\fR. The \fBAE_LEVEL_0\fR
level is fastest but the result can be less accurate. The \fBAE_LEVEL_3\fR
level produces best result but can be slow. If the \fIflags\fR argument is
unspecified, the default is \fBAE_LEVEL_0\fR. When another flag or set of flags
are defined in the future, use the inclusive-bitwise OR operation to specify
multiple flags.
.sp
.LP
Information about encodings are stored in data type\fBauto_ef_t\fR in the order
of possibility with the most possible encoding stored first. To examine the
information, use the \fBauto_ef_get_encoding()\fR and \fBauto_ef_get_score()\fR
access functions. For a list of encodings with which \fBauto_ef_file()\fR can
examine text, see \fBauto_ef\fR(3EXT).
.sp
.LP
If \fBauto_ef_file()\fR cannot determine the encoding of text, it returns 0 and
stores \fINULL\fR at the location pointed by \fIinfo\fR.
.sp
.LP
The \fBauto_ef_get_encoding()\fR function returns the name of the encoding. The
returned string is vaild until until the location pointed to by \fIinfo\fR is
freed with \fBauto_ef_free()\fR. Applications should not use \fBfree\fR(3C) to
free the pointer returned by \fBauto_ef_get_encoding()\fR.
.sp
.LP
The \fBauto_ef_get_score()\fR function returns the score of this encoding in
the range between 0.0 and 1.0.
.sp
.LP
The \fBauto_ef_str()\fR function is identical to \fBauto_ef_file()\fR, except
that it examines text in the buffer specified by \fIbuffer\fR with a maximum
size of \fIbufsize\fR bytes, instead of text in a file.
.sp
.LP
The \fBauto_ef_free()\fR function frees the area allocated by
\fBauto_ef_file()\fR or by \fBauto_ef_str()\fR, taking as its argument the
pointer stored at the location pointed to by \fIinfo\fR.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, the \fBauto_ef_file()\fR and \fBauto_ef_str()\fR
functions return the number of possible encodings for which information is
stored. Otherwise, \(mi1 is returned.
.sp
.LP
The \fBauto_ef_get_encoding()\fR function returns the string that stores the
encoding name.
.sp
.LP
the \fBauto_ef_get_score()\fR function returns the score value for encoding the
name with the examined text data.
.SH ERRORS
.sp
.LP
The \fBauto_ef_file()\fR and \fBauto_ef_str()\fR will fail if:
.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 10n
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 \fBlibauto_ef\fR cannot find the internal hashtable.
.RE
.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 10n
A signal was caught during the execution.
.RE
.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
Failed to allocate area to store the result.
.RE
.sp
.ne 2
.na
\fB\fBEMFILE\fR\fR
.ad
.RS 10n
Too many files descriptors are currently open in the calling process.
.RE
.sp
.ne 2
.na
\fB\fBENFILE\fR\fR
.ad
.RS 10n
Too many files are currently open in the system.
.RE
.SH EXAMPLES
.LP
\fBExample 1 \fRSpecify the array index to examine stored information.
.sp
.LP
Since \fBauto_ef_file()\fR stores the array whose elements hold information on
each possible encoding, the following example specifies the array index to
examine the stored information.
.sp
.in +2
.nf
#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);
.fi
.in -2
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE ATTRIBUTE VALUE
_
Interface Stability Stable
_
MT-Level MT-Safe
.TE
.SH SEE ALSO
.sp
.LP
\fBauto_ef\fR(3EXT), \fBlibauto_ef\fR(3LIB), \fBattributes\fR(5)
|
