libmagic(3)

1LIBMAGIC(3)              BSD Library Functions Manual              LIBMAGIC(3)
2

NAME

4     magic_open, magic_close, magic_error, magic_descriptor, magic_buffer,
5     magic_setflags, magic_check, magic_compile, magic_load — Magic number
6     recognition library
7

LIBRARY

9     Magic Number Recognition Library (libmagic, -lmagic)
10

SYNOPSIS

12     #include <magic.h>
13
14     magic_t
15     magic_open(int flags);
16
17     void
18     magic_close(magic_t cookie);
19
20     const char *
21     magic_error(magic_t cookie);
22
23     int
24     magic_errno(magic_t cookie);
25
26     const char *
27     magic_descriptor(magic_t cookie, int fd);
28
29     const char *
30     magic_file(magic_t cookie, const char *filename);
31
32     const char *
33     magic_buffer(magic_t cookie, const void *buffer, size_t length);
34
35     int
36     magic_setflags(magic_t cookie, int flags);
37
38     int
39     magic_check(magic_t cookie, const char *filename);
40
41     int
42     magic_compile(magic_t cookie, const char *filename);
43
44     int
45     magic_list(magic_t cookie, const char *filename);
46
47     int
48     magic_load(magic_t cookie, const char *filename);
49

DESCRIPTION

51     These functions operate on the magic database file which is described in
52     magic(5).
53
54     The function magic_open() creates a magic cookie pointer and returns it.
55     It returns NULL if there was an error allocating the magic cookie.  The
56     flags argument specifies how the other magic functions should behave:
57
58     MAGIC_NONE      No special handling.
59
60     MAGIC_DEBUG     Print debugging messages to stderr.
61
62     MAGIC_SYMLINK   If the file queried is a symlink, follow it.
63
64     MAGIC_COMPRESS  If the file is compressed, unpack it and look at the con‐
65                     tents.
66
67     MAGIC_DEVICES   If the file is a block or character special device, then
68                     open the device and try to look in its contents.
69
70     MAGIC_MIME_TYPE
71                     Return a MIME type string, instead of a textual descrip‐
72                     tion.
73
74     MAGIC_MIME_ENCODING
75                     Return a MIME encoding, instead of a textual description.
76
77     MAGIC_MIME      A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING.
78
79     MAGIC_CONTINUE  Return all matches, not just the first.
80
81     MAGIC_CHECK     Check the magic database for consistency and print warn‐
82                     ings to stderr.
83
84     MAGIC_PRESERVE_ATIME
85                     On systems that support utime(3) or utimes(2), attempt to
86                     preserve the access time of files analysed.
87
88     MAGIC_RAW       Don't translate unprintable characters to a \ooo octal
89                     representation.
90
91     MAGIC_ERROR     Treat operating system errors while trying to open files
92                     and follow symlinks as real errors, instead of printing
93                     them in the magic buffer.
94
95     MAGIC_APPLE     Return the Apple creator and type.
96
97     MAGIC_NO_CHECK_APPTYPE
98                     Don't check for EMX application type (only on EMX).
99
100     MAGIC_NO_CHECK_CDF
101                     Don't get extra information on MS Composite Document
102                     Files.
103
104     MAGIC_NO_CHECK_COMPRESS
105                     Don't look inside compressed files.
106
107     MAGIC_NO_CHECK_ELF
108                     Don't print ELF details.
109
110     MAGIC_NO_CHECK_ENCODING
111                     Don't check text encodings.
112
113     MAGIC_NO_CHECK_SOFT
114                     Don't consult magic files.
115
116     MAGIC_NO_CHECK_TAR
117                     Don't examine tar files.
118
119     MAGIC_NO_CHECK_TEXT
120                     Don't check for various types of text files.
121
122     MAGIC_NO_CHECK_TOKENS
123                     Don't look for known tokens inside ascii files.
124
125     The magic_close() function closes the magic(5) database and deallocates
126     any resources used.
127
128     The magic_error() function returns a textual explanation of the last
129     error, or NULL if there was no error.
130
131     The magic_errno() function returns the last operating system error number
132     (errno(2)) that was encountered by a system call.
133
134     The magic_file() function returns a textual description of the contents
135     of the filename argument, or NULL if an error occurred.  If the filename
136     is NULL, then stdin is used.
137
138     The magic_descriptor() function returns a textual description of the con‐
139     tents of the fd argument, or NULL if an error occurred.
140
141     The magic_buffer() function returns a textual description of the contents
142     of the buffer argument with length bytes size.
143
144     The magic_setflags() function sets the flags described above.  Note that
145     using both MIME flags together can also return extra information on the
146     charset.
147
148     The magic_check() function can be used to check the validity of entries
149     in the colon separated database files passed in as filename, or NULL for
150     the default database.  It returns 0 on success and -1 on failure.
151
152     The magic_compile() function can be used to compile the the colon sepa‐
153     rated list of database files passed in as filename, or NULL for the
154     default database.  It returns 0 on success and -1 on failure.  The com‐
155     piled files created are named from the basename(1) of each file argument
156     with “.mgc” appended to it.
157
158     The magic_list() function dumps all magic entries in a human readable
159     format, dumping first the entries that are matched against binary files
160     and then the ones that match text files.  It takes and optional filename
161     argument which is a colon separated list of database files, or NULL for
162     the default database.
163
164     The magic_load() function must be used to load the the colon separated
165     list of database files passed in as filename, or NULL for the default
166     database file before any magic queries can performed.
167
168     The default database file is named by the MAGIC environment variable.  If
169     that variable is not set, the default database file name is
170     /usr/share/misc/magic.  magic_load() adds “.mgc” to the database filename
171     as appropriate.
172

RETURN VALUES

174     The function magic_open() returns a magic cookie on success and NULL on
175     failure setting errno to an appropriate value.  It will set errno to
176     EINVAL if an unsupported value for flags was given.  The magic_list(),
177     magic_load(), magic_compile(), and magic_check() functions return 0 on
178     success and -1 on failure.  The magic_buffer(), magic_getpath(), and
179     magic_file(), functions return a string on success and NULL on failure.
180     The magic_error() function returns a textual description of the errors of
181     the above functions, or NULL if there was no error.  Finally,
182     magic_setflags() returns -1 on systems that don't support utime(3), or
183     utimes(2) when MAGIC_PRESERVE_ATIME is set.
184

FILES

186     /usr/share/misc/magic      The non-compiled default magic database.
187     /usr/share/misc/magic.mgc  The compiled default magic database.
188

AUTHORS

193     Måns Rullgård Initial libmagic implementation, and configuration.
194     Christos Zoulas API cleanup, error code and allocation handling.
195
196BSD                            December 19, 2011                           BSD