|
Packit |
3652a6 |
# NAME
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
File::LibMagic - Determine MIME types of data or files using libmagic
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# VERSION
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
version 1.16
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# SYNOPSIS
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
use File::LibMagic;
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
my $magic = File::LibMagic->new();
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
my $info = $magic->info_from_filename('path/to/file');
|
|
Packit |
3652a6 |
# Prints a description like "ASCII text"
|
|
Packit |
3652a6 |
print $info->{description};
|
|
Packit |
3652a6 |
# Prints a MIME type like "text/plain"
|
|
Packit |
3652a6 |
print $info->{mime_type};
|
|
Packit |
3652a6 |
# Prints a character encoding like "us-ascii"
|
|
Packit |
3652a6 |
print $info->{encoding};
|
|
Packit |
3652a6 |
# Prints a MIME type with encoding like "text/plain; charset=us-ascii"
|
|
Packit |
3652a6 |
print $info->{mime_with_encoding};
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
my $file_content = read_file('path/to/file');
|
|
Packit |
3652a6 |
$info = $magic->info_from_string($file_content);
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
open my $fh, '<', 'path/to/file' or die $!;
|
|
Packit |
3652a6 |
$info = $magic->info_from_handle($fh);
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# DESCRIPTION
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
The `File::LibMagic` is a simple perl interface to libmagic from the file
|
|
Packit |
3652a6 |
package (version 4.x or 5.x). You will need both the library (`libmagic.so`)
|
|
Packit |
3652a6 |
and the header file (`magic.h`) to build this Perl module.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
## Installing libmagic
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
On Debian/Ubuntu run:
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
sudo apt-get install libmagic-dev
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
on Red Hat run:
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
sudo yum install file-devel
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
On Mac you can use homebrew (http://brew.sh/):
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
brew install libmagic
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
## Specifying lib and/or include directories
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
On some systems, you may need to pass additional lib and include directories
|
|
Packit |
3652a6 |
to the Makefile.PL. You can do this with the \`--lib\` and \`--include\`
|
|
Packit |
3652a6 |
parameters:
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
perl Makefile.PL --lib /usr/local/lib --include /usr/local/include
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
You can pass these parameters multiple times to specify more than one
|
|
Packit |
3652a6 |
location.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# API
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This module provides an object-oriented API with the following methods:
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
## File::LibMagic->new()
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Creates a new File::LibMagic object.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Using the object oriented interface only opens the magic database once, which
|
|
Packit |
3652a6 |
is probably most efficient for repeated uses.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Each `File::LibMagic` object loads the magic database independently of other
|
|
Packit |
3652a6 |
`File::LibMagic` objects, so you may want to share a single object across
|
|
Packit |
3652a6 |
many modules.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This method takes the following named parameters:
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- magic\_file
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This should be a string or an arrayref containing one or more magic files.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
If a file you provide doesn't exist the constructor will throw an exception,
|
|
Packit |
3652a6 |
but only with libmagic 4.17+.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
If you don't set this parameter, the constructor will throw an exception if it
|
|
Packit |
3652a6 |
can't find any magic files at all.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Note that even if you're using a custom file, you probably _also_ want to use
|
|
Packit |
3652a6 |
the standard file (`/usr/share/misc/magic` on my system, yours may vary).
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- follow\_symlinks
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
If this is true, then calls to `$magic->info_from_filename` will follow
|
|
Packit |
3652a6 |
symlinks to the real file.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- uncompress
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
If this is true, then compressed files (such as gzip files) will be
|
|
Packit |
3652a6 |
uncompressed, and the various `info_from_*` methods will return info
|
|
Packit |
3652a6 |
about the uncompressed file.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
## $magic->info\_from\_filename('path/to/file')
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This method returns info about the given file. The return value is a hash
|
|
Packit |
3652a6 |
reference with four keys:
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- description
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
A textual description of the file content like "ASCII C program text".
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- mime\_type
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
The MIME type without a character encoding, like "text/x-c".
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- encoding
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Just the character encoding, like "us-ascii".
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- mime\_with\_encoding
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
The MIME type with a character encoding, like "text/x-c;
|
|
Packit |
3652a6 |
charset=us-ascii". Note that if no encoding was found, this will be the same
|
|
Packit |
3652a6 |
as the `mime_type` key.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
## $magic->info\_from\_string($string)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This method returns info about the given string. The string can be passed as a
|
|
Packit |
3652a6 |
reference to save memory.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
The return value is the same as that of `$mime->info_from_filename()`.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
## $magic->info\_from\_handle($fh)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This method returns info about the given filehandle. It will read data
|
|
Packit |
3652a6 |
starting from the handle's current position, and leave the handle at that same
|
|
Packit |
3652a6 |
position after reading.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# DISCOURAGED APIS
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This module offers two different procedural APIs based on optional exports,
|
|
Packit |
3652a6 |
the "easy" and "complete" interfaces. There is also an older OO API still
|
|
Packit |
3652a6 |
available. All of these APIs are discouraged, but will not be removed in the
|
|
Packit |
3652a6 |
near future, nor will using them cause any warnings.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
I strongly recommend you use the new OO API. It's simpler than the complete
|
|
Packit |
3652a6 |
interface, more efficient than the easy interface, and more featureful than
|
|
Packit |
3652a6 |
the old OO API.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
## The Old OO API
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This API uses the same constructor as the current API.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- $magic->checktype\_contents($data)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Returns the MIME type of the data given as the first argument. The data can be
|
|
Packit |
3652a6 |
passed as a plain scalar or as a reference to a scalar.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This is the same value as would be returned by the `file` command with the
|
|
Packit |
3652a6 |
`-i` switch.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- $magic->checktype\_filename($filename)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Returns the MIME type of the given file.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This is the same value as would be returned by the `file` command with the
|
|
Packit |
3652a6 |
`-i` switch.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- $magic->describe\_contents($data)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Returns a description (as a string) of the data given as the first argument.
|
|
Packit |
3652a6 |
The data can be passed as a plain scalar or as a reference to a scalar.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This is the same value as would be returned by the `file` command with no
|
|
Packit |
3652a6 |
switches.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- $magic->describe\_filename($filename)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Returns a description (as a string) of the given file.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This is the same value as would be returned by the `file` command with no
|
|
Packit |
3652a6 |
switches.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
## The "easy" interface
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This interface is exported by:
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
use File::LibMagic ':easy';
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This interface exports two subroutines:
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- MagicBuffer($data)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Returns the description of a chunk of data, just like the `describe_contents`
|
|
Packit |
3652a6 |
method.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- MagicFile($filename)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Returns the description of a file, just like the `describe_filename` method.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
## The "complete" interface
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This interface is exported by:
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
use File::LibMagic ':complete';
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This interface exports several subroutines:
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- magic\_open($flags)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This subroutine opens creates a magic handle. See the libmagic man page for a
|
|
Packit |
3652a6 |
description of all the flags. These are exported by the `:complete` import.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
my $handle = magic_open(MAGIC_MIME);
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- magic\_load($handle, $filename)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This subroutine actually loads the magic file. The `$filename` argument is
|
|
Packit |
3652a6 |
optional. There should be a sane default compiled into your `libmagic`
|
|
Packit |
3652a6 |
library.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- magic\_buffer($handle, $data)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This returns information about a chunk of data as a string. What it returns
|
|
Packit |
3652a6 |
depends on the flags you passed to `magic_open`, a description, a MIME type,
|
|
Packit |
3652a6 |
etc.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- magic\_file($handle, $filename)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This returns information about a file as a string. What it returns depends on
|
|
Packit |
3652a6 |
the flags you passed to `magic_open`, a description, a MIME type, etc.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- magic\_close($handle)
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Closes the magic handle.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# EXCEPTIONS
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This module can throw an exception if your system runs out of memory when
|
|
Packit |
3652a6 |
trying to call `magic_open` internally.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# BUGS
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This module is totally dependent on the version of file on your system. It's
|
|
Packit |
3652a6 |
possible that the tests will fail because of this. Please report these
|
|
Packit |
3652a6 |
failures so I can make the tests smarter. Please make sure to report the
|
|
Packit |
3652a6 |
version of file on your system as well!
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# DEPENDENCIES/PREREQUISITES
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This module requires file 4.x or file 5x and the associated libmagic library
|
|
Packit |
3652a6 |
and headers (http://darwinsys.com/file/).
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# RELATED MODULES
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Andreas created File::LibMagic because he wanted to use libmagic (from
|
|
Packit |
3652a6 |
file 4.x) [File::MMagic](https://metacpan.org/pod/File::MMagic) only worked with file 3.x.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
[File::MimeInfo::Magic](https://metacpan.org/pod/File::MimeInfo::Magic) uses the magic file from freedesktop.org which is
|
|
Packit |
3652a6 |
encoded in XML, and is thus not the fastest approach. See
|
|
Packit |
3652a6 |
[http://mail.gnome.org/archives/nautilus-list/2003-December/msg00260.html](http://mail.gnome.org/archives/nautilus-list/2003-December/msg00260.html)
|
|
Packit |
3652a6 |
for a discussion of this issue.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
File::Type uses a relatively small magic file, which is directly hacked into
|
|
Packit |
3652a6 |
the module code. It is quite fast but the database is quite small relative to
|
|
Packit |
3652a6 |
the file package.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# SUPPORT
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Please submit bugs to the CPAN RT system at
|
|
Packit |
3652a6 |
http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-LibMagic or via email at
|
|
Packit |
3652a6 |
bug-file-libmagic@rt.cpan.org.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Bugs may be submitted at [http://rt.cpan.org/Public/Dist/Display.html?Name=File::LibMagic](http://rt.cpan.org/Public/Dist/Display.html?Name=File::LibMagic) or via email to [bug-file::libmagic@rt.cpan.org](mailto:bug-file::libmagic@rt.cpan.org).
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
I am also usually active on IRC as 'autarch' on `irc://irc.perl.org`.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# SOURCE
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
The source code repository for File-LibMagic can be found at [https://github.com/houseabsolute/File-LibMagic](https://github.com/houseabsolute/File-LibMagic).
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# DONATIONS
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
If you'd like to thank me for the work I've done on this module, please
|
|
Packit |
3652a6 |
consider making a "donation" to me via PayPal. I spend a lot of free time
|
|
Packit |
3652a6 |
creating free software, and would appreciate any support you'd care to offer.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Please note that **I am not suggesting that you must do this** in order for me
|
|
Packit |
3652a6 |
to continue working on this particular software. I will continue to do so,
|
|
Packit |
3652a6 |
inasmuch as I have in the past, for as long as it interests me.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
Similarly, a donation made in this way will probably not make me work on this
|
|
Packit |
3652a6 |
software much more, unless I get so many donations that I can consider working
|
|
Packit |
3652a6 |
on free software full time (let's all have a chuckle at that together).
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
To donate, log into PayPal and send money to autarch@urth.org, or use the
|
|
Packit |
3652a6 |
button at [http://www.urth.org/~autarch/fs-donation.html](http://www.urth.org/~autarch/fs-donation.html).
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# AUTHORS
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- Andreas Fitzner
|
|
Packit |
3652a6 |
- Michael Hendricks <michael@ndrix.org>
|
|
Packit |
3652a6 |
- Dave Rolsky <autarch@urth.org>
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# CONTRIBUTORS
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
- E. Choroba <choroba@matfyz.cz>
|
|
Packit |
3652a6 |
- Mithun Ayachit <mayachit@amfam.com>
|
|
Packit |
3652a6 |
- Olaf Alders <olaf@wundersolutions.com>
|
|
Packit |
3652a6 |
- Tom Wyant <wyant@cpan.org>
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
# COPYRIGHT AND LICENSE
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This software is copyright (c) 2017 by Andreas Fitzner, Michael Hendricks, and Dave Rolsky.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
This is free software; you can redistribute it and/or modify it under
|
|
Packit |
3652a6 |
the same terms as the Perl 5 programming language system itself.
|
|
Packit |
3652a6 |
|
|
Packit |
3652a6 |
The full text of the license can be found in the
|
|
Packit |
3652a6 |
`LICENSE` file included with this distribution.
|