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