1.fp 5 CW 2.de Af 3.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2 4.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9" 5.. 6.de aF 7.ie \\$3 .ft \\$1 8.el \{\ 9.ds ;G \& 10.nr ;G \\n(.f 11.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9" 12\\*(;G 13.ft \\n(;G \} 14.. 15.de L 16.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" 17.. 18.de LR 19.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" 20.. 21.de RL 22.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" 23.. 24.de EX \" start example 25.ta 1i 2i 3i 4i 5i 6i 26.PP 27.RS 28.PD 0 29.ft 5 30.nf 31.. 32.de EE \" end example 33.fi 34.ft 35.PD 36.RE 37.PP 38.. 39.TH MAGIC 3 40.SH NAME 41magic \- magic file interface 42.SH SYNOPSIS 43.EX 44#include <magic.h> 45 46Magic_t 47{ 48 unsigned long flags; 49}; 50 51Magic_t* magicopen(unsigned long \fIflags\fP); 52void magicclose(Magic_t* \fImagic\fP); 53 54int magicload(Magic_t* \fImagic\fP, const char* \fIpath\fP, unsigned long \fIflags\fP); 55int magiclist(Magic_t* \fImagic\fP, Sfio_t* \fIsp\fP); 56 57char* magictype(Magic_t* \fImagic\fP, const char* \fIpath\fP, struct stat* \fIst\fP); 58.EE 59.SH DESCRIPTION 60These routines provide an interface to the 61.IR file (1) 62command magic file. 63.L magicopen 64returns a magic session handle that is passed to all of the other routines. 65.I flags 66may be 67.TP 68.L MAGIC_MIME 69Return the MIME type string rather than the magic file description. 70.TP 71.L MAGIC_PHYSICAL 72Don't follow symbolic links. 73.TP 74.L MAGIC_STAT 75The stat structure 76.I st 77passed to 78.I magictype 79will contain valid 80.I stat (2) 81information. 82See 83.L magictype 84below. 85.TP 86.L MAGIC_VERBOSE 87Enable verbose error messages. 88.PP 89.L magicclose 90closes the magic session. 91.PP 92.L magicload 93loads the magic file named by 94.I path 95into the magic session. 96.I flags 97are the same as with 98.LR magicopen . 99More than one magic file can be loaded into a session; 100the files are searched in load order. 101If 102.I path 103is 104.L 0 105then the default magic file is loaded. 106.PP 107.L magiclist 108lists the magic file contents on the 109.IR sfio (3) 110stream 111.IR sp . 112This is used for debugging magic entries. 113.PP 114.L magictype 115returns the type string for 116.I path 117with optional 118.IR stat (2) 119information 120.IR st . 121If 122.I "st == 0" 123then 124.L magictype 125calls 126.L stat 127on a private stat buffer, 128else if 129.L magicopen 130was called with the 131.L MAGIC_STAT 132flag then 133.I st 134is assumed to contain valid stat information, otherwise 135.L magictype 136calls 137.L stat 138on 139.IR st . 140.L magictype 141always returns a non-null string. 142If errors are encounterd on 143.I path 144then the return value will contain information on those errors, e.g., 145.LR "cannot stat" . 146.SH FORMAT 147The magic file format is a backwards compatible extension of an 148ancient System V file implementation. 149However, with the extended format it is possible to write a single 150magic file that works on all platforms. 151Most of the net magic files floating around work with 152.LR magic , 153but they usually double up on 154.I le 155and 156.I be 157entries that are automatically handled by 158.LR magic . 159.PP 160A magic file entry describes a procedure for determining a single file type 161based on the file pathname, 162.I stat (2) 163information, and the file data. 164An entry is a sequence of lines, each line being a record of 165.I space 166separated fields. 167The general record format is: 168.EX 169[op]offset type [mask]expression description [mimetype] 170.EE 171.L # 172in the first column introduces a comment. 173The first record in an entry contains no 174.LR op ; 175the remaining records for an entry contain an 176.LR op . 177Integer constants are as in C: 178.L 0x* 179or 180.L 0X* 181for hexadecimal, 182.L 0* 183for octal and decimal otherwise. 184.PP 185The 186.L op 187field may be one of: 188.TP 189.L + 190The previous records must match but the current record is optional. 191.L > 192is an old-style synonym for 193.LR + . 194.TP 195.L & 196The previous and current records must match. 197.TP 198.L { 199Starts a nesting block that is terminated by 200.LR } . 201A nesting block pushes a new context for the 202.L + 203and 204.L & 205ops. 206The 207.L { 208and 209.L } 210records have no other fields. 211.TP 212\fIid\f5{\fR 213A function declaration and call for the single character identifier 214.IR id . 215The function return is a nesting block end record 216.LR } . 217Function may be redefined. 218Functions have no arguments or return value. 219.TP 220\fIid\f5()\fR 221A call to the function 222.IR id . 223.PP 224The 225.L offset 226field is either the offset into the data upon which the current entry operates 227or a file metadata identifier. 228Offsets are either integer constants or offset expressions. 229An offset expression is contained in (...) and is a combination of 230integral arithmetic operators and the 231.L @ 232indirection operator. 233Indirections take the form 234.LI @ integer 235where integer is the data offset for the indirection value. 236The size of the indirection value is taken either from one of the suffixes 237.LR B (byte, 1 char), 238.LR H (short, 2 chars), 239.LR L (long, 4 chars), 240pr 241.LR Q (quead, 8 chars), 242or from the 243.L type 244field. 245Valid file metadata identifiers are: 246.TP 247.L atime 248The string representation of 249.LR stat.st_atime . 250.TP 251.L blocks 252.LR stat.st_blocks . 253.TP 254.L ctime 255The string representation of 256.LR stat.st_ctime . 257.TP 258.L fstype 259The string representation of 260.LR stat.st_fstype . 261.TP 262.L gid 263The string representation of 264.LR stat.st_gid . 265.TP 266The 267.L stat.st_mode 268file mode bits in 269.IR modecanon (3) 270canonical representation (i.e., the good old octal values). 271.TP 272.L mtime 273The string representation of 274.LR stat.st_mtime . 275.TP 276.L nlink 277.LR stat.st_nlink . 278.TP 279.L size 280.LR stat.st_size . 281.TP 282.L name 283The file path name sans directory. 284.TP 285.L uid 286The string representation of 287.LR stat.st_uid . 288.PP 289The 290.L type 291field specifies the type of the data at 292.LR offset . 293Integral types may be prefixed by 294.L le 295or 296.L be 297for specifying exact little-endian or big-endian representation, 298but the internal algorithm automatically loops through the 299standard representations to find integral matches, 300so representation prefixes are rarely used. 301However, this looping may cause some magic entry conflicts; use the 302.L le 303or 304.L be 305prefix in these cases. 306Only one representation is used for all the records in an entry. 307Valid types are: 308.TP 309.L byte 310A 1 byte integer. 311.TP 312.L short 313A 2 byte integer. 314.TP 315.L long 316A 4 byte integer. 317.TP 318.L quad 319An 8 byte integer. 320Tests on this type may fail is the local compiler does not support 321an 8 byte integral type and the corresponding value overflows 4 bytes. 322.TP 323.L date 324The data at 325.L offset 326is interpreted as a 4 byte seconds-since-the-epoch date and 327converted to a string. 328.TP 329.L edit 330The 331.L expression 332field is an 333.IR ed (1) 334style substitution expression 335\fIdel old del new del \fP [ \fI flags \fP ] 336where the substituted value is made available to the 337.L description 338field 339.L %s 340format. 341In addition to the 342.I flags 343supported by 344.IR ed (3) 345are 346.L l 347that converts the substituted value to lower case and 348.L u 349that converts the substituted value to upper case. 350If 351.I old 352does not match the string data at 353.L offset 354then the entry record fails. 355.TP 356.L match 357.L expression 358field is a 359.IR strmatch (3) 360pattern that is matched against the string data at 361.LR offset . 362.TP 363.L string 364The 365.L expression 366field is a string that is compared with the string data at 367.LR offset . 368.PP 369The optional 370.L mask 371field takes the form 372.LI & number 373where 374.I number 375is 376.I anded 377with the integral value at 378.L offset 379before the 380.L expression 381is applied. 382.PP 383The contents of the expression field depends on the 384.LR type . 385String type expression are described in the 386.L type 387field entries above. 388.L * 389means any value and applies to all types. 390Integral 391.L type 392expression take the form [\fIoperator\fP] \fIoperand\P where 393.I operand 394is compared with the data value at 395.L offset 396using 397.IR operator . 398.I operator 399may be one of 400.LR < . 401.LR <= , 402.LR == , 403.LR >= 404or 405.LR > . 406.I operator 407defaults to 408.L == 409if omitted. 410.I operand 411may be an integral constant or one of the following builtin function calls: 412.TP 413.L magic() 414A recursive call to the magic algorithm starting with the data at 415.LR offset . 416.TP 417\f5loop(\fIfunction\fP,\fIoffset\fP,\fIincrement\fP)\fR 418Call 419.I function 420starting at 421.I offset 422and increment 423.I offset 424by 425.I increment 426after each iteration. 427Iteration continues until the description text does not change. 428.PP 429The 430.L description 431field is the most important because it is this field that is presented 432to the outside world. 433When constructing description 434fields one must be very careful to follow the style layed out in the 435magic file, lest yet another layer of inconsistency creep into the system. 436The description for each matching record in an entry are concatenated 437to form the complete magic type. 438If the previous matching description in the current entry does not end with 439.I space 440and the current description is not empty and does not start with 441.I comma , 442.I dot 443or 444.I backspace 445then a 446.I space 447is placed between the descriptions 448(most optional descriptions start with 449.IR comma .) 450The data value at 451.L offset 452can be referenced in the description using 453.L %s 454for the string types and 455.L %ld 456or 457.L %lu 458for the integral types. 459.PP 460The 461.L mimetype 462field specifies the MIME type, usually in the form 463.IR a / b . 464.SH FILES 465.L ../lib/file/magic 466located on 467.L $PATH 468.SH EXAMPLES 469.EX 4700 long 0x020c0108 hp s200 executable, pure 471o{ 472+36 long >0 , not stripped 473+4 short >0 , version %ld 474} 475 4760 long 0x020c0107 hp s200 executable 477o() 478 4790 long 0x020c010b hp s200 executable, demand-load 480o() 481.EE 482The function 483.LR o() , 484shared by 3 entries, 485determines if the executable is stripped and also extracts the version number. 486.EX 4870 long 0407 bsd 386 executable 488&mode long &0111!=0 489+16 long >0 , not stripped 490.EE 491This entry requires that the file also has execute permission. 492.SH "SEE ALSO" 493file(1), mime(4), tw(1), modecanon(3) 494