1.\" $File: libmagic.man,v 1.28 2014/03/02 14:47:16 christos Exp $
| 1.\" $File: libmagic.man,v 1.33 2014/11/28 02:46:39 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.\"
| 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 6, 2012
| 28.Dd November 27, 2014
|
29.Dt LIBMAGIC 3
30.Os
31.Sh NAME
32.Nm magic_open ,
33.Nm magic_close ,
34.Nm magic_error ,
35.Nm magic_errno ,
36.Nm magic_descriptor ,
37.Nm magic_buffer ,
38.Nm magic_setflags ,
39.Nm magic_check ,
40.Nm magic_compile ,
41.Nm magic_list ,
42.Nm magic_load ,
| 29.Dt LIBMAGIC 3
30.Os
31.Sh NAME
32.Nm magic_open ,
33.Nm magic_close ,
34.Nm magic_error ,
35.Nm magic_errno ,
36.Nm magic_descriptor ,
37.Nm magic_buffer ,
38.Nm magic_setflags ,
39.Nm magic_check ,
40.Nm magic_compile ,
41.Nm magic_list ,
42.Nm magic_load ,
|
| 43.Nm magic_load_buffers ,
44.Nm magic_setparam ,
45.Nm magic_getparam ,
|
43.Nm magic_version
44.Nd Magic number recognition library
45.Sh LIBRARY
46.Lb libmagic
47.Sh SYNOPSIS
48.In magic.h
49.Ft magic_t
50.Fn magic_open "int flags"
51.Ft void
52.Fn magic_close "magic_t cookie"
53.Ft const char *
54.Fn magic_error "magic_t cookie"
55.Ft int
56.Fn magic_errno "magic_t cookie"
57.Ft const char *
58.Fn magic_descriptor "magic_t cookie" "int fd"
59.Ft const char *
60.Fn magic_file "magic_t cookie" "const char *filename"
61.Ft const char *
62.Fn magic_buffer "magic_t cookie" "const void *buffer" "size_t length"
63.Ft int
64.Fn magic_setflags "magic_t cookie" "int flags"
65.Ft int
66.Fn magic_check "magic_t cookie" "const char *filename"
67.Ft int
68.Fn magic_compile "magic_t cookie" "const char *filename"
69.Ft int
70.Fn magic_list "magic_t cookie" "const char *filename"
71.Ft int
72.Fn magic_load "magic_t cookie" "const char *filename"
73.Ft int
| 46.Nm magic_version
47.Nd Magic number recognition library
48.Sh LIBRARY
49.Lb libmagic
50.Sh SYNOPSIS
51.In magic.h
52.Ft magic_t
53.Fn magic_open "int flags"
54.Ft void
55.Fn magic_close "magic_t cookie"
56.Ft const char *
57.Fn magic_error "magic_t cookie"
58.Ft int
59.Fn magic_errno "magic_t cookie"
60.Ft const char *
61.Fn magic_descriptor "magic_t cookie" "int fd"
62.Ft const char *
63.Fn magic_file "magic_t cookie" "const char *filename"
64.Ft const char *
65.Fn magic_buffer "magic_t cookie" "const void *buffer" "size_t length"
66.Ft int
67.Fn magic_setflags "magic_t cookie" "int flags"
68.Ft int
69.Fn magic_check "magic_t cookie" "const char *filename"
70.Ft int
71.Fn magic_compile "magic_t cookie" "const char *filename"
72.Ft int
73.Fn magic_list "magic_t cookie" "const char *filename"
74.Ft int
75.Fn magic_load "magic_t cookie" "const char *filename"
76.Ft int
|
| 77.Fn magic_load_buffers "magic_t cookie" "void **buffers" "size_t *sizes" "size_t nbuffers"
78.Ft int
79.Fn magic_getparam "magic_t cookie" "int param" "void *value"
80.Ft int
81.Fn magic_setparam "magic_t cookie" "int param" "const void *value"
82.Ft int
|
74.Fn magic_version "void"
75.Sh DESCRIPTION
76These functions
77operate on the magic database file
78which is described
79in
80.Xr magic __FSECTION__ .
81.Pp
82The function
83.Fn magic_open
84creates a magic cookie pointer and returns it.
85It returns
86.Dv NULL
87if there was an error allocating the magic cookie.
88The
89.Ar flags
90argument specifies how the other magic functions should behave:
91.Bl -tag -width MAGIC_COMPRESS
92.It Dv MAGIC_NONE
93No special handling.
94.It Dv MAGIC_DEBUG
95Print debugging messages to stderr.
96.It Dv MAGIC_SYMLINK
97If the file queried is a symlink, follow it.
98.It Dv MAGIC_COMPRESS
99If the file is compressed, unpack it and look at the contents.
100.It Dv MAGIC_DEVICES
101If the file is a block or character special device, then open the device
102and try to look in its contents.
103.It Dv MAGIC_MIME_TYPE
104Return a MIME type string, instead of a textual description.
105.It Dv MAGIC_MIME_ENCODING
106Return a MIME encoding, instead of a textual description.
107.It Dv MAGIC_MIME
108A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING.
109.It Dv MAGIC_CONTINUE
110Return all matches, not just the first.
111.It Dv MAGIC_CHECK
112Check the magic database for consistency and print warnings to stderr.
113.It Dv MAGIC_PRESERVE_ATIME
114On systems that support
115.Xr utime 3
116or
117.Xr utimes 2 ,
118attempt to preserve the access time of files analysed.
119.It Dv MAGIC_RAW
120Don't translate unprintable characters to a \eooo octal representation.
121.It Dv MAGIC_ERROR
122Treat operating system errors while trying to open files and follow symlinks
123as real errors, instead of printing them in the magic buffer.
124.It Dv MAGIC_APPLE
125Return the Apple creator and type.
126.It Dv MAGIC_NO_CHECK_APPTYPE
127Don't check for
128.Dv EMX
129application type (only on EMX).
130.It Dv MAGIC_NO_CHECK_CDF
131Don't get extra information on MS Composite Document Files.
132.It Dv MAGIC_NO_CHECK_COMPRESS
133Don't look inside compressed files.
134.It Dv MAGIC_NO_CHECK_ELF
135Don't print ELF details.
136.It Dv MAGIC_NO_CHECK_ENCODING
137Don't check text encodings.
138.It Dv MAGIC_NO_CHECK_SOFT
139Don't consult magic files.
140.It Dv MAGIC_NO_CHECK_TAR
141Don't examine tar files.
142.It Dv MAGIC_NO_CHECK_TEXT
143Don't check for various types of text files.
144.It Dv MAGIC_NO_CHECK_TOKENS
145Don't look for known tokens inside ascii files.
146.El
147.Pp
148The
149.Fn magic_close
150function closes the
151.Xr magic __FSECTION__
152database and deallocates any resources used.
153.Pp
154The
155.Fn magic_error
156function returns a textual explanation of the last error, or
157.Dv NULL
158if there was no error.
159.Pp
160The
161.Fn magic_errno
162function returns the last operating system error number
163.Pq Xr errno 2
164that was encountered by a system call.
165.Pp
166The
167.Fn magic_file
168function returns a textual description of the contents of the
169.Ar filename
170argument, or
171.Dv NULL
172if an error occurred.
173If the
174.Ar filename
175is
176.Dv NULL ,
177then stdin is used.
178.Pp
179The
180.Fn magic_descriptor
181function returns a textual description of the contents of the
182.Ar fd
183argument, or
184.Dv NULL
185if an error occurred.
186.Pp
187The
188.Fn magic_buffer
189function returns a textual description of the contents of the
190.Ar buffer
191argument with
192.Ar length
193bytes size.
194.Pp
195The
196.Fn magic_setflags
197function sets the
198.Ar flags
199described above.
200Note that using both MIME flags together can also
201return extra information on the charset.
202.Pp
203The
204.Fn magic_check
205function can be used to check the validity of entries in the colon
206separated database files passed in as
207.Ar filename ,
208or
209.Dv NULL
210for the default database.
211It returns 0 on success and \-1 on failure.
212.Pp
213The
214.Fn magic_compile
215function can be used to compile the the colon
216separated list of database files passed in as
217.Ar filename ,
218or
219.Dv NULL
220for the default database.
221It returns 0 on success and \-1 on failure.
222The compiled files created are named from the
223.Xr basename 1
224of each file argument with
225.Dq .mgc
226appended to it.
227.Pp
228The
229.Fn magic_list
230function dumps all magic entries in a human readable format,
231dumping first the entries that are matched against binary files and then the
232ones that match text files.
233It takes and optional
234.Fa filename
235argument which is a colon separated list of database files, or
236.Dv NULL
237for the default database.
238.Pp
239The
240.Fn magic_load
241function must be used to load the the colon
242separated list of database files passed in as
243.Ar filename ,
244or
245.Dv NULL
246for the default database file before any magic queries can performed.
247.Pp
248The default database file is named by the MAGIC environment variable.
249If that variable is not set, the default database file name is __MAGIC__.
250.Fn magic_load
251adds
252.Dq .mgc
253to the database filename as appropriate.
254.Pp
255The
| 83.Fn magic_version "void"
84.Sh DESCRIPTION
85These functions
86operate on the magic database file
87which is described
88in
89.Xr magic __FSECTION__ .
90.Pp
91The function
92.Fn magic_open
93creates a magic cookie pointer and returns it.
94It returns
95.Dv NULL
96if there was an error allocating the magic cookie.
97The
98.Ar flags
99argument specifies how the other magic functions should behave:
100.Bl -tag -width MAGIC_COMPRESS
101.It Dv MAGIC_NONE
102No special handling.
103.It Dv MAGIC_DEBUG
104Print debugging messages to stderr.
105.It Dv MAGIC_SYMLINK
106If the file queried is a symlink, follow it.
107.It Dv MAGIC_COMPRESS
108If the file is compressed, unpack it and look at the contents.
109.It Dv MAGIC_DEVICES
110If the file is a block or character special device, then open the device
111and try to look in its contents.
112.It Dv MAGIC_MIME_TYPE
113Return a MIME type string, instead of a textual description.
114.It Dv MAGIC_MIME_ENCODING
115Return a MIME encoding, instead of a textual description.
116.It Dv MAGIC_MIME
117A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING.
118.It Dv MAGIC_CONTINUE
119Return all matches, not just the first.
120.It Dv MAGIC_CHECK
121Check the magic database for consistency and print warnings to stderr.
122.It Dv MAGIC_PRESERVE_ATIME
123On systems that support
124.Xr utime 3
125or
126.Xr utimes 2 ,
127attempt to preserve the access time of files analysed.
128.It Dv MAGIC_RAW
129Don't translate unprintable characters to a \eooo octal representation.
130.It Dv MAGIC_ERROR
131Treat operating system errors while trying to open files and follow symlinks
132as real errors, instead of printing them in the magic buffer.
133.It Dv MAGIC_APPLE
134Return the Apple creator and type.
135.It Dv MAGIC_NO_CHECK_APPTYPE
136Don't check for
137.Dv EMX
138application type (only on EMX).
139.It Dv MAGIC_NO_CHECK_CDF
140Don't get extra information on MS Composite Document Files.
141.It Dv MAGIC_NO_CHECK_COMPRESS
142Don't look inside compressed files.
143.It Dv MAGIC_NO_CHECK_ELF
144Don't print ELF details.
145.It Dv MAGIC_NO_CHECK_ENCODING
146Don't check text encodings.
147.It Dv MAGIC_NO_CHECK_SOFT
148Don't consult magic files.
149.It Dv MAGIC_NO_CHECK_TAR
150Don't examine tar files.
151.It Dv MAGIC_NO_CHECK_TEXT
152Don't check for various types of text files.
153.It Dv MAGIC_NO_CHECK_TOKENS
154Don't look for known tokens inside ascii files.
155.El
156.Pp
157The
158.Fn magic_close
159function closes the
160.Xr magic __FSECTION__
161database and deallocates any resources used.
162.Pp
163The
164.Fn magic_error
165function returns a textual explanation of the last error, or
166.Dv NULL
167if there was no error.
168.Pp
169The
170.Fn magic_errno
171function returns the last operating system error number
172.Pq Xr errno 2
173that was encountered by a system call.
174.Pp
175The
176.Fn magic_file
177function returns a textual description of the contents of the
178.Ar filename
179argument, or
180.Dv NULL
181if an error occurred.
182If the
183.Ar filename
184is
185.Dv NULL ,
186then stdin is used.
187.Pp
188The
189.Fn magic_descriptor
190function returns a textual description of the contents of the
191.Ar fd
192argument, or
193.Dv NULL
194if an error occurred.
195.Pp
196The
197.Fn magic_buffer
198function returns a textual description of the contents of the
199.Ar buffer
200argument with
201.Ar length
202bytes size.
203.Pp
204The
205.Fn magic_setflags
206function sets the
207.Ar flags
208described above.
209Note that using both MIME flags together can also
210return extra information on the charset.
211.Pp
212The
213.Fn magic_check
214function can be used to check the validity of entries in the colon
215separated database files passed in as
216.Ar filename ,
217or
218.Dv NULL
219for the default database.
220It returns 0 on success and \-1 on failure.
221.Pp
222The
223.Fn magic_compile
224function can be used to compile the the colon
225separated list of database files passed in as
226.Ar filename ,
227or
228.Dv NULL
229for the default database.
230It returns 0 on success and \-1 on failure.
231The compiled files created are named from the
232.Xr basename 1
233of each file argument with
234.Dq .mgc
235appended to it.
236.Pp
237The
238.Fn magic_list
239function dumps all magic entries in a human readable format,
240dumping first the entries that are matched against binary files and then the
241ones that match text files.
242It takes and optional
243.Fa filename
244argument which is a colon separated list of database files, or
245.Dv NULL
246for the default database.
247.Pp
248The
249.Fn magic_load
250function must be used to load the the colon
251separated list of database files passed in as
252.Ar filename ,
253or
254.Dv NULL
255for the default database file before any magic queries can performed.
256.Pp
257The default database file is named by the MAGIC environment variable.
258If that variable is not set, the default database file name is __MAGIC__.
259.Fn magic_load
260adds
261.Dq .mgc
262to the database filename as appropriate.
263.Pp
264The
|
| 265.Fn magic_load_buffers
266function takes an array of size
267.Fa nbuffers
268of
269.Fa buffers
270with a respective size for each in the array of
271.Fa sizes
272loaded with the contents of the magic databases from the filesystem.
273This function can be used in environment where the magic library does
274not have direct access to the filesystem, but can access the magic
275database via shared memory or other IPC means.
276.Pp
277The
278.Fn magic_getparam
279and
280.Fn magic_setparam
281allow getting and setting various limits related to the the magic
282library.
283.Bl -column "MAGIC_PARAM_ELF_PHNUM_MAX" "size_t" "Default" -offset indent
284.It Sy "Parameter" Ta Sy "Type" Ta Sy "Default"
285.It Li MAGIC_PARAM_INDIR_MAX Ta size_t Ta 15
286.It Li MAGIC_PARAM_NAME_MAX Ta size_t Ta 30
287.It Li MAGIC_PARAM_ELF_PHNUM_MAX Ta size_t Ta 128
288.It Li MAGIC_PARAM_ELF_SHNUM_MAX Ta size_t Ta 32768
289.El
290.Pp
291The
292.Dv MAGIC_PARAM_INDIR_RECURSION
293parameter controls how many levels of recursion will be followed for
294indirect magic entries.
295.Pp
296The
297.Dv MAGIC_PARAM_NAME_RECURSION
298parameter controls how many levels of recursion will be followed for
299for name/use calls.
300.Pp
301The
302.Dv MAGIC_PARAM_NAME_MAX
303parameter controls the maximum number of calls for name/use.
304.Pp
305The
306.Dv MAGIC_PARAM_PHNUM_MAX
307parameter controls how many elf program sections will be processed.
308.Pp
309The
310.Dv MAGIC_PARAM_SHNUM_MAX
311parameter controls how many elf sections will be processed.
312.Pp
313The
|
256.Fn magic_version
257command returns the version number of this library which is compiled into
258the shared library using the constant
259.Dv MAGIC_VERSION
260from
261.In magic.h .
262This can be used by client programs to verify that the version they compile
263against is the same as the version that they run against.
264.Sh RETURN VALUES
265The function
266.Fn magic_open
267returns a magic cookie on success and
268.Dv NULL
269on failure setting errno to an appropriate value.
270It will set errno to
271.Er EINVAL
272if an unsupported value for flags was given.
273The
274.Fn magic_list ,
275.Fn magic_load ,
276.Fn magic_compile ,
277and
278.Fn magic_check
279functions return 0 on success and \-1 on failure.
280The
281.Fn magic_buffer ,
282.Fn magic_getpath ,
283and
284.Fn magic_file ,
285functions return a string on success and
286.Dv NULL
287on failure.
288The
289.Fn magic_error
290function returns a textual description of the errors of the above
291functions, or
292.Dv NULL
293if there was no error.
294The
295.Fn magic_version
296always returns the version number of the library.
297Finally,
298.Fn magic_setflags
299returns \-1 on systems that don't support
300.Xr utime 3 ,
301or
302.Xr utimes 2
303when
304.Dv MAGIC_PRESERVE_ATIME
305is set.
306.Sh FILES
307.Bl -tag -width __MAGIC__.mgc -compact
308.It Pa __MAGIC__
309The non-compiled default magic database.
310.It Pa __MAGIC__.mgc
311The compiled default magic database.
312.El
313.Sh SEE ALSO
314.Xr file __CSECTION__ ,
315.Xr magic __FSECTION__
316.Sh AUTHORS
317.An M\(oans Rullg\(oard
318Initial libmagic implementation, and configuration.
319.An Christos Zoulas
320API cleanup, error code and allocation handling.
| 314.Fn magic_version
315command returns the version number of this library which is compiled into
316the shared library using the constant
317.Dv MAGIC_VERSION
318from
319.In magic.h .
320This can be used by client programs to verify that the version they compile
321against is the same as the version that they run against.
322.Sh RETURN VALUES
323The function
324.Fn magic_open
325returns a magic cookie on success and
326.Dv NULL
327on failure setting errno to an appropriate value.
328It will set errno to
329.Er EINVAL
330if an unsupported value for flags was given.
331The
332.Fn magic_list ,
333.Fn magic_load ,
334.Fn magic_compile ,
335and
336.Fn magic_check
337functions return 0 on success and \-1 on failure.
338The
339.Fn magic_buffer ,
340.Fn magic_getpath ,
341and
342.Fn magic_file ,
343functions return a string on success and
344.Dv NULL
345on failure.
346The
347.Fn magic_error
348function returns a textual description of the errors of the above
349functions, or
350.Dv NULL
351if there was no error.
352The
353.Fn magic_version
354always returns the version number of the library.
355Finally,
356.Fn magic_setflags
357returns \-1 on systems that don't support
358.Xr utime 3 ,
359or
360.Xr utimes 2
361when
362.Dv MAGIC_PRESERVE_ATIME
363is set.
364.Sh FILES
365.Bl -tag -width __MAGIC__.mgc -compact
366.It Pa __MAGIC__
367The non-compiled default magic database.
368.It Pa __MAGIC__.mgc
369The compiled default magic database.
370.El
371.Sh SEE ALSO
372.Xr file __CSECTION__ ,
373.Xr magic __FSECTION__
374.Sh AUTHORS
375.An M\(oans Rullg\(oard
376Initial libmagic implementation, and configuration.
377.An Christos Zoulas
378API cleanup, error code and allocation handling.
|