usr/src/lib/libast/common/man/magic.3

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