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

	           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

fumagic 								1.0						 fileutil::magic::rt(3tcl)