Ubuntu Manpage: fileutil::magic::rt - Runtime core for file type recognition engines written in pure Tcl

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 engines 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 filename 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 ::fileutil::magic::rt::open and shuts the runtime
down. This command has to be invoked last, after the file has been dealt with completely.
Afterward another invokation of ::fileutil::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 special 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 special 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 absolute 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, except that it compares the fetched
and masked value against val as specified with comp and returns the result of that comparison.

The argument comp has to contain one of Tcl's comparison operators, and the comparison made will
be

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 output 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.

KEYWORDS

       file recognition, file type, file utilities, mime, type