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.16
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" is a simple perl interface to libmagic from the
34 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 (http://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 $magic->info_from_filename('path/to/file')
102 This method returns info about the given file. The return value is a
103 hash reference with four keys:
104 · description
106 A textual description of the file content like "ASCII C program
108 text".
109 · mime_type
111 The MIME type without a character encoding, like "text/x-c".
113 · encoding
115 Just the character encoding, like "us-ascii".
117 · mime_with_encoding
119 The MIME type with a character encoding, like "text/x-c;
121 charset=us-ascii". Note that if no encoding was found, this will be
122 the same as the "mime_type" key.
123 $magic->info_from_string($string)
125 This method returns info about the given string. The string can be
126 passed as a reference to save memory.
127 The return value is the same as that of "$mime->info_from_filename()".
129 $magic->info_from_handle($fh)
131 This method returns info about the given filehandle. It will read data
132 starting from the handle's current position, and leave the handle at
133 that same position after reading.
134
136 This module offers two different procedural APIs based on optional
137 exports, the "easy" and "complete" interfaces. There is also an older
138 OO API still available. All of these APIs are discouraged, but will not
139 be removed in the near future, nor will using them cause any warnings.
140 I strongly recommend you use the new OO API. It's simpler than the
142 complete interface, more efficient than the easy interface, and more
143 featureful than the old OO API.
144 The Old OO API
146 This API uses the same constructor as the current API.
147 · $magic->checktype_contents($data)
149 Returns the MIME type of the data given as the first argument. The
151 data can be passed as a plain scalar or as a reference to a scalar.
152 This is the same value as would be returned by the "file" command
154 with the "-i" switch.
155 · $magic->checktype_filename($filename)
157 Returns the MIME type of the given file.
159 This is the same value as would be returned by the "file" command
161 with the "-i" switch.
162 · $magic->describe_contents($data)
164 Returns a description (as a string) of the data given as the first
166 argument. The data can be passed as a plain scalar or as a
167 reference to a scalar.
168 This is the same value as would be returned by the "file" command
170 with no switches.
171 · $magic->describe_filename($filename)
173 Returns a description (as a string) of the given file.
175 This is the same value as would be returned by the "file" command
177 with no switches.
178 The "easy" interface
180 This interface is exported by:
181 use File::LibMagic ':easy';
183 This interface exports two subroutines:
185 · MagicBuffer($data)
187 Returns the description of a chunk of data, just like the
189 "describe_contents" method.
190 · MagicFile($filename)
192 Returns the description of a file, just like the
194 "describe_filename" method.
195 The "complete" interface
197 This interface is exported by:
198 use File::LibMagic ':complete';
200 This interface exports several subroutines:
202 · magic_open($flags)
204 This subroutine opens creates a magic handle. See the libmagic man
206 page for a description of all the flags. These are exported by the
207 ":complete" import.
208 my $handle = magic_open(MAGIC_MIME);
210 · magic_load($handle, $filename)
212 This subroutine actually loads the magic file. The $filename
214 argument is optional. There should be a sane default compiled into
215 your "libmagic" library.
216 · magic_buffer($handle, $data)
218 This returns information about a chunk of data as a string. What it
220 returns depends on the flags you passed to "magic_open", a
221 description, a MIME type, etc.
222 · magic_file($handle, $filename)
224 This returns information about a file as a string. What it returns
226 depends on the flags you passed to "magic_open", a description, a
227 MIME type, etc.
228 · magic_close($handle)
230 Closes the magic handle.
232
234 This module can throw an exception if your system runs out of memory
235 when trying to call "magic_open" internally.
236
238 This module is totally dependent on the version of file on your system.
239 It's possible that the tests will fail because of this. Please report
240 these failures so I can make the tests smarter. Please make sure to
241 report the version of file on your system as well!
242
244 This module requires file 4.x or file 5x and the associated libmagic
245 library and headers (http://darwinsys.com/file/).
246
248 Andreas created File::LibMagic because he wanted to use libmagic (from
249 file 4.x) File::MMagic only worked with file 3.x.
250 File::MimeInfo::Magic uses the magic file from freedesktop.org which is
252 encoded in XML, and is thus not the fastest approach. See
253 <http://mail.gnome.org/archives/nautilus-list/2003-December/msg00260.html>
254 for a discussion of this issue.
255 File::Type uses a relatively small magic file, which is directly hacked
257 into the module code. It is quite fast but the database is quite small
258 relative to the file package.
259
261 Please submit bugs to the CPAN RT system at
262 http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-LibMagic or via email at
263 bug-file-libmagic@rt.cpan.org.
264 Bugs may be submitted at
266 <http://rt.cpan.org/Public/Dist/Display.html?Name=File::LibMagic> or
267 via email to bug-file::libmagic@rt.cpan.org <mailto:bug-
268 file::libmagic@rt.cpan.org>.
269 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
271
273 The source code repository for File-LibMagic can be found at
274 <https://github.com/houseabsolute/File-LibMagic>.
275
277 If you'd like to thank me for the work I've done on this module, please
278 consider making a "donation" to me via PayPal. I spend a lot of free
279 time creating free software, and would appreciate any support you'd
280 care to offer.
281 Please note that I am not suggesting that you must do this in order for
283 me to continue working on this particular software. I will continue to
284 do so, inasmuch as I have in the past, for as long as it interests me.
285 Similarly, a donation made in this way will probably not make me work
287 on this software much more, unless I get so many donations that I can
288 consider working on free software full time (let's all have a chuckle
289 at that together).
290 To donate, log into PayPal and send money to autarch@urth.org, or use
292 the button at <http://www.urth.org/~autarch/fs-donation.html>.
293
295 · Andreas Fitzner
296 · Michael Hendricks <michael@ndrix.org>
298 · Dave Rolsky <autarch@urth.org>
300
302 · E. Choroba <choroba@matfyz.cz>
303 · Mithun Ayachit <mayachit@amfam.com>
305 · Olaf Alders <olaf@wundersolutions.com>
307 · Tom Wyant <wyant@cpan.org>
309
311 This software is copyright (c) 2017 by Andreas Fitzner, Michael
312 Hendricks, and Dave Rolsky.
313 This is free software; you can redistribute it and/or modify it under
315 the same terms as the Perl 5 programming language system itself.
316 The full text of the license can be found in the LICENSE file included
318 with this distribution.
319perl v5.28.0 2017-10-22 File::LibMagic(3)