Provided by: tcllib_1.15-dfsg-2_all bug

NAME

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

SYNOPSIS

       package require Tcl  8.4

       package require fileutil::magic::rt  ?1.0?

       ::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 atlevel type offset ?qual?

       ::fileutil::magic::rt::Nx atlevel type offset comp val ?qual?

       ::fileutil::magic::rt::S offset comp val ?qual?

       ::fileutil::magic::rt::Sx atlevel offset comp val ?qual?

       ::fileutil::magic::rt::L newlevel

       ::fileutil::magic::rt::I base type delta

       ::fileutil::magic::rt::R offset

_________________________________________________________________

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::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
              <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 atlevel 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
              level atlevel, for later use by ::fileutil::magic::rt::R.

       ::fileutil::magic::rt::Nx atlevel 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
              level atlevel, 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 atlevel 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
              level atlevel, 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.

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 SF  Trackers
       [http://sourceforge.net/tracker/?group_id=12883].    Please  also  report  any  ideas  for
       enhancements you may have for either package and/or documentation.

SEE ALSO

       file(1), fileutil, magic(5)

KEYWORDS

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

CATEGORY

       Programming tools