contrib/libpcap/pcap-savefile.manfile.in

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