1binary(n)                    Tcl Built-In Commands                   binary(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       binary - Insert and extract fields from binary strings
9

SYNOPSIS

11       binary format formatString ?arg arg ...?
12       binary scan string formatString ?varName varName ...?
13_________________________________________________________________
14

DESCRIPTION

16       This  command  provides  facilities  for manipulating binary data.  The
17       first form, binary format, creates a binary string from normal Tcl val‐
18       ues.   For  example,  given the values 16 and 22, on a 32-bit architec‐
19       ture, it might produce an 8-byte binary string consisting of two 4-byte
20       integers, one for each of the numbers.  The second form of the command,
21       binary scan, does the opposite: it extracts data from a  binary  string
22       and returns it as ordinary Tcl string values.
23

BINARY FORMAT

25       The  binary  format  command  generates a binary string whose layout is
26       specified by the formatString and whose contents come  from  the  addi‐
27       tional arguments.  The resulting binary value is returned.
28
29       The  formatString  consists  of a sequence of zero or more field speci‐
30       fiers separated by zero or more spaces.  Each field specifier is a sin‐
31       gle  type  character followed by an optional flag character followed by
32       an optional numeric count.  Most field specifiers consume one  argument
33       to  obtain the value to be formatted.  The type character specifies how
34       the value is to be formatted.  The count typically indicates  how  many
35       items  of the specified type are taken from the value.  If present, the
36       count is a non-negative decimal integer or *, which normally  indicates
37       that  all  of  the items in the value are to be used.  If the number of
38       arguments does not match the number of fields in the format string that
39       consume  arguments,  then  an error is generated. The flag character is
40       ignored for for binary format.
41
42       Here is a small example to clarify the relation between the field spec‐
43       ifiers and the arguments:
44              binary format d3d {1.0 2.0 3.0 4.0} 0.1
45
46       The  first argument is a list of four numbers, but because of the count
47       of 3 for the associated field specifier, only the first three  will  be
48       used.  The  second  argument is associated with the second field speci‐
49       fier. The resulting binary string contains the four numbers  1.0,  2.0,
50       3.0 and 0.1.
51
52       Each type-count pair moves an imaginary cursor through the binary data,
53       storing bytes at the current position and advancing the cursor to  just
54       after  the  last byte stored.  The cursor is initially at position 0 at
55       the beginning of the data.  The type may be any one  of  the  following
56       characters:
57
58       a    Stores  a byte string of length count in the output string.  Every
59            character is taken as modulo 256 (i.e. the low byte of every char‐
60            acter  is used, and the high byte discarded) so when storing char‐
61            acter  strings  not  wholly  expressible  using   the   characters
62            \u0000-\u00ff, the encoding convertto command should be used first
63            to change the string into an external representation if this trun‐
64            cation  is not desired (i.e. if the characters are not part of the
65            ISO 8859-1 character set.)  If arg has  fewer  than  count  bytes,
66            then  additional zero bytes are used to pad out the field.  If arg
67            is longer than the specified length, the extra characters will  be
68            ignored.  If count is *, then all of the bytes in arg will be for‐
69            matted.  If count is omitted, then one character will  be  format‐
70            ted.  For example,
71                   binary format a7a*a alpha bravo charlie
72            will return a string equivalent to alpha\000\000bravoc,
73                   binary format a* [encoding convertto utf-8 \u20ac]
74            will  return  a  string  equivalent  to \342\202\254 (which is the
75            UTF-8 byte sequence for a Euro-currency character) and
76                   binary format a* [encoding convertto iso8859-15 \u20ac]
77            will return a string equivalent to \244 (which is the ISO  8859-15
78            byte  sequence for a Euro-currency character). Contrast these last
79            two with:
80                   binary format a* \u20ac
81            which returns a string equivalent to \254 (i.e. \xac) by  truncat‐
82            ing the high-bits of the character, and which is probably not what
83            is desired.
84
85       A    This form is the same as a except that spaces are used for padding
86            instead of nulls.  For example,
87                   binary format A6A*A alpha bravo charlie
88            will return alpha bravoc.
89
90       b    Stores a string of count binary digits in low-to-high order within
91            each byte in the output string.  Arg must contain a sequence of  1
92            and  0  characters.   The  resulting bytes are emitted in first to
93            last order with the bits  being  formatted  in  low-to-high  order
94            within  each byte.  If arg has fewer than count digits, then zeros
95            will be used for the remaining bits.  If arg  has  more  than  the
96            specified  number of digits, the extra digits will be ignored.  If
97            count is *, then all of the digits in arg will be  formatted.   If
98            count is omitted, then one digit will be formatted.  If the number
99            of bits formatted does not end at a byte boundary,  the  remaining
100            bits of the last byte will be zeros.  For example,
101                   binary format b5b* 11100 111000011010
102            will return a string equivalent to \x07\x87\x05.
103
104       B    This  form  is  the  same  as b except that the bits are stored in
105            high-to-low order within each byte.  For example,
106                   binary format B5B* 11100 111000011010
107            will return a string equivalent to \xe0\xe1\xa0.
108
109       H    Stores a string of count hexadecimal digits in high-to-low  within
110            each  byte  in  the output string.  Arg must contain a sequence of
111            characters in the  set  “0123456789abcdefABCDEF”.   The  resulting
112            bytes are emitted in first to last order with the hex digits being
113            formatted in high-to-low order within each byte.  If arg has fewer
114            than  count digits, then zeros will be used for the remaining dig‐
115            its.  If arg has more than the specified  number  of  digits,  the
116            extra digits will be ignored.  If count is *, then all of the dig‐
117            its in arg will be formatted.  If count is omitted, then one digit
118            will be formatted.  If the number of digits formatted does not end
119            at a byte boundary, the remaining bits of the last  byte  will  be
120            zeros.  For example,
121                   binary format H3H*H2 ab DEF 987
122            will return a string equivalent to \xab\x00\xde\xf0\x98.
123
124       h    This  form  is  the same as H except that the digits are stored in
125            low-to-high order within each byte. This is seldom  required.  For
126            example,
127                   binary format h3h*h2 AB def 987
128            will return a string equivalent to \xba\x00\xed\x0f\x89.
129
130       c    Stores  one or more 8-bit integer values in the output string.  If
131            no count is specified, then arg must consist of an integer  value.
132            If  count  is  specified, arg must consist of a list containing at
133            least that many integers. The low-order 8 bits of each integer are
134            stored as a one-byte value at the cursor position.  If count is *,
135            then all of the integers in the list are formatted. If the  number
136            of elements in the list is greater than count, then the extra ele‐
137            ments are ignored.  For example,
138                   binary format c3cc* {3 -3 128 1} 260 {2 5}
139            will  return  a  string  equivalent  to  \x03\xfd\x80\x04\x02\x05,
140            whereas
141                   binary format c {2 5}
142            will generate an error.
143
144       s    This  form  is  the  same  as  c except that it stores one or more
145            16-bit integers in little-endian byte order in the output  string.
146            The  low-order  16-bits  of  each integer are stored as a two-byte
147            value at the cursor  position  with  the  least  significant  byte
148            stored first.  For example,
149                   binary format s3 {3 -3 258 1}
150            will return a string equivalent to \x03\x00\xfd\xff\x02\x01.
151
152       S    This  form  is  the  same  as  s except that it stores one or more
153            16-bit integers in big-endian byte order  in  the  output  string.
154            For example,
155                   binary format S3 {3 -3 258 1}
156            will return a string equivalent to \x00\x03\xff\xfd\x01\x02.
157
158       t    This  form  (mnemonically tiny) is the same as s and S except that │
159            it stores the 16-bit integers in the output string in  the  native │
160            byte  order  of  the  machine where the Tcl script is running.  To │
161            determine what the native byte order of the machine is,  refer  to │
162            the byteOrder element of the tcl_platform array.
163
164       i    This  form  is  the  same  as  c except that it stores one or more
165            32-bit integers in little-endian byte order in the output  string.
166            The  low-order  32-bits  of each integer are stored as a four-byte
167            value at the cursor  position  with  the  least  significant  byte
168            stored first.  For example,
169                   binary format i3 {3 -3 65536 1}
170            will        return        a       string       equivalent       to
171            \x03\x00\x00\x00\xfd\xff\xff\xff\x00\x00\x01\x00
172
173       I    This form is the same as i except that it stores one or  more  one
174            or  more  32-bit  integers  in big-endian byte order in the output
175            string.  For example,
176                   binary format I3 {3 -3 65536 1}
177            will       return       a       string        equivalent        to
178            \x00\x00\x00\x03\xff\xff\xff\xfd\x00\x01\x00\x00
179
180       n    This  form  (mnemonically number or normal) is the same as i and I 
181            except that it stores the 32-bit integers in the output string  in │
182            the  native byte order of the machine where the Tcl script is run‐ │
183            ning.  To determine what the native byte order of the machine  is, │
184            refer to the byteOrder element of the tcl_platform array.
185
186       w    This  form  is  the  same  as  c except that it stores one or more
187            64-bit integers in little-endian byte order in the output  string.
188            The  low-order 64-bits of each integer are stored as an eight-byte
189            value at the cursor  position  with  the  least  significant  byte
190            stored first.  For example,
191                   binary format w 7810179016327718216
192            will return the string HelloTcl
193
194       W    This  form  is the same as w except that it stores one or more one
195            or more 64-bit integers in big-endian byte  order  in  the  output
196            string.  For example,
197                   binary format Wc 4785469626960341345 110
198            will return the string BigEndian
199
200       m    This  form  (mnemonically  the mirror of w) is the same as w and W 
201            except that it stores the 64-bit integers in the output string  in │
202            the  native byte order of the machine where the Tcl script is run‐ │
203            ning.  To determine what the native byte order of the machine  is, │
204            refer to the byteOrder element of the tcl_platform array.
205
206       f    This  form  is the same as c except that it stores one or more one
207            or more single-precision floating point numbers in  the  machine's
208            native  representation  in the output string.  This representation
209            is not portable across architectures, so it should not be used  to
210            communicate  floating  point numbers across the network.  The size
211            of a floating point number may vary across architectures,  so  the
212            number  of  bytes that are generated may vary.  If the value over‐
213            flows the machine's  native  representation,  then  the  value  of
214            FLT_MAX  as  defined  by the system will be used instead.  Because
215            Tcl uses double-precision floating point numbers internally, there
216            may  be  some loss of precision in the conversion to single-preci‐
217            sion.  For example, on a Windows system running on an  Intel  Pen‐
218            tium processor,
219                   binary format f2 {1.6 3.4}
220            will        return        a       string       equivalent       to
221            \xcd\xcc\xcc\x3f\x9a\x99\x59\x40.
222
223       r    This form (mnemonically real) is the same  as  f  except  that  it │
224            stores  the  single-precision  floating  point  numbers in little- │
225            endian order.  This conversion  only  produces  meaningful  output │
226            when  used on machines which use the IEEE floating point represen‐ │
227            tation (very common, but not universal.)
228
229       R    This form is the same as r except that it stores the single-preci‐ │
230            sion floating point numbers in big-endian order.
231
232       d    This  form  is the same as f except that it stores one or more one
233            or more double-precision floating point numbers in  the  machine's
234            native  representation  in  the  output string.  For example, on a
235            Windows system running on an Intel Pentium processor,
236                   binary format d1 {1.6}
237            will       return       a       string        equivalent        to
238            \x9a\x99\x99\x99\x99\x99\xf9\x3f.
239
240       q    This  form  (mnemonically the mirror of d) is the same as d except │
241            that it stores the double-precision floating point numbers in lit‐ │
242            tle-endian order.  This conversion only produces meaningful output │
243            when used on machines which use the IEEE floating point  represen‐ │
244            tation (very common, but not universal.)
245
246       Q    This form is the same as q except that it stores the double-preci‐ │
247            sion floating point numbers in big-endian order.
248
249       x    Stores count null bytes in the output string.   If  count  is  not
250            specified,  stores  one  null  byte.   If count is *, generates an
251            error.  This type does not consume an argument.  For example,
252                   binary format a3xa3x2a3 abc def ghi
253            will return a string equivalent to abc\000def\000\000ghi.
254
255       X    Moves the cursor back count bytes in the output string.  If  count
256            is  * or is larger than the current cursor position, then the cur‐
257            sor is positioned at location 0 so that the next byte stored  will
258            be  the first byte in the result string.  If count is omitted then
259            the cursor is moved back one byte.  This type does not consume  an
260            argument.  For example,
261                   binary format a3X*a3X2a3 abc def ghi
262            will return dghi.
263
264       @    Moves  the  cursor  to  the absolute location in the output string
265            specified by count.  Position 0 refers to the first  byte  in  the
266            output string.  If count refers to a position beyond the last byte
267            stored so far, then null bytes will be placed in the uninitialized
268            locations and the cursor will be placed at the specified location.
269            If count is *, then the cursor is moved to the current end of  the
270            output  string.  If count is omitted, then an error will be gener‐
271            ated.  This type does not consume an argument. For example,
272                   binary format a5@2a1@*a3@10a1 abcde f ghi j
273            will return abfdeghi\000\000j.
274

BINARY SCAN

276       The binary scan command parses fields from a binary  string,  returning
277       the  number  of conversions performed.  String gives the input bytes to
278       be parsed (one byte per character, and characters not representable  as
279       a  byte have their high bits chopped) and formatString indicates how to
280       parse it.  Each varName gives the name of a variable; when a  field  is
281       scanned  from  string the result is assigned to the corresponding vari‐
282       able.
283
284       As with binary format, the formatString consists of a sequence of  zero
285       or  more field specifiers separated by zero or more spaces.  Each field
286       specifier is a single type character followed by an optional flag char‐
287       acter  followed  by  an  optional numeric count.  Most field specifiers
288       consume one argument to obtain the variable into which the scanned val‐
289       ues should be placed.  The type character specifies how the binary data
290       is to be interpreted.  The count typically indicates how many items  of
291       the specified type are taken from the data.  If present, the count is a
292       non-negative decimal integer or *, which normally indicates that all of
293       the  remaining  items  in  the  data  are to be used.  If there are not
294       enough bytes left after the current cursor position to satisfy the cur‐
295       rent field specifier, then the corresponding variable is left untouched
296       and binary scan returns immediately with the number of  variables  that
297       were  set.   If there are not enough arguments for all of the fields in
298       the format string that consume arguments, then an error  is  generated.
299       The  flag  character “u” may be given to cause some types to be read as
300       unsigned values. The flag is  accepted  for  all  field  types  but  is
301       ignored for non-integer fields.
302
303       A  similar  example  as  with binary format should explain the relation
304       between field specifiers and arguments in case of the binary scan  sub‐
305       command:
306              binary scan $bytes s3s first second
307
308       This  command (provided the binary string in the variable bytes is long
309       enough) assigns a list of three integers  to  the  variable  first  and
310       assigns a single value to the variable second.  If bytes contains fewer
311       than 8 bytes (i.e. four 2-byte integers), no assignment to second  will
312       be  made,  and  if bytes contains fewer than 6 bytes (i.e. three 2-byte
313       integers), no assignment to first will be made.  Hence:
314              puts [binary scan abcdefg s3s first second]
315              puts $first
316              puts $second
317       will print (assuming neither variable is set previously):
318              1
319              25185 25699 26213
320              can't read "second": no such variable
321
322       It is important to note that the c, s, and S (and i and I on 64bit sys‐
323       tems)  will be scanned into long data size values.  In doing this, val‐
324       ues that have their high bit set (0x80 for chars,  0x8000  for  shorts,
325       0x80000000  for  ints), will be sign extended.  Thus the following will
326       occur:
327              set signShort [binary format s1 0x8000]
328              binary scan $signShort s1 val; # val == 0xFFFF8000
329       If you require unsigned values you can include the “u”  flag  character
330       following the field type. For example, to read an unsigned short value:
331              set signShort [binary format s1 0x8000]
332              binary scan $signShort su1 val; # val == 0x00008000
333
334       Each type-count pair moves an imaginary cursor through the binary data,
335       reading bytes from the current position.  The cursor  is  initially  at
336       position  0  at  the beginning of the data.  The type may be any one of
337       the following characters:
338
339       a    The data is a byte string of length count.  If count  is  *,  then
340            all  of  the  remaining  bytes  in string will be scanned into the
341            variable.  If count is omitted, then one  byte  will  be  scanned.
342            All  bytes  scanned will be interpreted as being characters in the
343            range \u0000-\u00ff so the encoding convertfrom  command  will  be
344            needed if the string is not a binary string or a string encoded in
345            ISO 8859-1.  For example,
346                   binary scan abcde\000fghi a6a10 var1 var2
347            will return 1 with the string equivalent to  abcde\000  stored  in
348            var1 and var2 left unmodified, and
349                   binary scan \342\202\254 a* var1
350                   set var2 [encoding convertfrom utf-8 $var1]
351            will store a Euro-currency character in var2.
352
353       A    This  form  is the same as a, except trailing blanks and nulls are
354            stripped from the scanned value before it is stored in  the  vari‐
355            able.  For example,
356                   binary scan "abc efghi  \000" A* var1
357            will return 1 with abc efghi stored in var1.
358
359       b    The data is turned into a string of count binary digits in low-to-
360            high order represented as a sequence of “1”  and  “0”  characters.
361            The  data  bytes  are scanned in first to last order with the bits
362            being taken in low-to-high order within each byte.  Any extra bits
363            in  the  last  byte  are  ignored.  If count is *, then all of the
364            remaining bits in string will be scanned.  If  count  is  omitted,
365            then one bit will be scanned.  For example,
366                   binary scan \x07\x87\x05 b5b* var1 var2
367            will  return  2  with  11100  stored  in var1 and 1110000110100000
368            stored in var2.
369
370       B    This form is the same as b, except the bits are taken in  high-to-
371            low order within each byte.  For example,
372                   binary scan \x70\x87\x05 B5B* var1 var2
373            will  return  2  with  01110  stored  in var1 and 1000011100000101
374            stored in var2.
375
376       H    The data is turned into a string of count  hexadecimal  digits  in
377            high-to-low  order  represented as a sequence of characters in the
378            set “0123456789abcdef”.  The data bytes are scanned  in  first  to
379            last  order  with  the hex digits being taken in high-to-low order
380            within each byte. Any extra bits in the last byte are ignored.  If
381            count is *, then all of the remaining hex digits in string will be
382            scanned. If count is omitted, then one hex digit will be  scanned.
383            For example,
384                   binary scan \x07\xC6\x05\x1f\x34 H3H* var1 var2
385            will return 2 with 07c stored in var1 and 051f34 stored in var2.
386
387       h    This form is the same as H, except the digits are taken in reverse
388            (low-to-high) order within each byte. For example,
389                   binary scan \x07\x86\x05\x12\x34 h3h* var1 var2
390            will return 2 with 706 stored in var1 and 502143 stored in var2.
391       Note that most code that wishes to parse the  hexadecimal  digits  from
392       multiple bytes in order should use the H format.
393
394       c    The  data is turned into count 8-bit signed integers and stored in
395            the corresponding variable as a list. If count is *, then  all  of
396            the  remaining bytes in string will be scanned.  If count is omit‐
397            ted, then one 8-bit integer will be scanned.  For example,
398                   binary scan \x07\x86\x05 c2c* var1 var2
399            will return 2 with 7 -122 stored in var1 and  5  stored  in  var2.
400            Note  that  the integers returned are signed, but they can be con‐
401            verted to unsigned 8-bit quantities using an expression like:
402                   set num [expr { $num & 0xff }]
403
404       s    The data is interpreted as count  16-bit  signed  integers  repre‐
405            sented  in  little-endian  byte order.  The integers are stored in
406            the corresponding variable as a list.  If count is *, then all  of
407            the  remaining bytes in string will be scanned.  If count is omit‐
408            ted, then one 16-bit integer will be scanned.  For example,
409                   binary scan \x05\x00\x07\x00\xf0\xff s2s* var1 var2
410            will return 2 with 5 7 stored in var1  and  -16  stored  in  var2.
411            Note  that  the integers returned are signed, but they can be con‐
412            verted to unsigned 16-bit quantities using an expression like:
413                   set num [expr { $num & 0xffff }]
414
415       S    This form is the same as s except that the data is interpreted  as
416            count 16-bit signed integers represented in big-endian byte order.
417            For example,
418                   binary scan \x00\x05\x00\x07\xff\xf0 S2S* var1 var2
419            will return 2 with 5 7 stored in var1 and -16 stored in var2.
420
421       t    The data is interpreted as count  16-bit  signed  integers  repre‐ │
422            sented  in  the  native  byte order of the machine running the Tcl │
423            script.  It is otherwise identical to s and S.  To determine  what │
424            the  native  byte  order of the machine is, refer to the byteOrder 
425            element of the tcl_platform array.
426
427       i    The data is interpreted as count  32-bit  signed  integers  repre‐
428            sented  in  little-endian  byte order.  The integers are stored in
429            the corresponding variable as a list.  If count is *, then all  of
430            the  remaining bytes in string will be scanned.  If count is omit‐
431            ted, then one 32-bit integer will be scanned.  For example,
432                   set str \x05\x00\x00\x00\x07\x00\x00\x00\xf0\xff\xff\xff
433                   binary scan $str i2i* var1 var2
434            will return 2 with 5 7 stored in var1  and  -16  stored  in  var2.
435            Note  that  the integers returned are signed, but they can be con‐
436            verted to unsigned 32-bit quantities using an expression like:
437                   set num [expr { $num & 0xffffffff }]
438
439       I    This form is the same as I except that the data is interpreted  as
440            count 32-bit signed integers represented in big-endian byte order.
441            For example,
442                   set str \x00\x00\x00\x05\x00\x00\x00\x07\xff\xff\xff\xf0
443                   binary scan $str I2I* var1 var2
444            will return 2 with 5 7 stored in var1 and -16 stored in var2.
445
446       n    The data is interpreted as count  32-bit  signed  integers  repre‐ │
447            sented  in  the  native  byte order of the machine running the Tcl │
448            script.  It is otherwise identical to i and I.  To determine  what │
449            the  native  byte  order of the machine is, refer to the byteOrder 
450            element of the tcl_platform array.
451
452       w    The data is interpreted as count  64-bit  signed  integers  repre‐
453            sented  in  little-endian  byte order.  The integers are stored in
454            the corresponding variable as a list.  If count is *, then all  of
455            the  remaining bytes in string will be scanned.  If count is omit‐
456            ted, then one 64-bit integer will be scanned.  For example,
457                   set str \x05\x00\x00\x00\x07\x00\x00\x00\xf0\xff\xff\xff
458                   binary scan $str wi* var1 var2
459            will return 2 with 30064771077 stored in var1 and  -16  stored  in
460            var2.   Note  that  the integers returned are signed and cannot be
461            represented by Tcl as unsigned values.
462
463       W    This form is the same as w except that the data is interpreted  as
464            count 64-bit signed integers represented in big-endian byte order.
465            For example,
466                   set str \x00\x00\x00\x05\x00\x00\x00\x07\xff\xff\xff\xf0
467                   binary scan $str WI* var1 var2
468            will return 2 with 21474836487 stored in var1 and  -16  stored  in
469            var2.
470
471       m    The  data  is  interpreted  as count 64-bit signed integers repre‐ │
472            sented in the native byte order of the  machine  running  the  Tcl │
473            script.   It is otherwise identical to w and W.  To determine what │
474            the native byte order of the machine is, refer  to  the  byteOrder 
475            element of the tcl_platform array.
476
477       f    The  data  is interpreted as count single-precision floating point
478            numbers in the  machine's  native  representation.   The  floating
479            point  numbers are stored in the corresponding variable as a list.
480            If count is *, then all of the remaining bytes in string  will  be
481            scanned.   If count is omitted, then one single-precision floating
482            point number will be scanned.  The size of a floating point number
483            may  vary  across  architectures,  so the number of bytes that are
484            scanned may vary.  If the data does not represent a valid floating
485            point number, the resulting value is undefined and compiler depen‐
486            dent.  For example, on a Windows system running on an  Intel  Pen‐
487            tium processor,
488                   binary scan \x3f\xcc\xcc\xcd f var1
489            will return 1 with 1.6000000238418579 stored in var1.
490
491       r    This  form is the same as f except that the data is interpreted as │
492            count single-precision  floating  point  number  in  little-endian │
493            order.  This conversion is not portable to the minority of systems │
494            not using IEEE floating point representations.
495
496       R    This form is the same as f except that the data is interpreted  as │
497            count  single-precision floating point number in big-endian order. │
498            This conversion is not portable to the  minority  of  systems  not │
499            using IEEE floating point representations.
500
501       d    This  form is the same as f except that the data is interpreted as
502            count double-precision floating point  numbers  in  the  machine's
503            native representation. For example, on a Windows system running on
504            an Intel Pentium processor,
505                   binary scan \x9a\x99\x99\x99\x99\x99\xf9\x3f d var1
506            will return 1 with 1.6000000000000001 stored in var1.
507
508       q    This form is the same as d except that the data is interpreted  as │
509            count  double-precision  floating  point  number  in little-endian │
510            order.  This conversion is not portable to the minority of systems │
511            not using IEEE floating point representations.
512
513       Q    This  form is the same as d except that the data is interpreted as │
514            count double-precision floating point number in big-endian  order. │
515            This  conversion  is  not  portable to the minority of systems not │
516            using IEEE floating point representations.
517
518       x    Moves the cursor forward count bytes in string.  If count is *  or
519            is  larger than the number of bytes after the current cursor posi‐
520            tion, then the cursor is positioned after the last byte in string.
521            If  count  is  omitted, then the cursor is moved forward one byte.
522            Note that this type does not consume an argument.  For example,
523                   binary scan \x01\x02\x03\x04 x2H* var1
524            will return 1 with 0304 stored in var1.
525
526       X    Moves the cursor back count bytes in string.  If count is * or  is
527            larger  than the current cursor position, then the cursor is posi‐
528            tioned at location 0 so that the next byte  scanned  will  be  the
529            first  byte  in  string.   If  count is omitted then the cursor is
530            moved back one byte.  Note that this  type  does  not  consume  an
531            argument.  For example,
532                   binary scan \x01\x02\x03\x04 c2XH* var1 var2
533            will return 2 with 1 2 stored in var1 and 020304 stored in var2.
534
535       @    Moves the cursor to the absolute location in the data string spec‐
536            ified by count.  Note that position 0 refers to the first byte  in
537            string.   If  count refers to a position beyond the end of string,
538            then the cursor is positioned after the last byte.   If  count  is
539            omitted, then an error will be generated.  For example,
540                   binary scan \x01\x02\x03\x04 c2@1H* var1 var2
541            will return 2 with 1 2 stored in var1 and 020304 stored in var2.
542

PORTABILITY ISSUES

544       The  r, R, q and Q conversions will only work reliably for transferring
545       data between computers which are all using IEEE floating  point  repre‐
546       sentations.   This  is  very  common,  but  not universal.  To transfer
547       floating-point numbers portably between all  architectures,  use  their
548       textual representation (as produced by format) instead.
549

EXAMPLES

551       This  is  a procedure to write a Tcl string to a binary-encoded channel
552       as UTF-8 data preceded by a length word:
553              proc writeString {channel string} {
554                  set data [encoding convertto utf-8 $string]
555                  puts -nonewline [binary format Ia* \
556                          [string length $data] $data]
557              }
558
559       This procedure reads a string from a channel that was  written  by  the
560       previously presented writeString procedure:
561              proc readString {channel} {
562                  if {![binary scan [read $channel 4] I length]} {
563                      error "missing length"
564                  }
565                  set data [read $channel $length]
566                  return [encoding convertfrom utf-8 $data]
567              }
568

SEE ALSO

570       format(n), scan(n), tclvars(n)
571

KEYWORDS

573       binary, format, scan
574
575
576
577Tcl                                   8.0                            binary(n)
Impressum