Rand Stats



Actions Status

NAME Filetype::Magic

Try to guess a files type using the libmagic heuristic library.


Object oriented mode:

use Filetype::Magic;

my $magic = Magic.new;

say $magic.type: '/path/to/file.name';

Or use a convenience function.

Subroutine interface:

use Filetype::Magic;

say file-type '/path/to/file.name';


Provides a Raku interface to the libmagic shared library used by the 'file' utility to guess file types, installed by default on most BSDs and Linuxs. Libraries available for OSX and Windows as well.

Linux / BSD / OSX: Needs to have the shared library: libmagic-dev installed. May install the shared library directly or install the file-dev packages which will include the shared libmagic library file. Needs the header files so will need the dev packages even if you already have libmagic installed.

Windows: Needs libmagic.dll. Older 32bit packages are available on the authors site; the newest version available is 5.03. 64bit dlls can be built by following instructions on the nscaife github page (link below). At 5.29 by default, though it appears that it attempts to update to the latest version on build. (5.32 as of this writing.)

PlatformInstall Method
Debian derivatives[sudo] apt-get install libmagic-dev
FreeBSD[sudo] pkg install libmagic-dev
Fedora[sudo] dnf install libmagic-dev
OSX[sudo] brew install libmagic
OpenSUSE[sudo] zypper install libmagic-dev
Red Hat[sudo] yum install file-devel
Source Code on GitHubhttps://github.com/file/file
Windows 32bit (older)http://gnuwin32.sourceforge.net/packages/file.htm
Windows 64bit (newer)https://github.com/nscaife/file-windows


There is a series of flags which control the behavior of the search:

Flaghex valuemeaning
MAGIC_NONE0x000000,No flags
MAGIC_DEBUG0x000001,Turn on debugging
MAGIC_SYMLINK0x000002,Follow symlinks
MAGIC_COMPRESS0x000004,Check inside compressed files
MAGIC_DEVICES0x000008,Look at the contents of devices
MAGIC_MIME_TYPE0x000010,Return the MIME type
MAGIC_CONTINUE0x000020,Return all matches
MAGIC_CHECK0x000040,Print warnings to stderr
MAGIC_PRESERVE_ATIME0x000080,Restore access time on exit
MAGIC_RAW0x000100,Don't translate unprintable chars
MAGIC_ERROR0x000200,Handle ENOENT etc as real errors
MAGIC_MIME_ENCODING0x000400,Return the MIME encoding
MAGIC_APPLE0x000800,Return the Apple creator and type
MAGIC_NO_CHECK_COMPRESS0x001000,Don't check for compressed files
MAGIC_NO_CHECK_TAR0x002000,Don't check for tar files
MAGIC_NO_CHECK_SOFT0x004000,Don't check magic entries
MAGIC_NO_CHECK_APPTYPE0x008000,Don't check application
MAGIC_NO_CHECK_ELF0x010000,Don't check for elf details
MAGIC_NO_CHECK_TEXT0x020000,Don't check for text files
MAGIC_NO_CHECK_CDF0x040000,Don't check for cdf files
MAGIC_NO_CHECK_TOKENS0x100000,Don't check tokens
MAGIC_NO_CHECK_ENCODING0x200000,Don't check text encodings

The flags may be set during construction by passing a :flags(WHATEVER) value in to the .new( ) method, or may be adjusted later using the .set-flags( ) method.

FUNCTIONS - subroutine interface

Useful for one-and-done, one-off use.

sub file-type( IO::Path $path, Bool :$mime )
   # or
sub file-type( Str $filename, Bool :$mime )
   # or
sub file-type( IO::Handle $handle, Bool :$mime )
    # or
sub file-type( Buf $buffer, Bool :$mime )

Try to detect file type of a given file path/name, or open file handle, or string buffer. Strings must be in a specific encoding for the C library, so to avoid encoding issues and to differentiate string buffers from string filenames, you must pass strings as a Buf encoded appropriately. Pass a keyword parameter mime to get a mime type result.


METHODS - object interface

For when you would like a persistent instance.

method new  # Default database, default flags(none)
   # or
method new( :magicfile( '/path/to/magic/database.file' ) ) # Load a custom database
   # or
method new( :flags( MAGIC_SYMLINK +| MAGIC_MIME ) ) # Adjust search/reporting behavior

Construct a new Magic instance with passed parameters if desired.


method set-flags( int32 $flags = 0 )

Allows modification of parameters after initialization. Numeric-bitwise or any parameters together.

E.G. $magic-instance.set-flags( MAGIC_SYMLINK +| MAGIC_MIME ).


method get-flags( )

Query which flags are set, returns the int32 value of the set flags.


method type( IO::Path $path )
   # or
method type( Str $filename )
   # or
method type( IO::Handle $handle )
   # or
method type( Buf $buffer )

Try to detect file type of a given a file path/name, or open file handle, or string buffer. Strings must be in a specific encoding for the C library, so to avoid encoding issues and to differentiate string buffers from string filenames, you must pass strings as a Buf encoded appropriately.


method version()

Return the current version. First digit is major version number, rest are minor.

There are several semi-private methods which mostly deal with initialization and setup. There is nothing preventing you from accessing them, they are publically available, but most people won't ever need to use them.

method magic-database( str $magic-database, int32 $flags )

Location of the magic database file, pass Nil to load the default database. Pass any flags numeric-bitwise ored together to adjust behavior. (See method set-flags)


method magic-init( int32 $flags = 0 )

Initialize the file-magic instance, allocate a data structure to hold information and return a pointer to it. Pointer is stored in the class as $!magic-cookie.


method magic-load( Pointer $magic-struct, str $database-list )

Load the database file(s) into the data structure.


method magic-error()

Pass any errors back up to the calling code.


Once the Magic instance is initialized, you may query the database locations by checking the $magic-instance.database string. Contains the various file paths to loaded database files as a colon separated string. Do not try to change the database string directly. It will not affect the current instance; it is only a convenience method to make it easier to see the currently loaded files. Changes to the database need to be done with the magic-load( ) method.

A few methods dealing with generating, compiling, and checking magic database files have yet to be implemented.


2019 Steve Schulze aka thundergnat

This package is free software and is provided "as is" without express or implied warranty. You can redistribute it and/or modify it under the same terms as Perl itself.

libmagic library and file utility v5.x author: Ian Darwin, Christos Zoulas, et al.


github: gmoshkin


Licensed under The Artistic 2.0; see LICENSE.