procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Bindat examples in source, not manual

Browse source 
* doc/lispref/processes.texi (Bindat Examples): Remove, fixing
a FIXME in the manual.  The long example had bitrotted to some
extent, compared to the more-up-to-date example in bindat.el
commentary, which apparently what people were referring to
anyway.  The short example was confusing and not that useful
and will be obsolescent anyway if we change timestamp format.
This commit is contained in:
Paul Eggert 2018-09-20 17:43:42 -07:00
parent d6f3c2cf06
commit 7f3877e834
2 changed files with 0 additions and 131 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/lispref/elisp.texi
View file

@ -1391,7 +1391,6 @@ Packing and Unpacking Byte Arrays
* Bindat Spec:: Describing data layout.
* Bindat Functions:: Doing the unpacking and packing.
* Bindat Examples:: Samples of what bindat.el can do for you!
Emacs Display

130
doc/lispref/processes.texi
View file

@ -3126,7 +3126,6 @@ direction is also known as @dfn{serializing} or @dfn{packing}.
@menu
* Bindat Spec:: Describing data layout.
* Bindat Functions:: Doing the unpacking and packing.
* Bindat Examples:: Samples of what bindat.el can do for you!
@end menu
@node Bindat Spec
@ -3369,132 +3368,3 @@ dotted notation.
@result{} "127.0.0.1"
@end example
@end defun
@node Bindat Examples
@subsection Examples of Byte Unpacking and Packing
@c FIXME? This seems a very long example for something that is not used
@c very often. As of 25.2, gdb-mi.el is the only user of bindat.el in Emacs.
@c Maybe one or both of these examples should just be moved to the
@c commentary of bindat.el.
Here are two complete examples that use bindat.el.
The first shows simple byte packing:
@lisp
(require 'bindat)
(defun rfc868-payload ()
(bindat-pack
'((now-hi u16)
(now-lo u16))
;; Emacs uses Unix epoch, while RFC868 epoch
;; is 1900-01-01 00:00:00, which is 2208988800
;; (or #x83aa7e80) seconds more.
(let ((now (time-add nil '(#x83aa #x7e80))))
`((now-hi . ,(car now))
(now-lo . ,(cadr now))))))
(let ((s (rfc868-payload)))
(list (multibyte-string-p s)
(mapconcat (lambda (byte)
(format "%02x" byte))
s " ")
(current-time-string)))
@result{} (nil "dc 6d 17 01" "Fri Mar 10 13:13:53 2017")
@end lisp
The following is an example of defining and unpacking a complex
structure. Consider the following C structures:
@example
struct header @{
unsigned long dest_ip;
unsigned long src_ip;
unsigned short dest_port;
unsigned short src_port;
@};
struct data @{
unsigned char type;
unsigned char opcode;
unsigned short length; /* in network byte order */
unsigned char id[8]; /* null-terminated string */
unsigned char data[/* (length + 3) & ~3 */];
@};
struct packet @{
struct header header;
unsigned long counters[2]; /* in little endian order */
unsigned char items;
unsigned char filler[3];
struct data item[/* items */];
@};
@end example
The corresponding data layout specification is:
@lisp
(setq header-spec
'((dest-ip ip)
(src-ip ip)
(dest-port u16)
(src-port u16)))
(setq data-spec
'((type u8)
(opcode u8)
(length u16) ; network byte order
(id strz 8)
(data vec (length))
(align 4)))
(setq packet-spec
'((header struct header-spec)
(counters vec 2 u32r) ; little endian order
(items u8)
(fill 3)
(item repeat (items)
(struct data-spec))))
@end lisp
A binary data representation is:
@lisp
(setq binary-data
[ 192 168 1 100 192 168 1 101 01 28 21 32
160 134 1 0 5 1 0 0 2 0 0 0
2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])
@end lisp
The corresponding decoded structure is:
@lisp
(setq decoded (bindat-unpack packet-spec binary-data))
@result{}
((header
(dest-ip . [192 168 1 100])
(src-ip . [192 168 1 101])
(dest-port . 284)
(src-port . 5408))
(counters . [100000 261])
(items . 2)
(item ((data . [1 2 3 4 5])
(id . "ABCDEF")
(length . 5)
(opcode . 3)
(type . 2))
((data . [6 7 8 9 10 11 12])
(id . "BCDEFG")
(length . 7)
(opcode . 4)
(type . 1))))
@end lisp
An example of fetching data from this structure:
@lisp
(bindat-get-field decoded 'item 1 'id)
@result{} "BCDEFG"
@end lisp