1File::LibMagic(3) User Contributed Perl Documentation File::LibMagic(3)
2
6 File::LibMagic - Determine MIME types of data or files using libmagic
7
9 version 1.23
10
12 use File::LibMagic;
13 my $magic = File::LibMagic->new;
15 my $info = $magic->info_from_filename('path/to/file');
17 # Prints a description like "ASCII text"
18 print $info->{description};
19 # Prints a MIME type like "text/plain"
20 print $info->{mime_type};
21 # Prints a character encoding like "us-ascii"
22 print $info->{encoding};
23 # Prints a MIME type with encoding like "text/plain; charset=us-ascii"
24 print $info->{mime_with_encoding};
25 my $file_content = read_file('path/to/file');
27 $info = $magic->info_from_string($file_content);
28 open my $fh, '<', 'path/to/file' or die $!;
30 $info = $magic->info_from_handle($fh);
31
33 The "File::LibMagic" module is a simple perl interface to libmagic from
34 the file package (version 4.x or 5.x). You will need both the library
35 (libmagic.so) and the header file (magic.h) to build this Perl module.
36 Installing libmagic
38 On Debian/Ubuntu run:
39 sudo apt-get install libmagic-dev
41 on Red Hat run:
43 sudo yum install file-devel
45 On Mac you can use homebrew (https://brew.sh/):
47 brew install libmagic
49 Specifying lib and/or include directories
51 On some systems, you may need to pass additional lib and include
52 directories to the Makefile.PL. You can do this with the `--lib` and
53 `--include` parameters:
54 perl Makefile.PL --lib /usr/local/lib --include /usr/local/include
56 You can pass these parameters multiple times to specify more than one
58 location.
59
61 This module provides an object-oriented API with the following methods:
62 File::LibMagic->new
64 Creates a new File::LibMagic object.
65 Using the object oriented interface only opens the magic database once,
67 which is probably most efficient for repeated uses.
68 Each "File::LibMagic" object loads the magic database independently of
70 other "File::LibMagic" objects, so you may want to share a single
71 object across many modules.
72 This method takes the following named parameters:
74 • "magic_file"
76 This should be a string or an arrayref containing one or more magic
78 files.
79 If a file you provide doesn't exist the constructor will throw an
81 exception, but only with libmagic 4.17+.
82 If you don't set this parameter, the constructor will throw an
84 exception if it can't find any magic files at all.
85 Note that even if you're using a custom file, you probably also
87 want to use the standard file (/usr/share/misc/magic on my system,
88 yours may vary).
89 • "follow_symlinks"
91 If this is true, then calls to "$magic->info_from_filename" will
93 follow symlinks to the real file.
94 • "uncompress"
96 If this is true, then compressed files (such as gzip files) will be
98 uncompressed, and the various "info_from_*" methods will return
99 info about the uncompressed file.
100 • Processing limits
102 Newer versions of the libmagic library have a number of limits
104 order to prevent malformed or malicious files from causing resource
105 exhaustion or other errors.
106 If your libmagic support it, you can set the following limits
108 through constructor parameters. If your version does not support
109 setting these limits, passing these options will cause the
110 constructor to croak. In addition, the specific limits were
111 introduced over a number of libmagic releases, and your version of
112 libmagic may not support every parameter. Using a parameter that is
113 not supported by your libmagic will also cause the constructor to
114 cloak.
115 • "max_indir"
117 This limits recursion for indirection when processing
119 entries in the magic file.
120 • "max_name"
122 This limits the maximum number of levels of name/use magic
124 that will be processed in the magic file.
125 • "max_elf_notes"
127 This limits the maximum number of ELF notes that will be
129 processed when determining a file's mime type.
130 • "max_elf_phnum"
132 This limits the maximum number of ELF program sections that
134 will be processed when determining a file's mime type.
135 • "max_elf_shnum"
137 This limits the maximum number of ELF sections that will be
139 processed when determining a file's mime type.
140 • "max_regex"
142 This limits the maximum size of regexes when processing
144 entries in the magic file.
145 • "max_bytes"
147 This limits the maximum number of bytes read from a file
149 when determining a file's mime type.
150 The values of these parameters should be integer limits.
152 • "max_future_compat"
154 For compatibility with future additions to the libmagic processing
156 limit parameters, you can pass a "max_future_compat" parameter.
157 This is a hash reference where the keys are constant values
158 (integers defined by libmagic, not names) and the values are the
159 limit you want to set.
160 $magic->info_from_filename('path/to/file')
162 This method returns info about the given file. The return value is a
163 hash reference with four keys:
164 • "description"
166 A textual description of the file content like "ASCII C program
168 text".
169 • "mime_type"
171 The MIME type without a character encoding, like "text/x-c".
173 • "encoding"
175 Just the character encoding, like "us-ascii".
177 • "mime_with_encoding"
179 The MIME type with a character encoding, like "text/x-c;
181 charset=us-ascii". Note that if no encoding was found, this will be
182 the same as the "mime_type" key.
183 $magic->info_from_string($string)
185 This method returns info about the contents of the given string. The
186 string can be passed as a reference to save memory.
187 The return value is the same as that of "$mime->info_from_filename".
189 $magic->info_from_handle($fh)
191 This method returns info about the contents read from the given
192 filehandle. It will read data starting from the handle's current
193 position, and leave the handle at that same position after reading.
194 File::LibMagic->max_param_constant
196 This method returns the maximum value that can be passed as a
197 processing limit parameter to the constructor. You can use this to
198 determine if passing a particular value in the "max_future_compat"
199 constructor parameter will work.
200 This may include constant values that do not have corresponding "max_X"
202 constructor keys if your version of libmagic is newer than the one used
203 to build this distribution.
204 Conversely, if your version is older than it's possible that not all of
206 the defined keys will be supported.
207 File::LibMagic->limit_key_is_supported($key)
209 This method takes a processing limit key like "max_indir" or "max_name"
210 and returns a boolean indicating whether the linked version of libmagic
211 supports that processing limit.
212
214 This module offers two different procedural APIs based on optional
215 exports, the "easy" and "complete" interfaces. There is also an older
216 OO API still available. All of these APIs are discouraged, but will not
217 be removed in the near future, nor will using them cause any warnings.
218 I strongly recommend you use the new OO API. It's simpler than the
220 complete interface, more efficient than the easy interface, and more
221 featureful than the old OO API.
222 The Old OO API
224 This API uses the same constructor as the current API.
225 • $magic->checktype_contents($data)
227 Returns the MIME type of the data given as the first argument. The
229 data can be passed as a plain scalar or as a reference to a scalar.
230 This is the same value as would be returned by the "file" command
232 with the "-i" switch.
233 • $magic->checktype_filename($filename)
235 Returns the MIME type of the given file.
237 This is the same value as would be returned by the "file" command
239 with the "-i" switch.
240 • $magic->describe_contents($data)
242 Returns a description (as a string) of the data given as the first
244 argument. The data can be passed as a plain scalar or as a
245 reference to a scalar.
246 This is the same value as would be returned by the "file" command
248 with no switches.
249 • $magic->describe_filename($filename)
251 Returns a description (as a string) of the given file.
253 This is the same value as would be returned by the "file" command
255 with no switches.
256 The "easy" interface
258 This interface is exported by:
259 use File::LibMagic ':easy';
261 This interface exports two subroutines:
263 • MagicBuffer($data)
265 Returns the description of a chunk of data, just like the
267 "describe_contents" method.
268 • MagicFile($filename)
270 Returns the description of a file, just like the
272 "describe_filename" method.
273 The "complete" interface
275 This interface is exported by:
276 use File::LibMagic ':complete';
278 This interface exports several subroutines:
280 • magic_open($flags)
282 This subroutine opens creates a magic handle. See the libmagic man
284 page for a description of all the flags. These are exported by the
285 ":complete" import.
286 my $handle = magic_open(MAGIC_MIME);
288 • magic_load($handle, $filename)
290 This subroutine actually loads the magic file. The $filename
292 argument is optional. There should be a sane default compiled into
293 your "libmagic" library.
294 • magic_buffer($handle, $data)
296 This returns information about a chunk of data as a string. What it
298 returns depends on the flags you passed to "magic_open", a
299 description, a MIME type, etc.
300 • magic_file($handle, $filename)
302 This returns information about a file as a string. What it returns
304 depends on the flags you passed to "magic_open", a description, a
305 MIME type, etc.
306 • magic_close($handle)
308 Closes the magic handle.
310
312 This module can throw an exception if your system runs out of memory
313 when trying to call "magic_open" internally.
314
316 This module is totally dependent on the version of file on your system.
317 It's possible that the tests will fail because of this. Please report
318 these failures so I can make the tests smarter. Please make sure to
319 report the version of file on your system as well!
320
322 This module requires file 4.x or file 5x and the associated libmagic
323 library and headers (https://darwinsys.com/file/).
324
326 Andreas created File::LibMagic because he wanted to use libmagic (from
327 file 4.x) File::MMagic only worked with file 3.x.
328 File::MimeInfo::Magic uses the magic file from freedesktop.org which is
330 encoded in XML, and is thus not the fastest approach. See
331 <https://mail.gnome.org/archives/nautilus-list/2003-December/msg00260.html>
332 for a discussion of this issue.
333 File::Type uses a relatively small magic file, which is directly hacked
335 into the module code. It is quite fast but the database is quite small
336 relative to the file package.
337
339 Please submit bugs to the CPAN RT system at
340 https://rt.cpan.org/Public/Dist/Display.html?Name=File-LibMagic or via
341 email at bug-file-libmagic@rt.cpan.org.
342 Bugs may be submitted at
344 <https://github.com/houseabsolute/File-LibMagic/issues>.
345 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
347
349 The source code repository for File-LibMagic can be found at
350 <https://github.com/houseabsolute/File-LibMagic>.
351
353 If you'd like to thank me for the work I've done on this module, please
354 consider making a "donation" to me via PayPal. I spend a lot of free
355 time creating free software, and would appreciate any support you'd
356 care to offer.
357 Please note that I am not suggesting that you must do this in order for
359 me to continue working on this particular software. I will continue to
360 do so, inasmuch as I have in the past, for as long as it interests me.
361 Similarly, a donation made in this way will probably not make me work
363 on this software much more, unless I get so many donations that I can
364 consider working on free software full time (let's all have a chuckle
365 at that together).
366 To donate, log into PayPal and send money to autarch@urth.org, or use
368 the button at <https://www.urth.org/fs-donation.html>.
369
371 • Andreas Fitzner
372 • Michael Hendricks <michael@ndrix.org>
374 • Dave Rolsky <autarch@urth.org>
376
378 • E. Choroba <choroba@matfyz.cz>
379 • Mithun Ayachit <mayachit@amfam.com>
381 • Olaf Alders <olaf@wundersolutions.com>
383 • Paul Wise <pabs3@bonedaddy.net>
385 • Tom Wyant <wyant@cpan.org>
387
389 This software is copyright (c) 2020 by Andreas Fitzner, Michael
390 Hendricks, Dave Rolsky, and Paul Wise.
391 This is free software; you can redistribute it and/or modify it under
393 the same terms as the Perl 5 programming language system itself.
394 The full text of the license can be found in the LICENSE file included
396 with this distribution.
397perl v5.36.0 2022-07-22 File::LibMagic(3)