magic(3) · carta

NAME

magic - magic file interface

SYNOPSIS

#include <magic.h>
Magic_t
{
	unsigned long	flags;
};
Magic_t*  magicopen(unsigned long flags);
void      magicclose(Magic_t* magic);
int       magicload(Magic_t* magic, const char* path, unsigned long flags);
int       magiclist(Magic_t* magic, Sfio_t* sp);
char*     magictype(Magic_t* magic, const char* path, struct stat* st);

DESCRIPTION

These routines provide an interface to the file(1) command magic file. $1$2magicopenmagicopenmagicopenmagicopenmagicopenmagicopenmagicopenmagicopen returns a magic session handle that is passed to all of the other routines. flags may be

$1$2MAGIC_MIMEMAGIC_MIMEMAGIC_MIMEMAGIC_MIMEMAGIC_MIMEMAGIC_MIMEMAGIC_MIMEMAGIC_MIME: Return the MIME type string rather than the magic file description.

$1$2MAGIC_PHYSICALMAGIC_PHYSICALMAGIC_PHYSICALMAGIC_PHYSICALMAGIC_PHYSICALMAGIC_PHYSICALMAGIC_PHYSICALMAGIC_PHYSICAL: Don't follow symbolic links.

$1$2MAGIC_STATMAGIC_STATMAGIC_STATMAGIC_STATMAGIC_STATMAGIC_STATMAGIC_STATMAGIC_STAT: The stat structure st passed to magictype will contain valid stat (2) information. See $1$2magictypemagictypemagictypemagictypemagictypemagictypemagictypemagictype below.

$1$2MAGIC_VERBOSEMAGIC_VERBOSEMAGIC_VERBOSEMAGIC_VERBOSEMAGIC_VERBOSEMAGIC_VERBOSEMAGIC_VERBOSEMAGIC_VERBOSE: Enable verbose error messages.

$1$2magicclosemagicclosemagicclosemagicclosemagicclosemagicclosemagicclosemagicclose closes the magic session.

$1$2magicloadmagicloadmagicloadmagicloadmagicloadmagicloadmagicloadmagicload loads the magic file named by path into the magic session. flags are the same as with $1$2magicopenmagicopenmagicopenmagicopenmagicopenmagicopenmagicopenmagicopen More than one magic file can be loaded into a session; the files are searched in load order. If path is $1$200000000 then the default magic file is loaded.

$1$2magiclistmagiclistmagiclistmagiclistmagiclistmagiclistmagiclistmagiclist lists the magic file contents on the sfio(3) stream sp. This is used for debugging magic entries.

$1$2magictypemagictypemagictypemagictypemagictypemagictypemagictypemagictype returns the type string for path with optional stat(2) information st. If st == 0 then $1$2magictypemagictypemagictypemagictypemagictypemagictypemagictypemagictype calls $1$2statstatstatstatstatstatstatstat on a private stat buffer, else if $1$2magicopenmagicopenmagicopenmagicopenmagicopenmagicopenmagicopenmagicopen was called with the $1$2MAGIC_STATMAGIC_STATMAGIC_STATMAGIC_STATMAGIC_STATMAGIC_STATMAGIC_STATMAGIC_STAT flag then st is assumed to contain valid stat information, otherwise $1$2magictypemagictypemagictypemagictypemagictypemagictypemagictypemagictype calls $1$2statstatstatstatstatstatstatstat on st. $1$2magictypemagictypemagictypemagictypemagictypemagictypemagictypemagictype always returns a non-null string. If errors are encounterd on path then the return value will contain information on those errors, e.g., $1$2cannot statcannot statcannot statcannot statcannot statcannot statcannot statcannot stat

FORMAT

The magic file format is a backwards compatible extension of an ancient System V file implementation. However, with the extended format it is possible to write a single magic file that works on all platforms. Most of the net magic files floating around work with $1$2magicmagicmagicmagicmagicmagicmagicmagic but they usually double up on le and be entries that are automatically handled by $1$2magicmagicmagicmagicmagicmagicmagicmagic

A magic file entry describes a procedure for determining a single file type based on the file pathname, stat (2) information, and the file data. An entry is a sequence of lines, each line being a record of space separated fields. The general record format is:

[op]offset type [mask]expression description [mimetype]

$1$2######## in the first column introduces a comment. The first record in an entry contains no $1$2opopopopopopopop the remaining records for an entry contain an $1$2opopopopopopopop Integer constants are as in C: $1$20x*0x*0x*0x*0x*0x*0x*0x* or $1$20X*0X*0X*0X*0X*0X*0X*0X* for hexadecimal, $1$20*0*0*0*0*0*0*0* for octal and decimal otherwise.

