NAME¶
File::LibMagic - Perlwrapper for libmagic (file-4.x or file-5.x)
SYNOPSIS¶
The easy way:
use File::LibMagic ':easy';
print MagicBuffer("Hello World\n"),"\n";
# returns "ASCII text"
print MagicFile("/bin/ls"),"\n";
# returns "ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV)"
# on my system
To use all capabilities of libmagic use
use File::LibMagic ':complete';
my $handle=magic_open(0);
my $ret =magic_load($handle,""); # use default magic file
# OR $ret =magic_load($handle, '/home/someone/.magic');
print magic_buffer($handle,"Hello World\n"),"\n";
print magic_file($handle,"/bin/ls"),"\n";
magic_close($handle);
Using the object-oriented interface:
use File::LibMagic;
my $flm = File::LibMagic->new();
# determine a content description
print $flm->describe_filename('path/to/file');
print $flm->describe_contents('this is some data');
# determine the MIME type
print $flm->checktype_filename('path/to/file');
print $flm->checktype_contents('this is some data');
Please have a look at the files in the example-directory.
ABSTRACT¶
The "File::LibMagic" is a simple perl interface to libmagic from the
file-4.x or file-5.x package from Christos Zoulas
(
ftp://ftp.astron.com/pub/file/).
DESCRIPTION¶
The "File::LibMagic" is a simple perlinterface to libmagic from the
file-4.x or file-5.x package from Christos Zoulas
(
ftp://ftp.astron.com/pub/file/).
You can use the simple Interface like
MagicBuffer() or
MagicFile(), use the functions of
libmagic(3) or use the
OO-Interface.
Simple Interface¶
MagicBuffer()
fixme
MagicFile()
fixme
magic_open, magic_close, magic_error, magic_file, magic_buffer, magic_setflags,
magic_check, magic_compile, magic_load -- Magic number recognition library
OO-Interface¶
new
Create a new File::LibMagic object to use for determining the type or MIME type
of content.
Using the object oriented interface provides an efficient way to repeatedly
determine the magic of a file. Using the object oriented interface provides
significant performance improvements over using the ":easy"
interface when testing many files. This performance improvement is because the
loading of the magic database happens only once, during object creation.
Each File::LibMagic object loads the magic database independently of other
File::LibMagic objects.
checktype_contents
Returns the MIME type of the data given as the first argument.
checktype_filename
Returns the MIME type of the given file. This will be the same as returned by
the "file -i" command.
describe_contents
Returns a description of the data given as the first argument.
describe_filename
Returns the MIME type of the given file. This will be the same as returned by
the "file" command.
EXPORT¶
None by default.
DIAGNOSTICS¶
MagicBuffer requires defined content¶
This exception is thrown if "MagicBuffer" is called with an undefined
argument.
libmagic cannot open %s¶
If libmagic is unable to open the file for which you want to determine the type,
this exception is thrown. The exception can be thrown by "MagicFile"
or "magic_file". '%s' contains details about why libmagic was unable
to open the file.
This exception is only thrown when using libmagic version 4.17 or later.
libmagic could not find any magic files¶
If libmagic is unable to find a suitable database of magic definitions, this
exception is thrown. The exception can be thrown by "MagicBuffer",
"MagicFile" or "magic_load".
With "magic_load", you can specify the location of the magic database
with the second argument. Depending on your libmagic implementation, you can
often set the MAGIC environment variable to tell libmagic where to find the
correct magic database.
libmagic out of memory¶
If libmagic is unable to allocate enough memory for its internal data
structures, this exception is thrown. The exception can be thrown by
"MagicBuffer", "MagicFile" or "magic_open".
magic_file requires a filename¶
If "magic_file" is called with an undefined second argument, this
exception is thrown.
BUGS¶
- "normalisation"-problem:
- The results from libmagic are dependend on the (linux)
distribution being used. A Gentoo-Linux might return "text/plain;
charset=us-asci", an OpenSUSE "text/plain charset=us-asci"
(no semicolon!). Please check this if you run your project on a different
platform (and send me an mail if you see different
outputs/return-values).
- I'm still learning perlxs ...
- still no real error handling (printf is not enough)
DEPENDENCIES/PREREQUISITES¶
This module requires these other modules and libraries:
o) file-4.x or file-5x and the associated libmagic
(ftp://ftp.astron.com/pub/file/)
o) on some systems zlib is required.
I created File::LibMagic because I wanted to use libmagic (from file-4.x) and
the otherwise great Module File::MMagic only works with file-3.x. In file-3.x
exists no libmagic but an ascii file (/etc/magic) in which all data (magic
numbers, etc.) is included. File::MMagic parsed this ascii file at each
request and is thus releativly slow. Also it can not use the new data from
file-4.x or file-5.x.
File::MimeInfo::Magic uses the magic file from freedesktop which is encoded
completely in XML, and thus not the fastest approach (
http://mail.gnome.org/archives/nautilus-list/2003-December/msg00260.html ).
File::Type uses a relativly small magic file, which is directly hacked into the
module code. Thus it is quite fast. It is also mod_perl save. It may be the
right choice for you, but the databasis is quite small relative to the
file-package.
HISTORY¶
April 2004 initial Release
April 2005 version 0.81
Thanks to James Olin Oden (joden@lee.k12.nc.us) for his help. Thanks to Nathan
Hawkins <utsl@quic.net> for his port to 64-bit systems.
June 2006 version 0.8x (x>1) Michael Hendricks started to put a lot of work
into File::LibMagic.
May 2009 latest relase.
AUTHOR¶
Andreas Fitzner <fitzner@informatik.hu-berlin.de>, Michael Hendricks
<michael@ndrix.org>
COPYRIGHT AND LICENSE¶
Copyright 200[5-9] by Andreas Fitzner, Michael Hendricks
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
