1File::LibMagic(3)     User Contributed Perl Documentation    File::LibMagic(3)
2
3
4

NAME

6       File::LibMagic - Determine MIME types of data or files using libmagic
7

VERSION

9       version 1.23
10

SYNOPSIS

12         use File::LibMagic;
13
14         my $magic = File::LibMagic->new;
15
16         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
26         my $file_content = read_file('path/to/file');
27         $info = $magic->info_from_string($file_content);
28
29         open my $fh, '<', 'path/to/file' or die $!;
30         $info = $magic->info_from_handle($fh);
31

DESCRIPTION

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
37   Installing libmagic
38       On Debian/Ubuntu run:
39
40           sudo apt-get install libmagic-dev
41
42       on Red Hat run:
43
44           sudo yum install file-devel
45
46       On Mac you can use homebrew (https://brew.sh/):
47
48           brew install libmagic
49
50   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
55           perl Makefile.PL --lib /usr/local/lib --include /usr/local/include
56
57       You can pass these parameters multiple times to specify more than one
58       location.
59

API

61       This module provides an object-oriented API with the following methods:
62
63   File::LibMagic->new
64       Creates a new File::LibMagic object.
65
66       Using the object oriented interface only opens the magic database once,
67       which is probably most efficient for repeated uses.
68
69       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
73       This method takes the following named parameters:
74
75       •   "magic_file"
76
77           This should be a string or an arrayref containing one or more magic
78           files.
79
80           If a file you provide doesn't exist the constructor will throw an
81           exception, but only with libmagic 4.17+.
82
83           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
86           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
90       •   "follow_symlinks"
91
92           If this is true, then calls to "$magic->info_from_filename" will
93           follow symlinks to the real file.
94
95       •   "uncompress"
96
97           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
101       •   Processing limits
102
103           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
107           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
116           •       "max_indir"
117
118                   This limits recursion for indirection when processing
119                   entries in the magic file.
120
121           •       "max_name"
122
123                   This limits the maximum number of levels of name/use magic
124                   that will be processed in the magic file.
125
126           •       "max_elf_notes"
127
128                   This limits the maximum number of ELF notes that will be
129                   processed when determining a file's mime type.
130
131           •       "max_elf_phnum"
132
133                   This limits the maximum number of ELF program sections that
134                   will be processed when determining a file's mime type.
135
136           •       "max_elf_shnum"
137
138                   This limits the maximum number of ELF sections that will be
139                   processed when determining a file's mime type.
140
141           •       "max_regex"
142
143                   This limits the maximum size of regexes when processing
144                   entries in the magic file.
145
146           •       "max_bytes"
147
148                   This limits the maximum number of bytes read from a file
149                   when determining a file's mime type.
150
151           The values of these parameters should be integer limits.
152
153       •   "max_future_compat"
154
155           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
161   $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
165       •   "description"
166
167           A textual description of the file content like "ASCII C program
168           text".
169
170       •   "mime_type"
171
172           The MIME type without a character encoding, like "text/x-c".
173
174       •   "encoding"
175
176           Just the character encoding, like "us-ascii".
177
178       •   "mime_with_encoding"
179
180           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
184   $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
188       The return value is the same as that of "$mime->info_from_filename".
189
190   $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
195   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
201       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
205       Conversely, if your version is older than it's possible that not all of
206       the defined keys will be supported.
207
208   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

DISCOURAGED APIS

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
219       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
223   The Old OO API
224       This API uses the same constructor as the current API.
225
226       •   $magic->checktype_contents($data)
227
228           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
231           This is the same value as would be returned by the "file" command
232           with the "-i" switch.
233
234       •   $magic->checktype_filename($filename)
235
236           Returns the MIME type of the given file.
237
238           This is the same value as would be returned by the "file" command
239           with the "-i" switch.
240
241       •   $magic->describe_contents($data)
242
243           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
247           This is the same value as would be returned by the "file" command
248           with no switches.
249
250       •   $magic->describe_filename($filename)
251
252           Returns a description (as a string) of the given file.
253
254           This is the same value as would be returned by the "file" command
255           with no switches.
256
257   The "easy" interface
258       This interface is exported by:
259
260         use File::LibMagic ':easy';
261
262       This interface exports two subroutines:
263
264       •   MagicBuffer($data)
265
266           Returns the description of a chunk of data, just like the
267           "describe_contents" method.
268
269       •   MagicFile($filename)
270
271           Returns the description of a file, just like the
272           "describe_filename" method.
273
274   The "complete" interface
275       This interface is exported by:
276
277         use File::LibMagic ':complete';
278
279       This interface exports several subroutines:
280
281       •   magic_open($flags)
282
283           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
287             my $handle = magic_open(MAGIC_MIME);
288
289       •   magic_load($handle, $filename)
290
291           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
295       •   magic_buffer($handle, $data)
296
297           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
301       •   magic_file($handle, $filename)
302
303           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
307       •   magic_close($handle)
308
309           Closes the magic handle.
310

EXCEPTIONS

312       This module can throw an exception if your system runs out of memory
313       when trying to call "magic_open" internally.
314

BUGS

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

DEPENDENCIES/PREREQUISITES

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
329       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
334       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

SUPPORT

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
343       Bugs may be submitted at
344       <https://github.com/houseabsolute/File-LibMagic/issues>.
345
346       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
347

SOURCE

349       The source code repository for File-LibMagic can be found at
350       <https://github.com/houseabsolute/File-LibMagic>.
351

DONATIONS

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
358       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
362       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
367       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

AUTHORS

371       •   Andreas Fitzner
372
373       •   Michael Hendricks <michael@ndrix.org>
374
375       •   Dave Rolsky <autarch@urth.org>
376

CONTRIBUTORS

378       •   E. Choroba <choroba@matfyz.cz>
379
380       •   Mithun Ayachit <mayachit@amfam.com>
381
382       •   Olaf Alders <olaf@wundersolutions.com>
383
384       •   Paul Wise <pabs3@bonedaddy.net>
385
386       •   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
392       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
395       The full text of the license can be found in the LICENSE file included
396       with this distribution.
397
398
399
400perl v5.38.0                      2023-07-20                 File::LibMagic(3)
Impressum