The $1$2opopopopopopopop field may be one of:

$1$2++++++++: The previous records must match but the current record is optional. $1$2>>>>>>>> is an old-style synonym for $1$2++++++++

$1$2&&&&&&&&: The previous and current records must match.

$1$2{{{{{{{{: Starts a nesting block that is terminated by $1$2}}}}}}}} A nesting block pushes a new context for the $1$2++++++++ and $1$2&&&&&&&& ops. The $1$2{{{{{{{{ and $1$2}}}}}}}} records have no other fields.

id{: A function declaration and call for the single character identifier id. The function return is a nesting block end record $1$2}}}}}}}} Function may be redefined. Functions have no arguments or return value.

id(): A call to the function id.

The $1$2offsetoffsetoffsetoffsetoffsetoffsetoffsetoffset field is either the offset into the data upon which the current entry operates or a file metadata identifier. Offsets are either integer constants or offset expressions. An offset expression is contained in (...) and is a combination of integral arithmetic operators and the $1$2@@@@@@@@ indirection operator. Indirections take the form where integer is the data offset for the indirection value. The size of the indirection value is taken either from one of the suffixes $1$2BBBBBBBB $1$2HHHHHHHH $1$2LLLLLLLL pr $1$2QQQQQQQQ or from the $1$2typetypetypetypetypetypetypetype field. Valid file metadata identifiers are:

$1$2atimeatimeatimeatimeatimeatimeatimeatime: The string representation of $1$2stat.st_atimestat.st_atimestat.st_atimestat.st_atimestat.st_atimestat.st_atimestat.st_atimestat.st_atime

$1$2blocksblocksblocksblocksblocksblocksblocksblocks: $1$2stat.st_blocksstat.st_blocksstat.st_blocksstat.st_blocksstat.st_blocksstat.st_blocksstat.st_blocksstat.st_blocks

$1$2ctimectimectimectimectimectimectimectime: The string representation of $1$2stat.st_ctimestat.st_ctimestat.st_ctimestat.st_ctimestat.st_ctimestat.st_ctimestat.st_ctimestat.st_ctime

$1$2fstypefstypefstypefstypefstypefstypefstypefstype: The string representation of $1$2stat.st_fstypestat.st_fstypestat.st_fstypestat.st_fstypestat.st_fstypestat.st_fstypestat.st_fstypestat.st_fstype

$1$2gidgidgidgidgidgidgidgid: The string representation of $1$2stat.st_gidstat.st_gidstat.st_gidstat.st_gidstat.st_gidstat.st_gidstat.st_gidstat.st_gid

The: $1$2stat.st_modestat.st_modestat.st_modestat.st_modestat.st_modestat.st_modestat.st_modestat.st_mode file mode bits in modecanon(3) canonical representation (i.e., the good old octal values).

$1$2mtimemtimemtimemtimemtimemtimemtimemtime: The string representation of $1$2stat.st_mtimestat.st_mtimestat.st_mtimestat.st_mtimestat.st_mtimestat.st_mtimestat.st_mtimestat.st_mtime

$1$2nlinknlinknlinknlinknlinknlinknlinknlink: $1$2stat.st_nlinkstat.st_nlinkstat.st_nlinkstat.st_nlinkstat.st_nlinkstat.st_nlinkstat.st_nlinkstat.st_nlink

$1$2sizesizesizesizesizesizesizesize: $1$2stat.st_sizestat.st_sizestat.st_sizestat.st_sizestat.st_sizestat.st_sizestat.st_sizestat.st_size

$1$2namenamenamenamenamenamenamename: The file path name sans directory.

$1$2uiduiduiduiduiduiduiduid: The string representation of $1$2stat.st_uidstat.st_uidstat.st_uidstat.st_uidstat.st_uidstat.st_uidstat.st_uidstat.st_uid

The $1$2typetypetypetypetypetypetypetype field specifies the type of the data at $1$2offsetoffsetoffsetoffsetoffsetoffsetoffsetoffset Integral types may be prefixed by $1$2lelelelelelelele or $1$2bebebebebebebebe for specifying exact little-endian or big-endian representation, but the internal algorithm automatically loops through the standard representations to find integral matches, so representation prefixes are rarely used. However, this looping may cause some magic entry conflicts; use the $1$2lelelelelelelele or $1$2bebebebebebebebe prefix in these cases. Only one representation is used for all the records in an entry. Valid types are:

$1$2bytebytebytebytebytebytebytebyte: A 1 byte integer.

$1$2shortshortshortshortshortshortshortshort: A 2 byte integer.

$1$2longlonglonglonglonglonglonglong: A 4 byte integer.

