share/man/man3ext/auto_ef.3ext

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