1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin fileutil::magic::rt n 1.0]
[see_also file(1)]
[see_also fileutil]
[see_also magic(5)]
[keywords {file recognition}]
[keywords {file type}]
[keywords {file utilities}]
[keywords mime]
[keywords type]
[moddesc {file utilities}]
[titledesc {Runtime core for file type recognition engines written in pure Tcl}]
[category {Programming tools}]
[require Tcl 8.4]
[require fileutil::magic::rt [opt 1.0]]
[description]
[para]
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
[package fileutil::magic::mimetypes] and
[package fileutil::magic::filetypes], and the two engine compiler
packages [package fileutil::magic::cgen] and
[package fileutil::magic::cfront].
[section COMMANDS]
[list_begin definitions]
[call [cmd ::fileutil::magic::rt::open] [arg filename]]
This command initializes the runtime and prepares the file
[arg filename] for use by the system.
This command has to be invoked first, before any other command of this
package.
[para]
The command returns the channel handle of the opened file as its
result.
[call [cmd ::fileutil::magic::rt::close]]
This command closes the last file opened via
[cmd ::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 [cmd ::fileutil::magic::rt::open] is
required to process another file.
[para]
This command returns the empty string as its result.
[call [cmd ::fileutil::magic::rt::file_start] [arg name]]
This command marks the start of a magic file when debugging. It
returns the empty string as its result.
[call [cmd ::fileutil::magic::rt::result] [opt [arg msg]]]
This command returns the current result and stops processing.
[para]
If [arg msg] is specified its text is added to the result before it is
returned. See [cmd ::fileutil::magic::rt::emit] for the allowed
special character sequences.
[call [cmd ::fileutil::magic::rt::resultv] [opt [arg msg]]]
This command returns the current result.
In contrast to [cmd ::fileutil::magic::rt::result] processing
continues.
[para]
If [arg msg] is specified its text is added to the result before it is
returned. See [cmd ::fileutil::magic::rt::emit] for the allowed
special character sequences.
[call [cmd ::fileutil::magic::rt::emit] [arg msg]]
This command adds the text [arg 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.
[list_begin definitions]
[def [const \\b]] This sequence is removed
[def [const %s]] Replaced with the last buffered string value.
[def [const %ld]] Replaced with the last buffered numeric value.
[def [const %d]] See above.
[list_end]
[comment [call [cmd ::fileutil::magic::rt::offset] [arg where]]]
[comment {
Handling of complex offsets. Currently not implemented.
Always returns zero.
}]
[call [cmd ::fileutil::magic::rt::Nv] [arg type] [arg offset] [opt [arg qual]]]
This command fetches the numeric value with [arg type] from the
absolute location [arg offset] and returns it as its result. The
fetched value is further stored in the numeric buffer.
[para]
If [arg 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.
[example {
& number
}]
For example:
[example {
Nv lelong 0 &0x8080ffff
}]
For the possible types see section [sectref {NUMERIC TYPES}].
[call [cmd ::fileutil::magic::rt::N] [arg type] [arg offset] [arg comp] [arg val] [opt [arg qual]]]
This command behaves mostly like [cmd ::fileutil::magic::rt::Nv],
except that it compares the fetched and masked value against [arg val]
as specified with [arg comp] and returns the result of that
comparison.
[para]
The argument [arg comp] has to contain one of Tcl's comparison
operators, and the comparison made will be
[example {
<val> <comp> <fetched-and-masked-value>
}]
[para]
The special comparison operator [const x] signals that no comparison
should be done, or, in other words, that the fetched value will always
match [arg val].
[call [cmd ::fileutil::magic::rt::Nvx] [arg atlevel] [arg type] [arg offset] [opt [arg qual]]]
This command behaves like [cmd ::fileutil::magic::rt::Nv], except that
it additionally remembers the location in the file after the fetch in
the calling context, for the level [arg atlevel], for later use by
[cmd ::fileutil::magic::rt::R].
[call [cmd ::fileutil::magic::rt::Nx] [arg atlevel] [arg type] [arg offset] [arg comp] [arg val] [opt [arg qual]]]
This command behaves like [cmd ::fileutil::magic::rt::N], except that
it additionally remembers the location in the file after the fetch in
the calling context, for the level [arg atlevel], for later use by
[cmd ::fileutil::magic::rt::R].
[call [cmd ::fileutil::magic::rt::S] [arg offset] [arg comp] [arg val] [opt [arg qual]]]
This command behaves like [cmd ::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.
[call [cmd ::fileutil::magic::rt::Sx] [arg atlevel] [arg offset] [arg comp] [arg val] [opt [arg qual]]]
This command behaves like [cmd ::fileutil::magic::rt::S], except that
it additionally remembers the location in the file after the fetch in
the calling context, for the level [arg atlevel], for later use by
[cmd ::fileutil::magic::rt::R].
[call [cmd ::fileutil::magic::rt::L] [arg newlevel]]
This command sets the current level in the calling context to
[arg newlevel]. The command returns the empty string as its result.
[call [cmd ::fileutil::magic::rt::I] [arg base] [arg type] [arg delta]]
This command handles base locations specified indirectly through the
contents of the inspected file. It returns the sum of [arg delta] and
the value of numeric [arg type] fetched from the absolute location
[arg base].
[para]
For the possible types see section [sectref {NUMERIC TYPES}].
[call [cmd ::fileutil::magic::rt::R] [arg offset]]
This command handles base locations specified relative to the end of
the last field one level above.
[para]
In other words, the command computes an absolute location in the file
based on the relative [arg 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.
[list_end]
[section {NUMERIC TYPES}]
[list_begin definitions]
[def [const byte]] 8-bit integer
[def [const short]] 16-bit integer, stored in native endianess
[def [const beshort]] see above, stored in big endian
[def [const leshort]] see above, stored in small/little endian
[def [const long]] 32-bit integer, stored in native endianess
[def [const belong]] see above, stored in big endian
[def [const lelong]] see above, stored in small/little endian
[list_end]
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.
[list_begin definitions]
[def [const date]] 32-bit integer timestamp, stored in native endianess
[def [const bedate]] see above, stored in big endian
[def [const ledate]] see above, stored in small/little endian
[def [const ldate]] 32-bit integer timestamp, stored in native endianess
[def [const beldate]] see above, stored in big endian
[def [const leldate]] see above, stored in small/little endian
[list_end]
[vset CATEGORY {fileutil :: magic}]
[include ../doctools2base/include/feedback.inc]
[manpage_end]
|