$1$2quadquadquadquadquadquadquadquad: An 8 byte integer. Tests on this type may fail is the local compiler does not support an 8 byte integral type and the corresponding value overflows 4 bytes.

$1$2datedatedatedatedatedatedatedate: The data at $1$2offsetoffsetoffsetoffsetoffsetoffsetoffsetoffset is interpreted as a 4 byte seconds-since-the-epoch date and converted to a string.

$1$2editediteditediteditediteditedit: The $1$2expressionexpressionexpressionexpressionexpressionexpressionexpressionexpression field is an ed(1) style substitution expression del old del new del [ flags ] where the substituted value is made available to the $1$2descriptiondescriptiondescriptiondescriptiondescriptiondescriptiondescriptiondescription field $1$2%s%s%s%s%s%s%s%s format. In addition to the flags supported by ed(3) are $1$2llllllll that converts the substituted value to lower case and $1$2uuuuuuuu that converts the substituted value to upper case. If old does not match the string data at $1$2offsetoffsetoffsetoffsetoffsetoffsetoffsetoffset then the entry record fails.

$1$2matchmatchmatchmatchmatchmatchmatchmatch: $1$2expressionexpressionexpressionexpressionexpressionexpressionexpressionexpression field is a strmatch(3) pattern that is matched against the string data at $1$2offsetoffsetoffsetoffsetoffsetoffsetoffsetoffset

$1$2stringstringstringstringstringstringstringstring: The $1$2expressionexpressionexpressionexpressionexpressionexpressionexpressionexpression field is a string that is compared with the string data at $1$2offsetoffsetoffsetoffsetoffsetoffsetoffsetoffset

The optional $1$2maskmaskmaskmaskmaskmaskmaskmask field takes the form where number is anded with the integral value at $1$2offsetoffsetoffsetoffsetoffsetoffsetoffsetoffset before the $1$2expressionexpressionexpressionexpressionexpressionexpressionexpressionexpression is applied.

The contents of the expression field depends on the $1$2typetypetypetypetypetypetypetype String type expression are described in the $1$2typetypetypetypetypetypetypetype field entries above. $1$2******** means any value and applies to all types. Integral $1$2typetypetypetypetypetypetypetype expression take the form [operator] operandP where operand is compared with the data value at $1$2offsetoffsetoffsetoffsetoffsetoffsetoffsetoffset using operator. operator may be one of $1$2<<<<<<<< $1$2<=<=<=<=<=<=<=<= $1$2================ $1$2>=>=>=>=>=>=>=>= or $1$2>>>>>>>> operator defaults to $1$2================ if omitted. operand may be an integral constant or one of the following builtin function calls:

$1$2magic()magic()magic()magic()magic()magic()magic()magic(): A recursive call to the magic algorithm starting with the data at $1$2offsetoffsetoffsetoffsetoffsetoffsetoffsetoffset

loop(function,offset,increment): Call function starting at offset and increment offset by increment after each iteration. Iteration continues until the description text does not change.

The $1$2descriptiondescriptiondescriptiondescriptiondescriptiondescriptiondescriptiondescription field is the most important because it is this field that is presented to the outside world. When constructing description fields one must be very careful to follow the style layed out in the magic file, lest yet another layer of inconsistency creep into the system. The description for each matching record in an entry are concatenated to form the complete magic type. If the previous matching description in the current entry does not end with space and the current description is not empty and does not start with comma , dot or backspace then a space is placed between the descriptions (most optional descriptions start with comma.) The data value at $1$2offsetoffsetoffsetoffsetoffsetoffsetoffsetoffset can be referenced in the description using $1$2%s%s%s%s%s%s%s%s for the string types and $1$2%ld%ld%ld%ld%ld%ld%ld%ld or $1$2%lu%lu%lu%lu%lu%lu%lu%lu for the integral types.

The $1$2mimetypemimetypemimetypemimetypemimetypemimetypemimetypemimetype field specifies the MIME type, usually in the form a/b.

FILES

$1$2../lib/file/magic../lib/file/magic../lib/file/magic../lib/file/magic../lib/file/magic../lib/file/magic../lib/file/magic../lib/file/magic located on $1$2$PATH$PATH$PATH$PATH$PATH$PATH$PATH$PATH

EXAMPLES

0	long		0x020c0108	hp s200 executable, pure
o{
+36	long		>0		, not stripped
+4	short		>0		, version %ld
}
0	long		0x020c0107	hp s200 executable
o()
0	long		0x020c010b	hp s200 executable, demand-load
o()

The function $1$2o()o()o()o()o()o()o()o() shared by 3 entries, determines if the executable is stripped and also extracts the version number.

0	long		0407		bsd 386 executable
&mode	long		&0111!=0
+16	long		>0		, not stripped