2f218db2216cbe39eb0fcf7e4112cc44f56af4a4
[dragonfly.git] / contrib / file / doc / libmagic.man
1 .\" $File: libmagic.man,v 1.24 2011/05/13 22:11:44 christos Exp $
2 .\"
3 .\" Copyright (c) Christos Zoulas 2003.
4 .\" All Rights Reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice immediately at the beginning of the file, without modification,
11 .\"    this list of conditions, and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
20 .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .Dd January 14, 2011
29 .Dt LIBMAGIC 3
30 .Os
31 .Sh NAME
32 .Nm magic_open ,
33 .Nm magic_close ,
34 .Nm magic_error ,
35 .Nm magic_descriptor ,
36 .Nm magic_buffer ,
37 .Nm magic_setflags ,
38 .Nm magic_check ,
39 .Nm magic_compile ,
40 .Nm magic_load
41 .Nd Magic number recognition library
42 .Sh LIBRARY
43 .Lb libmagic
44 .Sh SYNOPSIS
45 .In magic.h
46 .Ft magic_t
47 .Fn magic_open "int flags"
48 .Ft void
49 .Fn magic_close "magic_t cookie"
50 .Ft const char *
51 .Fn magic_error "magic_t cookie"
52 .Ft int
53 .Fn magic_errno "magic_t cookie"
54 .Ft const char *
55 .Fn magic_descriptor "magic_t cookie, "int fd"
56 .Ft const char *
57 .Fn magic_file "magic_t cookie, const char *filename"
58 .Ft const char *
59 .Fn magic_buffer "magic_t cookie" "const void *buffer" "size_t length"
60 .Ft int
61 .Fn magic_setflags "magic_t cookie" "int flags"
62 .Ft int
63 .Fn magic_check "magic_t cookie" "const char *filename"
64 .Ft int
65 .Fn magic_compile "magic_t cookie" "const char *filename"
66 .Ft int
67 .Fn magic_load "magic_t cookie" "const char *filename"
68 .Sh DESCRIPTION
69 These functions
70 operate on the magic database file
71 which is described
72 in
73 .Xr magic __FSECTION__ .
74 .Pp
75 The function
76 .Fn magic_open
77 creates a magic cookie pointer and returns it.
78 It returns
79 .Dv NULL
80 if there was an error allocating the magic cookie.
81 The
82 .Ar flags
83 argument specifies how the other magic functions should behave:
84 .Bl -tag -width MAGIC_COMPRESS
85 .It Dv MAGIC_NONE
86 No special handling.
87 .It Dv MAGIC_DEBUG
88 Print debugging messages to stderr.
89 .It Dv MAGIC_SYMLINK
90 If the file queried is a symlink, follow it.
91 .It Dv MAGIC_COMPRESS
92 If the file is compressed, unpack it and look at the contents.
93 .It Dv MAGIC_DEVICES
94 If the file is a block or character special device, then open the device
95 and try to look in its contents.
96 .It Dv MAGIC_MIME_TYPE
97 Return a MIME type string, instead of a textual description.
98 .It Dv MAGIC_MIME_ENCODING
99 Return a MIME encoding, instead of a textual description.
100 .It Dv MAGIC_MIME
101 A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING.
102 .It Dv MAGIC_CONTINUE
103 Return all matches, not just the first.
104 .It Dv MAGIC_CHECK
105 Check the magic database for consistency and print warnings to stderr.
106 .It Dv MAGIC_PRESERVE_ATIME
107 On systems that support
108 .Xr utime 3
109 or
110 .Xr utimes 2 ,
111 attempt to preserve the access time of files analysed.
112 .It Dv MAGIC_RAW
113 Don't translate unprintable characters to a \eooo octal representation.
114 .It Dv MAGIC_ERROR
115 Treat operating system errors while trying to open files and follow symlinks
116 as real errors, instead of printing them in the magic buffer.
117 .It Dv MAGIC_APPLE
118 Return the Apple creator and type.
119 .It Dv MAGIC_NO_CHECK_APPTYPE
120 Don't check for
121 .Dv EMX
122 application type (only on EMX).
123 .It Dv MAGIC_NO_CHECK_CDF
124 Don't get extra information on MS Composite Document Files.
125 .It Dv MAGIC_NO_CHECK_COMPRESS
126 Don't look inside compressed files.
127 .It Dv MAGIC_NO_CHECK_ELF
128 Don't print ELF details.
129 .It Dv NO_CHECK_ENCODING
130 Don't check text encodings.
131 .It Dv MAGIC_NO_CHECK_SOFT
132 Don't consult magic files.
133 .It Dv MAGIC_NO_CHECK_TAR
134 Don't examine tar files.
135 .It Dv MAGIC_NO_CHECK_TEXT
136 Don't check for various types of text files.
137 .It Dv MAGIC_NO_CHECK_TOKENS
138 Don't look for known tokens inside ascii files.
139 .El
140 .Pp
141 The
142 .Fn magic_close
143 function closes the
144 .Xr magic __FSECTION__
145 database and deallocates any resources used.
146 .Pp
147 The
148 .Fn magic_error
149 function returns a textual explanation of the last error, or
150 .Dv NULL
151 if there was no error.
152 .Pp
153 The
154 .Fn magic_errno
155 function returns the last operating system error number
156 .Pq Xr errno 2
157 that was encountered by a system call.
158 .Pp
159 The
160 .Fn magic_file
161 function returns a textual description of the contents of the
162 .Ar filename
163 argument, or
164 .Dv NULL
165 if an error occurred.
166 If the
167 .Ar filename
168 is
169 .Dv NULL ,
170 then stdin is used.
171 .Pp
172 The
173 .Fn magic_descriptor
174 function returns a textual description of the contents of the
175 .Ar fd
176 argument, or
177 .Dv NULL
178 if an error occurred.
179 .Pp
180 The
181 .Fn magic_buffer
182 function returns a textual description of the contents of the
183 .Ar buffer
184 argument with
185 .Ar length
186 bytes size.
187 .Pp
188 The
189 .Fn magic_setflags
190 function sets the
191 .Ar flags
192 described above.
193 Note that using both MIME flags together can also
194 return extra information on the charset.
195 .Pp
196 The
197 .Fn magic_check
198 function can be used to check the validity of entries in the colon
199 separated database files passed in as
200 .Ar filename ,
201 or
202 .Dv NULL
203 for the default database.
204 It returns 0 on success and \-1 on failure.
205 .Pp
206 The
207 .Fn magic_compile
208 function can be used to compile the the colon
209 separated list of database files passed in as
210 .Ar filename ,
211 or
212 .Dv NULL
213 for the default database.
214 It returns 0 on success and \-1 on failure.
215 The compiled files created are named from the
216 .Xr basename 1
217 of each file argument with
218 .Dq .mgc
219 appended to it.
220 .Pp
221 The
222 .Fn magic_load
223 function must be used to load the the colon
224 separated list of database files passed in as
225 .Ar filename ,
226 or
227 .Dv NULL
228 for the default database file before any magic queries can performed.
229 .Pp
230 The default database file is named by the MAGIC environment variable.
231 If that variable is not set, the default database file name is __MAGIC__.
232 .Fn magic_load
233 adds
234 .Dq .mgc
235 to the database filename as appropriate.
236 .Sh RETURN VALUES
237 The function
238 .Fn magic_open
239 returns a magic cookie on success and
240 .Dv NULL
241 on failure setting errno to an appropriate value.
242 It will set errno to
243 .Er EINVAL
244 if an unsupported value for flags was given.
245 The
246 .Fn magic_load ,
247 .Fn magic_compile ,
248 and
249 .Fn magic_check
250 functions return 0 on success and \-1 on failure.
251 The
252 .Fn magic_file ,
253 and
254 .Fn magic_buffer
255 functions return a string on success and
256 .Dv NULL
257 on failure.
258 The
259 .Fn magic_error
260 function returns a textual description of the errors of the above
261 functions, or
262 .Dv NULL
263 if there was no error.
264 Finally,
265 .Fn magic_setflags
266 returns \-1 on systems that don't support
267 .Xr utime 3 ,
268 or
269 .Xr utimes 2
270 when
271 .Dv MAGIC_PRESERVE_ATIME
272 is set.
273 .Sh FILES
274 .Bl -tag -width __MAGIC__.mgc -compact
275 .It Pa __MAGIC__
276 The non-compiled default magic database.
277 .It Pa __MAGIC__.mgc
278 The compiled default magic database.
279 .El
280 .Sh SEE ALSO
281 .Xr file __CSECTION__ ,
282 .Xr magic __FSECTION__
283 .Sh AUTHORS
284 .An M\(oans Rullg\(oard
285 Initial libmagic implementation, and configuration.
286 .An Christos Zoulas
287 API cleanup, error code and allocation handling.