fileutil::magic::rt(3tcl) file utilities fileutil::magic::rt(3tcl)
______________________________________________________________________________
NAME
fileutil::magic::rt - Runtime core for file type recognition engines
written in pure Tcl
SYNOPSIS
package require Tcl 8.5
package require fileutil::magic::rt ?2.0?
::fileutil::magic::rt::>
::fileutil::magic::rt::<
::fileutil::magic::rt::open filename
::fileutil::magic::rt::close
::fileutil::magic::rt::file_start name
::fileutil::magic::rt::result ?msg?
::fileutil::magic::rt::resultv ?msg?
::fileutil::magic::rt::emit msg
::fileutil::magic::rt::offset where
::fileutil::magic::rt::Nv type offset ?qual?
::fileutil::magic::rt::N type offset comp val ?qual?
::fileutil::magic::rt::Nvx type offset ?qual?
::fileutil::magic::rt::Nx type offset comp val ?qual?
::fileutil::magic::rt::S offset comp val ?qual?
::fileutil::magic::rt::Sx offset comp val ?qual?
::fileutil::magic::rt::L newlevel
::fileutil::magic::rt::I base type delta
::fileutil::magic::rt::R offset
::fileutil::magic::rt::U fileindex name
______________________________________________________________________________
DESCRIPTION
This package provides the runtime core for file type recognition en-
gines written in pure Tcl and is thus used by all other packages in
this module, i.e. the two frontend packages fileutil::magic::mimetypes
and fileutil::magic::filetypes, and the two engine compiler packages
fileutil::magic::cgen and fileutil::magic::cfront.
COMMANDS
::fileutil::magic::rt::>
Shorthand for incr level.
::fileutil::magic::rt::<
Shorthand for incr level -1.
::fileutil::magic::rt::open filename
This command initializes the runtime and prepares the file file-
name for use by the system. This command has to be invoked
first, before any other command of this package.
The command returns the channel handle of the opened file as its
result.
::fileutil::magic::rt::close
This command closes the last file opened via ::fileu-
til::magic::rt::open and shuts the runtime down. This command
has to be invoked last, after the file has been dealt with com-
pletely. Afterward another invokation of ::fileu-
til::magic::rt::open is required to process another file.
This command returns the empty string as its result.
::fileutil::magic::rt::file_start name
This command marks the start of a magic file when debugging. It
returns the empty string as its result.
::fileutil::magic::rt::result ?msg?
This command returns the current result and stops processing.
If msg is specified its text is added to the result before it is
returned. See ::fileutil::magic::rt::emit for the allowed spe-
cial character sequences.
::fileutil::magic::rt::resultv ?msg?
This command returns the current result. In contrast to
::fileutil::magic::rt::result processing continues.
If msg is specified its text is added to the result before it is
returned. See ::fileutil::magic::rt::emit for the allowed spe-
cial character sequences.
::fileutil::magic::rt::emit msg
This command adds the text msg to the result buffer. The message
may contain the following special character sequences. They will
be replaced with buffered values before the message is added to
the result. The command returns the empty string as its result.
\b This sequence is removed
%s Replaced with the last buffered string value.
%ld Replaced with the last buffered numeric value.
%d See above.
::fileutil::magic::rt::Nv type offset ?qual?
This command fetches the numeric value with type from the abso-
lute location offset and returns it as its result. The fetched
value is further stored in the numeric buffer.
If qual is specified it is considered to be a mask and applied
to the fetched value before it is stored and returned. It has to
have the form of a partial Tcl bit-wise expression, i.e.
& number
For example:
Nv lelong 0 &0x8080ffff
For the possible types see section NUMERIC TYPES.
::fileutil::magic::rt::N type offset comp val ?qual?
This command behaves mostly like ::fileutil::magic::rt::Nv, ex-
cept that it compares the fetched and masked value against val
as specified with comp and returns the result of that compari-
son.
The argument comp has to contain one of Tcl's comparison opera-
tors, and the comparison made will be
<val> <comp> <fetched-and-masked-value>
The special comparison operator x signals that no comparison should be
done, or, in other words, that the fetched value will always match val.
::fileutil::magic::rt::Nvx type offset ?qual?
This command behaves like ::fileutil::magic::rt::Nv, except that
it additionally remembers the location in the file after the
fetch in the calling context, for the current level, for later
use by ::fileutil::magic::rt::R.
::fileutil::magic::rt::Nx type offset comp val ?qual?
This command behaves like ::fileutil::magic::rt::N, except that
it additionally remembers the location in the file after the
fetch in the calling context, for the current, for later use by
::fileutil::magic::rt::R.
::fileutil::magic::rt::S offset comp val ?qual?
This command behaves like ::fileutil::magic::rt::N, except that
it fetches and compares strings, not numeric data. The fetched
value is also stored in the internal string buffer instead of
the numeric buffer.
::fileutil::magic::rt::Sx offset comp val ?qual?
This command behaves like ::fileutil::magic::rt::S, except that
it additionally remembers the location in the file after the
fetch in the calling context, for the current level, for later
use by ::fileutil::magic::rt::R.
::fileutil::magic::rt::L newlevel
This command sets the current level in the calling context to
newlevel. The command returns the empty string as its result.
::fileutil::magic::rt::I base type delta
This command handles base locations specified indirectly through
the contents of the inspected file. It returns the sum of delta
and the value of numeric type fetched from the absolute location
base.
For the possible types see section NUMERIC TYPES.
::fileutil::magic::rt::R offset
This command handles base locations specified relative to the
end of the last field one level above.
In other words, the command computes an absolute location in the
file based on the relative offset and returns it as its result.
The base the offset is added to is the last location remembered
for the level in the calling context.
::fileutil::magic::rt::U fileindex name
Use a named test script at the current level.
NUMERIC TYPES
byte 8-bit integer
short 16-bit integer, stored in native endianess
beshort
see above, stored in big endian
leshort
see above, stored in small/little endian
long 32-bit integer, stored in native endianess
belong see above, stored in big endian
lelong see above, stored in small/little endian
All of the types above exit in an unsigned form as well. The type names
are the same, with the character "u" added as prefix.
date 32-bit integer timestamp, stored in native endianess
bedate see above, stored in big endian
ledate see above, stored in small/little endian
ldate 32-bit integer timestamp, stored in native endianess
beldate
see above, stored in big endian
leldate
see above, stored in small/little endian
BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain
bugs and other problems. Please report such in the category fileutil
:: magic of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].
Please also report any ideas for enhancements you may have for either
package and/or documentation.
When proposing code changes, please provide unified diffs, i.e the out-
put of diff -u.
Note further that attachments are strongly preferred over inlined
patches. Attachments can be made by going to the Edit form of the
ticket immediately after its creation, and then using the left-most
button in the secondary navigation bar.
SEE ALSO
file(1), fileutil, magic(5)
KEYWORDS
file recognition, file type, file utilities, mime, type
CATEGORY
Programming tools
tcllib 2.0 fileutil::magic::rt(3tcl)