The Tcpdump Group git mirrors - libpcap/blob - pcap-savefile.manfile.in

   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 .\"
  20 .TH PCAP-SAVEFILE @MAN_FILE_FORMATS@ "16 Aug 2023"
  21 .SH NAME
  22 pcap-savefile \- libpcap savefile format
  23 .SH DESCRIPTION
  24 NOTE: applications and libraries should, if possible, use libpcap to
  25 read savefiles, rather than having their own code to read savefiles.
  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 Reserved1
  45 _
  46 Reserved2
  47 _
  48 Snapshot length
  49 _
  50 Link-layer header type and additional information
  51 .TE
  52 .RE
  53 .PP
  54 The per-file header length is 24 octets.
  55 .PP
  56 All fields in the per-file header are in the byte order of the host
  57 writing the file.  Normally, the first field in the per-file header is a
  58 4-byte magic number, with the value
  59 .BR 0xa1b2c3d4 .
  60 The magic number, when
  61 read by a host with the same byte order as the host that wrote the file,
  62 will have the value
  63 .BR 0xa1b2c3d4 ,
  64 and, when read by a host with the
  65 opposite byte order as the host that wrote the file, will have the value
  66 .BR 0xd4c3b2a1 .
  67 That allows software reading the file to determine whether
  68 the byte order of the host that wrote the file is the same as the byte
  69 order of the host on which the file is being read, and thus whether the
  70 values in the per-file and per-packet headers need to be byte-swapped.
  71 .PP
  72 If the magic number has the value
  73 .B 0xa1b23c4d
  74 (with the two nibbles of
  75 the two lower-order bytes of the magic number swapped), which would be
  76 read as
  77 .B 0xa1b23c4d
  78 by a host with the same byte order as the host that
  79 wrote the file and as
  80 .B 0x4d3cb2a1
  81 by a host with the opposite byte order
  82 as the host that wrote the file, the file format is the same as for
  83 regular files, except that the time stamps for packets are given in
  84 seconds and nanoseconds rather than seconds and microseconds.
  85 .PP
  86 Following this are:
  87 .IP
  88 A 2-byte file format major version number; the current version number is
  89 2.
  90 .IP
  91 A 2-byte file format minor version number; the current version number is
  92 4.
  93 .IP
  94 A 4-byte not used - SHOULD be filled with 0 by pcap file writers, and MUST
  95 be ignored by pcap file readers.  This value was documented by some older
  96 implementations as "gmt to local correction" or "time zone offset".
  97 Some older pcap file writers stored non-zero values in this field.
  98 .IP
  99 A 4-byte not used - SHOULD be filled with 0 by pcap file writers, and MUST
 100 be ignored by pcap file readers.  This value was documented by some older
 101 implementations as "accuracy of timestamps".  Some older pcap file
 102 writers stored non-zero values in this field.
 103 .IP
 104 A 4-byte number giving the "snapshot length" of the capture; packets
 105 longer than the snapshot length are truncated to the snapshot length, so
 106 that, if the snapshot length is
 107 .IR N ,
 108 only the first
 109 .I N
 110 bytes of a packet longer than
 111 .I N
 112 bytes will be saved in the capture.
 113 .IP
 114 A 4-byte number giving the link-layer header type for packets in the
 115 capture and optional additional information.
 116 .IP
 117 This format of this field is:
 118 .PP
 119 .nf
 120                      1                   2                   3
 121  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 122 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 123 |FCS len|R|P|     Reserved3     |        Link-layer type        |
 124 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 125 .fi
 126 .IP
 127 The field is shown as if it were in the byte order of the host reading
 128 or writing the file, with bit 0 being the most-significant bit of the
 129 field and bit 31 being the least-significant bit of the field.
 130 .IP
 131 Link-layer type (16 bits):
 132 A 16-bit value giving the link-layer header type for packets in the file;
 133 see
 134 .BR pcap-linktype (@MAN_MISC_INFO@)
 135 for the
 136 .B LINKTYPE_
 137 values that can appear in this field.
 138 .IP
 139 Reserved3 (10 bits):
 140 not used - MUST be set to zero by pcap writers, and MUST NOT be
 141 interpreted by pcap readers; a reader SHOULD treat a non-zero value as
 142 an error.
 143 .IP
 144 P (1 bit):
 145 A bit that, if set, indicates that the Frame Check Sequence (FCS)
 146 length value is present and, if not set, indicates that the FCS value is
 147 not present.
 148 .IP
 149 R (1 bit):
 150 not used - MUST be set to zero by pcap writers, and MUST NOT be
 151 interpreted by pcap readers; a reader SHOULD treat a non-zero value as
 152 an error.
 153 .IP
 154 FCS len (4 bits):
 155 A 4-bit unsigned value giving the number of 16-bit (2-octet) words
 156 of FCS that are appended to each packet, if the P bit is set; if the P
 157 bit is not set, and the FCS length is not indicated by the link-layer
 158 type value, the FCS length is unknown.  The valid values of the FCS len
 159 field are between 0 and 15; Ethernet, for example, would have an FCS
 160 length value of 2, corresponding to a 4-octet FCS.
 161 .PP
 162 Following the per-file header are zero or more packets; each packet
 163 begins with a per-packet header, which is immediately followed by the
 164 raw packet data.  The format of the per-packet header is:
 165 .RS
 166 .TS
 167 box;
 168 c.
 169 Time stamp, seconds value
 170 _
 171 Time stamp, microseconds or nanoseconds value
 172 _
 173 Length of captured packet data
 174 _
 175 Un-truncated length of the packet data
 176 .TE
 177 .RE
 178 .PP
 179 The per-packet header length is 16 octets.
 180 .PP
 181 All fields in the per-packet header are in the byte order of the host
 182 writing the file.  The per-packet header begins with a time stamp giving
 183 the approximate time the packet was captured; the time stamp consists of
 184 a 4-byte value, giving the time in seconds since January 1, 1970,
 185 00:00:00 UTC, followed by a 4-byte value, giving the time in
 186 microseconds or nanoseconds since that second, depending on the magic
 187 number in the file header.  Following that are a 4-byte value giving the
 188 number of bytes of captured data that follow the per-packet header and a
 189 4-byte value giving the number of bytes that would have been present had
 190 the packet not been truncated by the snapshot length.  The two lengths
 191 will be equal if the number of bytes of packet data are less than or
 192 equal to the snapshot length.
 193 .SH SEE ALSO
 194 .BR pcap (3PCAP)