JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 1 | .\" Copyright (c) 1994, 1996, 1997 |
| 2 | .\" The Regents of the University of California. All rights reserved. |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms, with or without |
| 5 | .\" modification, are permitted provided that: (1) source code distributions |
| 6 | .\" retain the above copyright notice and this paragraph in its entirety, (2) |
| 7 | .\" distributions including binary code include the above copyright notice and |
| 8 | .\" this paragraph in its entirety in the documentation or other materials |
| 9 | .\" provided with the distribution, and (3) all advertising materials mentioning |
| 10 | .\" features or use of this software display the following acknowledgement: |
| 11 | .\" ``This product includes software developed by the University of California, |
| 12 | .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of |
| 13 | .\" the University nor the names of its contributors may be used to endorse |
| 14 | .\" or promote products derived from this software without specific prior |
| 15 | .\" written permission. |
| 16 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED |
| 17 | .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
| 18 | .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 19 | .\" |
Elliott Hughes | 965a4b5 | 2017-05-15 10:37:39 -0700 | [diff] [blame] | 20 | .TH PCAP-SAVEFILE @MAN_FILE_FORMATS@ "8 March 2015" |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 21 | .SH NAME |
| 22 | pcap-savefile \- libpcap savefile format |
| 23 | .SH DESCRIPTION |
| 24 | NOTE: applications and libraries should, if possible, use libpcap to |
Elliott Hughes | d8845d7 | 2015-10-19 18:07:04 -0700 | [diff] [blame] | 25 | read savefiles, rather than having their own code to read savefiles. |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 26 | If, in the future, a new file format is supported by libpcap, |
| 27 | applications and libraries using libpcap to read savefiles will be able |
| 28 | to read the new format of savefiles, but applications and libraries |
| 29 | using their own code to read savefiles will have to be changed to |
| 30 | support the new file format. |
| 31 | .PP |
| 32 | ``Savefiles'' read and written by libpcap and applications using libpcap |
| 33 | start with a per-file header. The format of the per-file header is: |
| 34 | .RS |
| 35 | .TS |
| 36 | box; |
| 37 | c s |
| 38 | c | c |
| 39 | c s. |
| 40 | Magic number |
| 41 | _ |
| 42 | Major version Minor version |
| 43 | _ |
| 44 | Time zone offset |
| 45 | _ |
| 46 | Time stamp accuracy |
| 47 | _ |
| 48 | Snapshot length |
| 49 | _ |
| 50 | Link-layer header type |
| 51 | .TE |
| 52 | .RE |
| 53 | .PP |
| 54 | All fields in the per-file header are in the byte order of the host |
| 55 | writing the file. Normally, the first field in the per-file header is a |
| 56 | 4-byte magic number, with the value 0xa1b2c3d4. The magic number, when |
| 57 | read by a host with the same byte order as the host that wrote the file, |
| 58 | will have the value 0xa1b2c3d4, and, when read by a host with the |
| 59 | opposite byte order as the host that wrote the file, will have the value |
| 60 | 0xd4c3b2a1. That allows software reading the file to determine whether |
| 61 | the byte order of the host that wrote the file is the same as the byte |
| 62 | order of the host on which the file is being read, and thus whether the |
| 63 | values in the per-file and per-packet headers need to be byte-swapped. |
| 64 | .PP |
| 65 | If the magic number has the value 0xa1b23c4d (with the two nibbles of |
| 66 | the two lower-order bytes of the magic number swapped), which would be |
| 67 | read as 0xa1b23c4d by a host with the same byte order as the host that |
| 68 | wrote the file and as 0x4d3cb2a1 by a host with the opposite byte order |
| 69 | as the host that wrote the file, the file format is the same as for |
| 70 | regular files, except that the time stamps for packets are given in |
| 71 | seconds and nanoseconds rather than seconds and microseconds. |
| 72 | .PP |
| 73 | Following this are: |
| 74 | .IP |
| 75 | A 2-byte file format major version number; the current version number is |
| 76 | 2. |
| 77 | .IP |
| 78 | A 2-byte file format minor version number; the current version number is |
| 79 | 4. |
| 80 | .IP |
| 81 | A 4-byte time zone offset; this is always 0. |
| 82 | .IP |
| 83 | A 4-byte number giving the accuracy of time stamps in the file; this is |
| 84 | always 0. |
| 85 | .IP |
| 86 | A 4-byte number giving the "snapshot length" of the capture; packets |
| 87 | longer than the snapshot length are truncated to the snapshot length, so |
| 88 | that, if the snapshot length is |
| 89 | .IR N , |
| 90 | only the first |
| 91 | .I N |
| 92 | bytes of a packet longer than |
| 93 | .I N |
| 94 | bytes will be saved in the capture. |
| 95 | .IP |
| 96 | a 4-byte number giving the link-layer header type for packets in the |
| 97 | capture; see |
| 98 | .BR pcap-linktype (@MAN_MISC_INFO@) |
| 99 | for the |
| 100 | .B LINKTYPE_ |
| 101 | values that can appear in this field. |
| 102 | .PP |
| 103 | Following the per-file header are zero or more packets; each packet |
| 104 | begins with a per-packet header, which is immediately followed by the |
| 105 | raw packet data. The format of the per-packet header is: |
| 106 | .RS |
| 107 | .TS |
| 108 | box; |
| 109 | c. |
| 110 | Time stamp, seconds value |
| 111 | _ |
| 112 | Time stamp, microseconds or nanoseconds value |
| 113 | _ |
| 114 | Length of captured packet data |
| 115 | _ |
| 116 | Un-truncated length of the packet data |
| 117 | .TE |
| 118 | .RE |
| 119 | .PP |
| 120 | All fields in the per-packet header are in the byte order of the host |
| 121 | writing the file. The per-packet header begins with a time stamp giving |
| 122 | the approximate time the packet was captured; the time stamp consists of |
| 123 | a 4-byte value, giving the time in seconds since January 1, 1970, |
| 124 | 00:00:00 UTC, followed by a 4-byte value, giving the time in |
| 125 | microseconds or nanoseconds since that second, depending on the magic |
| 126 | number in the file header. Following that are a 4-byte value giving the |
| 127 | number of bytes of captured data that follow the per-packet header and a |
| 128 | 4-byte value giving the number of bytes that would have been present had |
| 129 | the packet not been truncated by the snapshot length. The two lengths |
| 130 | will be equal if the number of bytes of packet data are less than or |
| 131 | equal to the snapshot length. |
| 132 | .SH SEE ALSO |
| 133 | pcap(3PCAP), pcap-linktype(@MAN_MISC_INFO@) |