Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1997 by Sun Microsystems, Inc. | |
3 | '\" | |
4 | '\" See the file "license.terms" for information on usage and redistribution | |
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
6 | '\" | |
7 | '\" RCS: @(#) $Id: binary.n,v 1.11.2.8 2005/02/10 10:28:21 dkf Exp $ | |
8 | '\" | |
9 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
10 | '\" manual entries. | |
11 | '\" | |
12 | '\" .AP type name in/out ?indent? | |
13 | '\" Start paragraph describing an argument to a library procedure. | |
14 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
15 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
16 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
17 | '\" needed; use .AS below instead) | |
18 | '\" | |
19 | '\" .AS ?type? ?name? | |
20 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
21 | '\" name are examples of largest possible arguments that will be passed | |
22 | '\" to .AP later. If args are omitted, default tab stops are used. | |
23 | '\" | |
24 | '\" .BS | |
25 | '\" Start box enclosure. From here until next .BE, everything will be | |
26 | '\" enclosed in one large box. | |
27 | '\" | |
28 | '\" .BE | |
29 | '\" End of box enclosure. | |
30 | '\" | |
31 | '\" .CS | |
32 | '\" Begin code excerpt. | |
33 | '\" | |
34 | '\" .CE | |
35 | '\" End code excerpt. | |
36 | '\" | |
37 | '\" .VS ?version? ?br? | |
38 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
39 | '\" of man pages. The first argument is ignored and used for recording | |
40 | '\" the version when the .VS was added, so that the sidebars can be | |
41 | '\" found and removed when they reach a certain age. If another argument | |
42 | '\" is present, then a line break is forced before starting the sidebar. | |
43 | '\" | |
44 | '\" .VE | |
45 | '\" End of vertical sidebar. | |
46 | '\" | |
47 | '\" .DS | |
48 | '\" Begin an indented unfilled display. | |
49 | '\" | |
50 | '\" .DE | |
51 | '\" End of indented unfilled display. | |
52 | '\" | |
53 | '\" .SO | |
54 | '\" Start of list of standard options for a Tk widget. The | |
55 | '\" options follow on successive lines, in four columns separated | |
56 | '\" by tabs. | |
57 | '\" | |
58 | '\" .SE | |
59 | '\" End of list of standard options for a Tk widget. | |
60 | '\" | |
61 | '\" .OP cmdName dbName dbClass | |
62 | '\" Start of description of a specific option. cmdName gives the | |
63 | '\" option's name as specified in the class command, dbName gives | |
64 | '\" the option's name in the option database, and dbClass gives | |
65 | '\" the option's class in the option database. | |
66 | '\" | |
67 | '\" .UL arg1 arg2 | |
68 | '\" Print arg1 underlined, then print arg2 normally. | |
69 | '\" | |
70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
71 | '\" | |
72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
73 | .if t .wh -1.3i ^B | |
74 | .nr ^l \n(.l | |
75 | .ad b | |
76 | '\" # Start an argument description | |
77 | .de AP | |
78 | .ie !"\\$4"" .TP \\$4 | |
79 | .el \{\ | |
80 | . ie !"\\$2"" .TP \\n()Cu | |
81 | . el .TP 15 | |
82 | .\} | |
83 | .ta \\n()Au \\n()Bu | |
84 | .ie !"\\$3"" \{\ | |
85 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
86 | .\".b | |
87 | .\} | |
88 | .el \{\ | |
89 | .br | |
90 | .ie !"\\$2"" \{\ | |
91 | \&\\$1 \\fI\\$2\\fP | |
92 | .\} | |
93 | .el \{\ | |
94 | \&\\fI\\$1\\fP | |
95 | .\} | |
96 | .\} | |
97 | .. | |
98 | '\" # define tabbing values for .AP | |
99 | .de AS | |
100 | .nr )A 10n | |
101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
102 | .nr )B \\n()Au+15n | |
103 | .\" | |
104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
106 | .. | |
107 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
108 | '\" # BS - start boxed text | |
109 | '\" # ^y = starting y location | |
110 | '\" # ^b = 1 | |
111 | .de BS | |
112 | .br | |
113 | .mk ^y | |
114 | .nr ^b 1u | |
115 | .if n .nf | |
116 | .if n .ti 0 | |
117 | .if n \l'\\n(.lu\(ul' | |
118 | .if n .fi | |
119 | .. | |
120 | '\" # BE - end boxed text (draw box now) | |
121 | .de BE | |
122 | .nf | |
123 | .ti 0 | |
124 | .mk ^t | |
125 | .ie n \l'\\n(^lu\(ul' | |
126 | .el \{\ | |
127 | .\" Draw four-sided box normally, but don't draw top of | |
128 | .\" box if the box started on an earlier page. | |
129 | .ie !\\n(^b-1 \{\ | |
130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
131 | .\} | |
132 | .el \}\ | |
133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
134 | .\} | |
135 | .\} | |
136 | .fi | |
137 | .br | |
138 | .nr ^b 0 | |
139 | .. | |
140 | '\" # VS - start vertical sidebar | |
141 | '\" # ^Y = starting y location | |
142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
143 | .de VS | |
144 | .if !"\\$2"" .br | |
145 | .mk ^Y | |
146 | .ie n 'mc \s12\(br\s0 | |
147 | .el .nr ^v 1u | |
148 | .. | |
149 | '\" # VE - end of vertical sidebar | |
150 | .de VE | |
151 | .ie n 'mc | |
152 | .el \{\ | |
153 | .ev 2 | |
154 | .nf | |
155 | .ti 0 | |
156 | .mk ^t | |
157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
158 | .sp -1 | |
159 | .fi | |
160 | .ev | |
161 | .\} | |
162 | .nr ^v 0 | |
163 | .. | |
164 | '\" # Special macro to handle page bottom: finish off current | |
165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
166 | '\" # page bottom macro. | |
167 | .de ^B | |
168 | .ev 2 | |
169 | 'ti 0 | |
170 | 'nf | |
171 | .mk ^t | |
172 | .if \\n(^b \{\ | |
173 | .\" Draw three-sided box if this is the box's first page, | |
174 | .\" draw two sides but no top otherwise. | |
175 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
177 | .\} | |
178 | .if \\n(^v \{\ | |
179 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
181 | .\} | |
182 | .bp | |
183 | 'fi | |
184 | .ev | |
185 | .if \\n(^b \{\ | |
186 | .mk ^y | |
187 | .nr ^b 2 | |
188 | .\} | |
189 | .if \\n(^v \{\ | |
190 | .mk ^Y | |
191 | .\} | |
192 | .. | |
193 | '\" # DS - begin display | |
194 | .de DS | |
195 | .RS | |
196 | .nf | |
197 | .sp | |
198 | .. | |
199 | '\" # DE - end display | |
200 | .de DE | |
201 | .fi | |
202 | .RE | |
203 | .sp | |
204 | .. | |
205 | '\" # SO - start of list of standard options | |
206 | .de SO | |
207 | .SH "STANDARD OPTIONS" | |
208 | .LP | |
209 | .nf | |
210 | .ta 5.5c 11c | |
211 | .ft B | |
212 | .. | |
213 | '\" # SE - end of list of standard options | |
214 | .de SE | |
215 | .fi | |
216 | .ft R | |
217 | .LP | |
218 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
219 | .. | |
220 | '\" # OP - start of full description for a single option | |
221 | .de OP | |
222 | .LP | |
223 | .nf | |
224 | .ta 4c | |
225 | Command-Line Name: \\fB\\$1\\fR | |
226 | Database Name: \\fB\\$2\\fR | |
227 | Database Class: \\fB\\$3\\fR | |
228 | .fi | |
229 | .IP | |
230 | .. | |
231 | '\" # CS - begin code excerpt | |
232 | .de CS | |
233 | .RS | |
234 | .nf | |
235 | .ta .25i .5i .75i 1i | |
236 | .. | |
237 | '\" # CE - end code excerpt | |
238 | .de CE | |
239 | .fi | |
240 | .RE | |
241 | .. | |
242 | .de UL | |
243 | \\$1\l'|0\(ul'\\$2 | |
244 | .. | |
245 | .TH binary n 8.0 Tcl "Tcl Built-In Commands" | |
246 | .BS | |
247 | '\" Note: do not modify the .SH NAME line immediately below! | |
248 | .SH NAME | |
249 | binary \- Insert and extract fields from binary strings | |
250 | .SH SYNOPSIS | |
251 | \fBbinary format \fIformatString \fR?\fIarg arg ...\fR? | |
252 | .br | |
253 | \fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR? | |
254 | .BE | |
255 | ||
256 | .SH DESCRIPTION | |
257 | .PP | |
258 | This command provides facilities for manipulating binary data. The | |
259 | first form, \fBbinary format\fR, creates a binary string from normal | |
260 | Tcl values. For example, given the values 16 and 22, on a 32 bit | |
261 | architecture, it might produce an 8-byte binary string consisting of | |
262 | two 4-byte integers, one for each of the numbers. The second form of | |
263 | the command, \fBbinary scan\fR, does the opposite: it extracts data | |
264 | from a binary string and returns it as ordinary Tcl string values. | |
265 | ||
266 | .SH "BINARY FORMAT" | |
267 | .PP | |
268 | The \fBbinary format\fR command generates a binary string whose layout | |
269 | is specified by the \fIformatString\fR and whose contents come from | |
270 | the additional arguments. The resulting binary value is returned. | |
271 | .PP | |
272 | The \fIformatString\fR consists of a sequence of zero or more field | |
273 | specifiers separated by zero or more spaces. Each field specifier is | |
274 | a single type character followed by an optional numeric \fIcount\fR. | |
275 | Most field specifiers consume one argument to obtain the value to be | |
276 | formatted. The type character specifies how the value is to be | |
277 | formatted. The \fIcount\fR typically indicates how many items of the | |
278 | specified type are taken from the value. If present, the \fIcount\fR | |
279 | is a non-negative decimal integer or \fB*\fR, which normally indicates | |
280 | that all of the items in the value are to be used. If the number of | |
281 | arguments does not match the number of fields in the format string | |
282 | that consume arguments, then an error is generated. | |
283 | .PP | |
284 | Here is a small example to clarify the relation between the field | |
285 | specifiers and the arguments: | |
286 | .CS | |
287 | \fBbinary format d3d {1.0 2.0 3.0 4.0} 0.1\fR | |
288 | .CE | |
289 | .PP | |
290 | The first argument is a list of four numbers, but because of the count | |
291 | of 3 for the associated field specifier, only the first three will be | |
292 | used. The second argument is associated with the second field | |
293 | specifier. The resulting binary string contains the four numbers 1.0, | |
294 | 2.0, 3.0 and 0.1. | |
295 | .PP | |
296 | Each type-count pair moves an imaginary cursor through the binary | |
297 | data, storing bytes at the current position and advancing the cursor | |
298 | to just after the last byte stored. The cursor is initially at | |
299 | position 0 at the beginning of the data. The type may be any one of | |
300 | the following characters: | |
301 | .IP \fBa\fR 5 | |
302 | Stores a character string of length \fIcount\fR in the output string. | |
303 | Every character is taken as modulo 256 (i.e. the low byte of every | |
304 | character is used, and the high byte discarded) so when storing | |
305 | character strings not wholly expressible using the characters \\u0000-\\u00ff, | |
306 | the \fBencoding convertto\fR command should be used | |
307 | first if this truncation is not desired (i.e. if the characters are | |
308 | not part of the ISO 8859-1 character set.) | |
309 | If \fIarg\fR has fewer than \fIcount\fR bytes, then additional zero | |
310 | bytes are used to pad out the field. If \fIarg\fR is longer than the | |
311 | specified length, the extra characters will be ignored. If | |
312 | \fIcount\fR is \fB*\fR, then all of the bytes in \fIarg\fR will be | |
313 | formatted. If \fIcount\fR is omitted, then one character will be | |
314 | formatted. For example, | |
315 | .RS | |
316 | .CS | |
317 | \fBbinary format a7a*a alpha bravo charlie\fR | |
318 | .CE | |
319 | will return a string equivalent to \fBalpha\\000\\000bravoc\fR. | |
320 | .RE | |
321 | .IP \fBA\fR 5 | |
322 | This form is the same as \fBa\fR except that spaces are used for | |
323 | padding instead of nulls. For example, | |
324 | .RS | |
325 | .CS | |
326 | \fBbinary format A6A*A alpha bravo charlie\fR | |
327 | .CE | |
328 | will return \fBalpha bravoc\fR. | |
329 | .RE | |
330 | .IP \fBb\fR 5 | |
331 | Stores a string of \fIcount\fR binary digits in low-to-high order | |
332 | within each byte in the output string. \fIArg\fR must contain a | |
333 | sequence of \fB1\fR and \fB0\fR characters. The resulting bytes are | |
334 | emitted in first to last order with the bits being formatted in | |
335 | low-to-high order within each byte. If \fIarg\fR has fewer than | |
336 | \fIcount\fR digits, then zeros will be used for the remaining bits. | |
337 | If \fIarg\fR has more than the specified number of digits, the extra | |
338 | digits will be ignored. If \fIcount\fR is \fB*\fR, then all of the | |
339 | digits in \fIarg\fR will be formatted. If \fIcount\fR is omitted, | |
340 | then one digit will be formatted. If the number of bits formatted | |
341 | does not end at a byte boundary, the remaining bits of the last byte | |
342 | will be zeros. For example, | |
343 | .RS | |
344 | .CS | |
345 | \fBbinary format b5b* 11100 111000011010\fR | |
346 | .CE | |
347 | will return a string equivalent to \fB\\x07\\x87\\x05\fR. | |
348 | .RE | |
349 | .IP \fBB\fR 5 | |
350 | This form is the same as \fBb\fR except that the bits are stored in | |
351 | high-to-low order within each byte. For example, | |
352 | .RS | |
353 | .CS | |
354 | \fBbinary format B5B* 11100 111000011010\fR | |
355 | .CE | |
356 | will return a string equivalent to \fB\\xe0\\xe1\\xa0\fR. | |
357 | .RE | |
358 | .IP \fBh\fR 5 | |
359 | Stores a string of \fIcount\fR hexadecimal digits in low-to-high | |
360 | within each byte in the output string. \fIArg\fR must contain a | |
361 | sequence of characters in the set ``0123456789abcdefABCDEF''. The | |
362 | resulting bytes are emitted in first to last order with the hex digits | |
363 | being formatted in low-to-high order within each byte. If \fIarg\fR | |
364 | has fewer than \fIcount\fR digits, then zeros will be used for the | |
365 | remaining digits. If \fIarg\fR has more than the specified number of | |
366 | digits, the extra digits will be ignored. If \fIcount\fR is | |
367 | \fB*\fR, then all of the digits in \fIarg\fR will be formatted. If | |
368 | \fIcount\fR is omitted, then one digit will be formatted. If the | |
369 | number of digits formatted does not end at a byte boundary, the | |
370 | remaining bits of the last byte will be zeros. For example, | |
371 | .RS | |
372 | .CS | |
373 | \fBbinary format h3h* AB def\fR | |
374 | .CE | |
375 | will return a string equivalent to \fB\\xba\\x00\\xed\\x0f\fR. | |
376 | .RE | |
377 | .IP \fBH\fR 5 | |
378 | This form is the same as \fBh\fR except that the digits are stored in | |
379 | high-to-low order within each byte. For example, | |
380 | .RS | |
381 | .CS | |
382 | \fBbinary format H3H* ab DEF\fR | |
383 | .CE | |
384 | will return a string equivalent to \fB\\xab\\x00\\xde\\xf0\fR. | |
385 | .RE | |
386 | .IP \fBc\fR 5 | |
387 | Stores one or more 8-bit integer values in the output string. If no | |
388 | \fIcount\fR is specified, then \fIarg\fR must consist of an integer | |
389 | value; otherwise \fIarg\fR must consist of a list containing at least | |
390 | \fIcount\fR integer elements. The low-order 8 bits of each integer | |
391 | are stored as a one-byte value at the cursor position. If \fIcount\fR | |
392 | is \fB*\fR, then all of the integers in the list are formatted. If | |
393 | the number of elements in the list is fewer than \fIcount\fR, then an | |
394 | error is generated. If the number of elements in the list is greater | |
395 | than \fIcount\fR, then the extra elements are ignored. For example, | |
396 | .RS | |
397 | .CS | |
398 | \fBbinary format c3cc* {3 -3 128 1} 260 {2 5}\fR | |
399 | .CE | |
400 | will return a string equivalent to | |
401 | \fB\\x03\\xfd\\x80\\x04\\x02\\x05\fR, whereas | |
402 | .CS | |
403 | \fBbinary format c {2 5}\fR | |
404 | .CE | |
405 | will generate an error. | |
406 | .RE | |
407 | .IP \fBs\fR 5 | |
408 | This form is the same as \fBc\fR except that it stores one or more | |
409 | 16-bit integers in little-endian byte order in the output string. The | |
410 | low-order 16-bits of each integer are stored as a two-byte value at | |
411 | the cursor position with the least significant byte stored first. For | |
412 | example, | |
413 | .RS | |
414 | .CS | |
415 | \fBbinary format s3 {3 -3 258 1}\fR | |
416 | .CE | |
417 | will return a string equivalent to | |
418 | \fB\\x03\\x00\\xfd\\xff\\x02\\x01\fR. | |
419 | .RE | |
420 | .IP \fBS\fR 5 | |
421 | This form is the same as \fBs\fR except that it stores one or more | |
422 | 16-bit integers in big-endian byte order in the output string. For | |
423 | example, | |
424 | .RS | |
425 | .CS | |
426 | \fBbinary format S3 {3 -3 258 1}\fR | |
427 | .CE | |
428 | will return a string equivalent to | |
429 | \fB\\x00\\x03\\xff\\xfd\\x01\\x02\fR. | |
430 | .RE | |
431 | .IP \fBi\fR 5 | |
432 | This form is the same as \fBc\fR except that it stores one or more | |
433 | 32-bit integers in little-endian byte order in the output string. The | |
434 | low-order 32-bits of each integer are stored as a four-byte value at | |
435 | the cursor position with the least significant byte stored first. For | |
436 | example, | |
437 | .RS | |
438 | .CS | |
439 | \fBbinary format i3 {3 -3 65536 1}\fR | |
440 | .CE | |
441 | will return a string equivalent to | |
442 | \fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x01\\x00\fR | |
443 | .RE | |
444 | .IP \fBI\fR 5 | |
445 | This form is the same as \fBi\fR except that it stores one or more one | |
446 | or more 32-bit integers in big-endian byte order in the output string. | |
447 | For example, | |
448 | .RS | |
449 | .CS | |
450 | \fBbinary format I3 {3 -3 65536 1}\fR | |
451 | .CE | |
452 | will return a string equivalent to | |
453 | \fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x01\\x00\\x00\fR | |
454 | .RE | |
455 | .IP \fBw\fR 5 | |
456 | .VS 8.4 | |
457 | This form is the same as \fBc\fR except that it stores one or more | |
458 | 64-bit integers in little-endian byte order in the output string. The | |
459 | low-order 64-bits of each integer are stored as an eight-byte value at | |
460 | the cursor position with the least significant byte stored first. For | |
461 | example, | |
462 | .RS | |
463 | .CS | |
464 | \fBbinary format w 7810179016327718216\fR | |
465 | .CE | |
466 | will return the string \fBHelloTcl\fR | |
467 | .RE | |
468 | .IP \fBW\fR 5 | |
469 | This form is the same as \fBw\fR except that it stores one or more one | |
470 | or more 64-bit integers in big-endian byte order in the output string. | |
471 | For example, | |
472 | .RS | |
473 | .CS | |
474 | \fBbinary format Wc 4785469626960341345 110\fR | |
475 | .CE | |
476 | will return the string \fBBigEndian\fR | |
477 | .VE | |
478 | .RE | |
479 | .IP \fBf\fR 5 | |
480 | This form is the same as \fBc\fR except that it stores one or more one | |
481 | or more single-precision floating in the machine's native | |
482 | representation in the output string. This representation is not | |
483 | portable across architectures, so it should not be used to communicate | |
484 | floating point numbers across the network. The size of a floating | |
485 | point number may vary across architectures, so the number of bytes | |
486 | that are generated may vary. If the value overflows the | |
487 | machine's native representation, then the value of FLT_MAX | |
488 | as defined by the system will be used instead. Because Tcl uses | |
489 | double-precision floating-point numbers internally, there may be some | |
490 | loss of precision in the conversion to single-precision. For example, | |
491 | on a Windows system running on an Intel Pentium processor, | |
492 | .RS | |
493 | .CS | |
494 | \fBbinary format f2 {1.6 3.4}\fR | |
495 | .CE | |
496 | will return a string equivalent to | |
497 | \fB\\xcd\\xcc\\xcc\\x3f\\x9a\\x99\\x59\\x40\fR. | |
498 | .RE | |
499 | .IP \fBd\fR 5 | |
500 | This form is the same as \fBf\fR except that it stores one or more one | |
501 | or more double-precision floating in the machine's native | |
502 | representation in the output string. For example, on a | |
503 | Windows system running on an Intel Pentium processor, | |
504 | .RS | |
505 | .CS | |
506 | \fBbinary format d1 {1.6}\fR | |
507 | .CE | |
508 | will return a string equivalent to | |
509 | \fB\\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f\fR. | |
510 | .RE | |
511 | .IP \fBx\fR 5 | |
512 | Stores \fIcount\fR null bytes in the output string. If \fIcount\fR is | |
513 | not specified, stores one null byte. If \fIcount\fR is \fB*\fR, | |
514 | generates an error. This type does not consume an argument. For | |
515 | example, | |
516 | .RS | |
517 | .CS | |
518 | \fBbinary format a3xa3x2a3 abc def ghi\fR | |
519 | .CE | |
520 | will return a string equivalent to \fBabc\\000def\\000\\000ghi\fR. | |
521 | .RE | |
522 | .IP \fBX\fR 5 | |
523 | Moves the cursor back \fIcount\fR bytes in the output string. If | |
524 | \fIcount\fR is \fB*\fR or is larger than the current cursor position, | |
525 | then the cursor is positioned at location 0 so that the next byte | |
526 | stored will be the first byte in the result string. If \fIcount\fR is | |
527 | omitted then the cursor is moved back one byte. This type does not | |
528 | consume an argument. For example, | |
529 | .RS | |
530 | .CS | |
531 | \fBbinary format a3X*a3X2a3 abc def ghi\fR | |
532 | .CE | |
533 | will return \fBdghi\fR. | |
534 | .RE | |
535 | .IP \fB@\fR 5 | |
536 | Moves the cursor to the absolute location in the output string | |
537 | specified by \fIcount\fR. Position 0 refers to the first byte in the | |
538 | output string. If \fIcount\fR refers to a position beyond the last | |
539 | byte stored so far, then null bytes will be placed in the uninitialized | |
540 | locations and the cursor will be placed at the specified location. If | |
541 | \fIcount\fR is \fB*\fR, then the cursor is moved to the current end of | |
542 | the output string. If \fIcount\fR is omitted, then an error will be | |
543 | generated. This type does not consume an argument. For example, | |
544 | .RS | |
545 | .CS | |
546 | \fBbinary format a5@2a1@*a3@10a1 abcde f ghi j\fR | |
547 | .CE | |
548 | will return \fBabfdeghi\\000\\000j\fR. | |
549 | .RE | |
550 | ||
551 | .SH "BINARY SCAN" | |
552 | .PP | |
553 | The \fBbinary scan\fR command parses fields from a binary string, | |
554 | returning the number of conversions performed. \fIString\fR gives the | |
555 | input to be parsed and \fIformatString\fR indicates how to parse it. | |
556 | Each \fIvarName\fR gives the name of a variable; when a field is | |
557 | scanned from \fIstring\fR the result is assigned to the corresponding | |
558 | variable. | |
559 | .PP | |
560 | As with \fBbinary format\fR, the \fIformatString\fR consists of a | |
561 | sequence of zero or more field specifiers separated by zero or more | |
562 | spaces. Each field specifier is a single type character followed by | |
563 | an optional numeric \fIcount\fR. Most field specifiers consume one | |
564 | argument to obtain the variable into which the scanned values should | |
565 | be placed. The type character specifies how the binary data is to be | |
566 | interpreted. The \fIcount\fR typically indicates how many items of | |
567 | the specified type are taken from the data. If present, the | |
568 | \fIcount\fR is a non-negative decimal integer or \fB*\fR, which | |
569 | normally indicates that all of the remaining items in the data are to | |
570 | be used. If there are not enough bytes left after the current cursor | |
571 | position to satisfy the current field specifier, then the | |
572 | corresponding variable is left untouched and \fBbinary scan\fR returns | |
573 | immediately with the number of variables that were set. If there are | |
574 | not enough arguments for all of the fields in the format string that | |
575 | consume arguments, then an error is generated. | |
576 | .PP | |
577 | A similar example as with \fBbinary format\fR should explain the | |
578 | relation between field specifiers and arguments in case of the binary | |
579 | scan subcommand: | |
580 | .CS | |
581 | \fBbinary scan $bytes s3s first second\fR | |
582 | .CE | |
583 | .PP | |
584 | This command (provided the binary string in the variable \fIbytes\fR | |
585 | is long enough) assigns a list of three integers to the variable | |
586 | \fIfirst\fR and assigns a single value to the variable \fIsecond\fR. | |
587 | If \fIbytes\fR contains fewer than 8 bytes (i.e. four 2-byte | |
588 | integers), no assignment to \fIsecond\fR will be made, and if | |
589 | \fIbytes\fR contains fewer than 6 bytes (i.e. three 2-byte integers), | |
590 | no assignment to \fIfirst\fR will be made. Hence: | |
591 | .CS | |
592 | \fBputs [binary scan abcdefg s3s first second]\fR | |
593 | \fBputs $first\fR | |
594 | \fBputs $second\fR | |
595 | .CE | |
596 | will print (assuming neither variable is set previously): | |
597 | .CS | |
598 | \fB1\fR | |
599 | \fB25185 25699 26213\fR | |
600 | \fIcan't read "second": no such variable\fR | |
601 | .CE | |
602 | .PP | |
603 | It is \fBimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR | |
604 | (and \fBi\fR and \fBI\fR on 64bit systems) will be scanned into | |
605 | long data size values. In doing this, values that have their high | |
606 | bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints), | |
607 | will be sign extended. Thus the following will occur: | |
608 | .CS | |
609 | \fBset signShort [binary format s1 0x8000]\fR | |
610 | \fBbinary scan $signShort s1 val; \fI# val == 0xFFFF8000\fR | |
611 | .CE | |
612 | If you want to produce an unsigned value, then you can mask the return | |
613 | value to the desired size. For example, to produce an unsigned short | |
614 | value: | |
615 | .CS | |
616 | \fBset val [expr {$val & 0xFFFF}]; \fI# val == 0x8000\fR | |
617 | .CE | |
618 | .PP | |
619 | Each type-count pair moves an imaginary cursor through the binary data, | |
620 | reading bytes from the current position. The cursor is initially | |
621 | at position 0 at the beginning of the data. The type may be any one of | |
622 | the following characters: | |
623 | .IP \fBa\fR 5 | |
624 | The data is a character string of length \fIcount\fR. If \fIcount\fR | |
625 | is \fB*\fR, then all of the remaining bytes in \fIstring\fR will be | |
626 | scanned into the variable. If \fIcount\fR is omitted, then one | |
627 | character will be scanned. | |
628 | All characters scanned will be interpreted as being in the | |
629 | range \\u0000-\\u00ff so the \fBencoding convertfrom\fR command might be | |
630 | needed if the string is not an ISO 8859\-1 string. | |
631 | For example, | |
632 | .RS | |
633 | .CS | |
634 | \fBbinary scan abcde\\000fghi a6a10 var1 var2\fR | |
635 | .CE | |
636 | will return \fB1\fR with the string equivalent to \fBabcde\\000\fR | |
637 | stored in \fBvar1\fR and \fBvar2\fR left unmodified. | |
638 | .RE | |
639 | .IP \fBA\fR 5 | |
640 | This form is the same as \fBa\fR, except trailing blanks and nulls are stripped from | |
641 | the scanned value before it is stored in the variable. For example, | |
642 | .RS | |
643 | .CS | |
644 | \fBbinary scan "abc efghi \\000" A* var1\fR | |
645 | .CE | |
646 | will return \fB1\fR with \fBabc efghi\fR stored in \fBvar1\fR. | |
647 | .RE | |
648 | .IP \fBb\fR 5 | |
649 | The data is turned into a string of \fIcount\fR binary digits in | |
650 | low-to-high order represented as a sequence of ``1'' and ``0'' | |
651 | characters. The data bytes are scanned in first to last order with | |
652 | the bits being taken in low-to-high order within each byte. Any extra | |
653 | bits in the last byte are ignored. If \fIcount\fR is \fB*\fR, then | |
654 | all of the remaining bits in \fBstring\fR will be scanned. If | |
655 | \fIcount\fR is omitted, then one bit will be scanned. For example, | |
656 | .RS | |
657 | .CS | |
658 | \fBbinary scan \\x07\\x87\\x05 b5b* var1 var2\fR | |
659 | .CE | |
660 | will return \fB2\fR with \fB11100\fR stored in \fBvar1\fR and | |
661 | \fB1110000110100000\fR stored in \fBvar2\fR. | |
662 | .RE | |
663 | .IP \fBB\fR 5 | |
664 | This form is the same as \fBb\fR, except the bits are taken in | |
665 | high-to-low order within each byte. For example, | |
666 | .RS | |
667 | .CS | |
668 | \fBbinary scan \\x70\\x87\\x05 B5B* var1 var2\fR | |
669 | .CE | |
670 | will return \fB2\fR with \fB01110\fR stored in \fBvar1\fR and | |
671 | \fB1000011100000101\fR stored in \fBvar2\fR. | |
672 | .RE | |
673 | .IP \fBh\fR 5 | |
674 | The data is turned into a string of \fIcount\fR hexadecimal digits in | |
675 | low-to-high order represented as a sequence of characters in the set | |
676 | ``0123456789abcdef''. The data bytes are scanned in first to last | |
677 | order with the hex digits being taken in low-to-high order within each | |
678 | byte. Any extra bits in the last byte are ignored. If \fIcount\fR | |
679 | is \fB*\fR, then all of the remaining hex digits in \fBstring\fR will be | |
680 | scanned. If \fIcount\fR is omitted, then one hex digit will be | |
681 | scanned. For example, | |
682 | .RS | |
683 | .CS | |
684 | \fBbinary scan \\x07\\x86\\x05 h3h* var1 var2\fR | |
685 | .CE | |
686 | will return \fB2\fR with \fB706\fR stored in \fBvar1\fR and | |
687 | \fB50\fR stored in \fBvar2\fR. | |
688 | .RE | |
689 | .IP \fBH\fR 5 | |
690 | This form is the same as \fBh\fR, except the digits are taken in | |
691 | high-to-low order within each byte. For example, | |
692 | .RS | |
693 | .CS | |
694 | \fBbinary scan \\x07\\x86\\x05 H3H* var1 var2\fR | |
695 | .CE | |
696 | will return \fB2\fR with \fB078\fR stored in \fBvar1\fR and | |
697 | \fB05\fR stored in \fBvar2\fR. | |
698 | .RE | |
699 | .IP \fBc\fR 5 | |
700 | The data is turned into \fIcount\fR 8-bit signed integers and stored | |
701 | in the corresponding variable as a list. If \fIcount\fR is \fB*\fR, | |
702 | then all of the remaining bytes in \fBstring\fR will be scanned. If | |
703 | \fIcount\fR is omitted, then one 8-bit integer will be scanned. For | |
704 | example, | |
705 | .RS | |
706 | .CS | |
707 | \fBbinary scan \\x07\\x86\\x05 c2c* var1 var2\fR | |
708 | .CE | |
709 | will return \fB2\fR with \fB7 -122\fR stored in \fBvar1\fR and \fB5\fR | |
710 | stored in \fBvar2\fR. Note that the integers returned are signed, but | |
711 | they can be converted to unsigned 8-bit quantities using an expression | |
712 | like: | |
713 | .CS | |
714 | \fBexpr { $num & 0xff }\fR | |
715 | .CE | |
716 | .RE | |
717 | .IP \fBs\fR 5 | |
718 | The data is interpreted as \fIcount\fR 16-bit signed integers | |
719 | represented in little-endian byte order. The integers are stored in | |
720 | the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then | |
721 | all of the remaining bytes in \fBstring\fR will be scanned. If | |
722 | \fIcount\fR is omitted, then one 16-bit integer will be scanned. For | |
723 | example, | |
724 | .RS | |
725 | .CS | |
726 | \fBbinary scan \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2\fR | |
727 | .CE | |
728 | will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR | |
729 | stored in \fBvar2\fR. Note that the integers returned are signed, but | |
730 | they can be converted to unsigned 16-bit quantities using an expression | |
731 | like: | |
732 | .CS | |
733 | \fBexpr { $num & 0xffff }\fR | |
734 | .CE | |
735 | .RE | |
736 | .IP \fBS\fR 5 | |
737 | This form is the same as \fBs\fR except that the data is interpreted | |
738 | as \fIcount\fR 16-bit signed integers represented in big-endian byte | |
739 | order. For example, | |
740 | .RS | |
741 | .CS | |
742 | \fBbinary scan \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2\fR | |
743 | .CE | |
744 | will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR | |
745 | stored in \fBvar2\fR. | |
746 | .RE | |
747 | .IP \fBi\fR 5 | |
748 | The data is interpreted as \fIcount\fR 32-bit signed integers | |
749 | represented in little-endian byte order. The integers are stored in | |
750 | the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then | |
751 | all of the remaining bytes in \fBstring\fR will be scanned. If | |
752 | \fIcount\fR is omitted, then one 32-bit integer will be scanned. For | |
753 | example, | |
754 | .RS | |
755 | .CS | |
756 | \fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff i2i* var1 var2\fR | |
757 | .CE | |
758 | will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR | |
759 | stored in \fBvar2\fR. Note that the integers returned are signed, but | |
760 | they can be converted to unsigned 32-bit quantities using an expression | |
761 | like: | |
762 | .CS | |
763 | \fBexpr { $num & 0xffffffff }\fR | |
764 | .CE | |
765 | .RE | |
766 | .IP \fBI\fR 5 | |
767 | This form is the same as \fBI\fR except that the data is interpreted | |
768 | as \fIcount\fR 32-bit signed integers represented in big-endian byte | |
769 | order. For example, | |
770 | .RS | |
771 | .CS | |
772 | \fBbinary scan \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 I2I* var1 var2\fR | |
773 | .CE | |
774 | will return \fB2\fR with \fB5 7\fR stored in \fBvar1\fR and \fB-16\fR | |
775 | stored in \fBvar2\fR. | |
776 | .RE | |
777 | .IP \fBw\fR 5 | |
778 | .VS 8.4 | |
779 | The data is interpreted as \fIcount\fR 64-bit signed integers | |
780 | represented in little-endian byte order. The integers are stored in | |
781 | the corresponding variable as a list. If \fIcount\fR is \fB*\fR, then | |
782 | all of the remaining bytes in \fBstring\fR will be scanned. If | |
783 | \fIcount\fR is omitted, then one 64-bit integer will be scanned. For | |
784 | example, | |
785 | .RS | |
786 | .CS | |
787 | \fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff wi* var1 var2\fR | |
788 | .CE | |
789 | will return \fB2\fR with \fB30064771077\fR stored in \fBvar1\fR and | |
790 | \fB-16\fR stored in \fBvar2\fR. Note that the integers returned are | |
791 | signed and cannot be represented by Tcl as unsigned values. | |
792 | .RE | |
793 | .IP \fBW\fR 5 | |
794 | This form is the same as \fBw\fR except that the data is interpreted | |
795 | as \fIcount\fR 64-bit signed integers represented in big-endian byte | |
796 | order. For example, | |
797 | .RS | |
798 | .CS | |
799 | \fBbinary scan \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 WI* var1 var2\fR | |
800 | .CE | |
801 | will return \fB2\fR with \fB21474836487\fR stored in \fBvar1\fR and \fB-16\fR | |
802 | stored in \fBvar2\fR. | |
803 | .VE | |
804 | .RE | |
805 | .IP \fBf\fR 5 | |
806 | The data is interpreted as \fIcount\fR single-precision floating point | |
807 | numbers in the machine's native representation. The floating point | |
808 | numbers are stored in the corresponding variable as a list. If | |
809 | \fIcount\fR is \fB*\fR, then all of the remaining bytes in | |
810 | \fBstring\fR will be scanned. If \fIcount\fR is omitted, then one | |
811 | single-precision floating point number will be scanned. The size of a | |
812 | floating point number may vary across architectures, so the number of | |
813 | bytes that are scanned may vary. If the data does not represent a | |
814 | valid floating point number, the resulting value is undefined and | |
815 | compiler dependent. For example, on a Windows system running on an | |
816 | Intel Pentium processor, | |
817 | .RS | |
818 | .CS | |
819 | \fBbinary scan \\x3f\\xcc\\xcc\\xcd f var1\fR | |
820 | .CE | |
821 | will return \fB1\fR with \fB1.6000000238418579\fR stored in | |
822 | \fBvar1\fR. | |
823 | .RE | |
824 | .IP \fBd\fR 5 | |
825 | This form is the same as \fBf\fR except that the data is interpreted | |
826 | as \fIcount\fR double-precision floating point numbers in the | |
827 | machine's native representation. For example, on a Windows system | |
828 | running on an Intel Pentium processor, | |
829 | .RS | |
830 | .CS | |
831 | \fBbinary scan \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1\fR | |
832 | .CE | |
833 | will return \fB1\fR with \fB1.6000000000000001\fR | |
834 | stored in \fBvar1\fR. | |
835 | .RE | |
836 | .IP \fBx\fR 5 | |
837 | Moves the cursor forward \fIcount\fR bytes in \fIstring\fR. If | |
838 | \fIcount\fR is \fB*\fR or is larger than the number of bytes after the | |
839 | current cursor cursor position, then the cursor is positioned after | |
840 | the last byte in \fIstring\fR. If \fIcount\fR is omitted, then the | |
841 | cursor is moved forward one byte. Note that this type does not | |
842 | consume an argument. For example, | |
843 | .RS | |
844 | .CS | |
845 | \fBbinary scan \\x01\\x02\\x03\\x04 x2H* var1\fR | |
846 | .CE | |
847 | will return \fB1\fR with \fB0304\fR stored in \fBvar1\fR. | |
848 | .RE | |
849 | .IP \fBX\fR 5 | |
850 | Moves the cursor back \fIcount\fR bytes in \fIstring\fR. If | |
851 | \fIcount\fR is \fB*\fR or is larger than the current cursor position, | |
852 | then the cursor is positioned at location 0 so that the next byte | |
853 | scanned will be the first byte in \fIstring\fR. If \fIcount\fR | |
854 | is omitted then the cursor is moved back one byte. Note that this | |
855 | type does not consume an argument. For example, | |
856 | .RS | |
857 | .CS | |
858 | \fBbinary scan \\x01\\x02\\x03\\x04 c2XH* var1 var2\fR | |
859 | .CE | |
860 | will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR | |
861 | stored in \fBvar2\fR. | |
862 | .RE | |
863 | .IP \fB@\fR 5 | |
864 | Moves the cursor to the absolute location in the data string specified | |
865 | by \fIcount\fR. Note that position 0 refers to the first byte in | |
866 | \fIstring\fR. If \fIcount\fR refers to a position beyond the end of | |
867 | \fIstring\fR, then the cursor is positioned after the last byte. If | |
868 | \fIcount\fR is omitted, then an error will be generated. For example, | |
869 | .RS | |
870 | .CS | |
871 | \fBbinary scan \\x01\\x02\\x03\\x04 c2@1H* var1 var2\fR | |
872 | .CE | |
873 | will return \fB2\fR with \fB1 2\fR stored in \fBvar1\fR and \fB020304\fR | |
874 | stored in \fBvar2\fR. | |
875 | .RE | |
876 | .SH "PLATFORM ISSUES" | |
877 | Sometimes it is desirable to format or scan integer values in the | |
878 | native byte order for the machine. Refer to the \fBbyteOrder\fR | |
879 | element of the \fBtcl_platform\fR array to decide which type character | |
880 | to use when formatting or scanning integers. | |
881 | .SH EXAMPLES | |
882 | This is a procedure to write a Tcl string to a binary-encoded channel as | |
883 | UTF-8 data preceded by a length word: | |
884 | .CS | |
885 | proc writeString {channel string} { | |
886 | set data [encoding convertto utf-8 $string] | |
887 | puts -nonewline [\fBbinary format\fR Ia* \e | |
888 | [string length $data] $data] | |
889 | } | |
890 | .CE | |
891 | .PP | |
892 | This procedure reads a string from a channel that was written by the | |
893 | previously presented \fBwriteString\fR procedure: | |
894 | .CS | |
895 | proc readString {channel} { | |
896 | if {![\fBbinary scan\fR [read $channel 4] I length]} { | |
897 | error "missing length" | |
898 | } | |
899 | set data [read $channel $length] | |
900 | return [encoding convertfrom utf-8 $data] | |
901 | } | |
902 | .CE | |
903 | ||
904 | .SH "SEE ALSO" | |
905 | format(n), scan(n), tclvars(n) | |
906 | ||
907 | .SH KEYWORDS | |
908 | binary, format, scan |