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