new mandoc-style pcap(3) man page; kwesterback@home.com

1 files changed, 228 insertions, 236 deletions

diff --git a/lib/libpcap/pcap.3 b/lib/libpcap/pcap.3
index 5af5cc94de8..e219abc4bf1 100644
--- a/lib/libpcap/pcap.3
+++ b/lib/libpcap/pcap.3
@@ -1,4 +1,3 @@
-.\"	$OpenBSD: pcap.3,v 1.10 1999/06/17 15:51:08 brad Exp $
 .\"	$NetBSD: pcap.3,v 1.2.6.1 1996/06/05 18:04:43 cgd Exp $
 .\"
 .\" Copyright (c) 1994
@@ -20,317 +19,310 @@
 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 .\"
-.TH PCAP 3  "12 Oct 1994"
-.SH NAME
-pcap \- Packet Capture library
-.SH SYNOPSIS
-.nf
-.ft B
-#include <pcap.h>
-.ft
-.LP
-.ft B
-pcap_t *pcap_open_live(char *device, int snaplen,
-.ti +8
-int promisc, int to_ms, char *ebuf)
-pcap_t *pcap_open_offline(char *fname, char *ebuf)
-pcap_dumper_t *pcap_dump_open(pcap_t *p, char *fname)
-.ft
-.LP
-.ft B
-char errbuf[PCAP_ERRBUF_SIZE];
-char *pcap_lookupdev(char *errbuf)
-int pcap_lookupnet(char *device, u_int32_t *netp,
-.ti +8
-u_int32_t *maskp, char *errbuf)
-.ft
-.LP
-.ft B
-int pcap_dispatch(pcap_t *p, int cnt,
-.ti +8
-pcap_handler callback, u_char *user)
-int pcap_loop(pcap_t *p, int cnt,
-.ti +8
-pcap_handler callback, u_char *user)
-void pcap_dump(u_char *user, struct pcap_pkthdr *h,
-.ti +8
-u_char *sp)
-.ft
-.LP
-.ft B
-int pcap_inject(pcap_t *p, void *, size_t)
-.ft
-.LP
-.ft B
-int pcap_immediate(pcap_t *p)
-.ft
-.LP
-.ft B
-int pcap_compile(pcap_t *p, struct bpf_program *fp,
-.ti +8
-char *str, int optimize, u_int32_t netmask)
-int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
-.ft
-.LP
-.ft B
-u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
-.ft
-.LP
-.ft B
-int pcap_datalink(pcap_t *p)
-int pcap_snapshot(pcap_t *p)
-int pcap_is_swapped(pcap_t *p)
-int pcap_major_version(pcap_t *p)
-int pcap_minor_version(pcap_t *p)
-int pcap_stats(pcap_t *p, struct pcap_stat *ps)
-FILE *pcap_file(pcap_t *p)
-int pcap_fileno(pcap_t *p)
-void pcap_perror(pcap_t *p, char *prefix)
-char *pcap_geterr(pcap_t *p)
-char *pcap_strerror(int error)
-.ft
-.LP
-.ft B
-void pcap_close(pcap_t *p)
-void pcap_dump_close(pcap_dumper_t *p)
-.ft
-.fi
-.SH DESCRIPTION
-The Packet Capture library
+.Dd 4 June, 1999
+.Os
+.Dt PCAP 3
+.Sh NAME
+.Nm pcap
+.Nd Packet Capture library
+.Sh SYNOPSIS
+.Fd #include <pcap.h>
+.Ft "pcap_t *"
+.Fn pcap_open_live "char *device" "int snaplen" "int promisc" "int to_ms" "char *errbuf"
+.Ft "pcap_t *"
+.Fn pcap_open_offline "char *fname" "char *errbuf"
+.Ft "pcap_dumper_t *"
+.Fn pcap_dump_open "pcap_t *p" "char *fname"
+.Ft "char *"
+.Fn pcap_lookupdev "char *errbuf"
+.Ft uint
+.Fn pcap_lookupnet "char *device" "u_int32_t *netp" "u_int32_t *maskp" "char *errbuf"
+.Ft int
+.Fn pcap_dispatch "pcap_t *p" "int cnt" "pcap_handler callback" "u_char *user"
+.Ft int
+.Fn pcap_loop "pcap_t *p" "int cnt" "pcap_handler callback" "u_char *user"
+.Ft void
+.Fn pcap_dump "u_char *user" "struct pcap_pkthdr *h" "u_char *sp"
+.Ft int
+.Fn pcap_inject "pcap_t *p" "void *, size_t"
+.Ft int
+.Fn pcap_immediate "pcap_t *p"
+.Ft int
+.Fn pcap_compile "pcap_t *p" "struct bpf_program *fp" "char *str" "int optimize" "u_int32_t netmask"
+.Ft int
+.Fn pcap_setfilter "pcap_t *p" "struct bpf_program *fp"
+.Ft "u_char *"
+.Fn pcap_next "pcap_t *p" "struct pcap_pkthdr *h"
+.Ft int
+.Fn pcap_datalink "pcap_t *p"
+.Ft int
+.Fn pcap_snapshot "pcap_t *p"
+.Ft int
+.Fn pcap_is_swapped "pcap_t *p"
+.Ft int
+.Fn pcap_major_version "pcap_t *p"
+.Ft int
+.Fn pcap_minor_version "pcap_t *p"
+.Ft int
+.Fn pcap_stats "pcap_t *p" "struct pcap_stat *ps"
+.Ft "FILE *"
+.Fn pcap_file "pcap_t *p"
+.Ft int
+.Fn pcap_fileno "pcap_t *p"
+.Ft void
+.Fn pcap_perror "pcap_t *p" "char *prefix"
+.Ft "char *"
+.Fn pcap_geterr "pcap_t *p"
+.Ft "char *"
+.Fn pcap_strerror "int error"
+.Ft void
+.Fn pcap_close "pcap_t *p"
+.Ft void
+.Fn pcap_dump_close "pcap_dumper_t *p"
+.Sh DESCRIPTION
+.Nm
 provides a high level interface to packet capture systems. All packets
 on the network, even those destined for other hosts, are accessible
 through this mechanism.
-.PP
-.SH ROUTINES
-.B pcap_open_live()
+.Sh ROUTINES
+.Sy Note:
+.Fa errbuf
+in
+.Fn pcap_open_live ,
+.Fn pcap_open_offline ,
+.Fn pcap_lookupdev ,
+and
+.Fn pcap_lookupnet
+is assumed to be able to hold at least 
+.Dv PCAP_ERRBUFF_SIZE
+chars.
+.Pp
+.Fn pcap_open_live
 is used to obtain a packet capture descriptor to look
 at packets on the network.
-.I device
+.Fa device
 is a string that specifies the network device to open.
-.I snaplen
+.Fa snaplen
 specifies the maximum number of bytes to capture.
-.I to_ms
+.Fa to_ms
 specifies the read timeout in milliseconds.
-.I ebuf
+.Fa errbuf
 is used to return error text and is only set when
-.B pcap_open_live()
+.Fn pcap_open_live
 fails and returns
-.BR NULL .
-.PP
-.B pcap_open_offline()
-is called to open a ``savefile'' for reading.
-.I fname
+.Dv NULL .
+.Pp
+.Fn pcap_open_offline
+is called to open a
+.Dq savefile
+for reading.
+.Fa fname
 specifies the name of the file to open. The file has
 the same format as those used by
-.B tcpdump(8) .
+.Xr tcpdump 8 .
 .\" and
 .\" .BR tcpslice(1) .
-The name "-" is a synonym for
-.BR stdin .
-.I ebuf
+The name
+.Ql -
+is a synonym for
+.Dv stdin .
+.Fa errbuf
 is used to return error text and is only set when
-.B pcap_open_offline()
+.Fn pcap_open_offline
 fails and returns
-.BR NULL .
-.PP
-.B pcap_dump_open()
-is called to open a ``savefile'' for writing. The name "-" is a synonym
-for
-.BR stdin .
-.B NULL
+.Dv NULL .
+.Pp
+.Fn pcap_dump_open
+is called to open a
+.Dq savefile
+for writing. The name
+.Ql -
+is a synonym for
+.Dv stdin .
+.Dv NULL
 is returned on failure.
-.I p
+.Fa p
 is a
-.I pcap
+.Fa pcap
 struct as returned by
-.B pcap_open_offline()
+.Fn pcap_open_offline
 or
-.BR pcap_open_live() .
-.I fname
-specifies the name of the file to open.
-If
-.B NULL
+.Fn pcap_open_live .
+.Fa fname
+specifies the name of the file to open. If
+.Dv NULL
 is returned,
-.B pcap_geterr()
+.Fn pcap_geterr
 can be used to get the error text.
-.PP
-.B pcap_lookupdev()
+.Pp
+.Fn pcap_lookupdev
 returns a pointer to a network device suitable for use with
-.B pcap_open_live()
+.Fn pcap_open_live
 and
-.BR pcap_lookupnet() .
+.Fn pcap_lookupnet .
 If there is an error,
-.B NULL
+.Dv NULL
 is returned and
-.I errbuf
+.Fa errbuf
 is filled in with an appropriate error message.
-.PP
-.B pcap_lookupnet()
+.Pp
+.Fn pcap_lookupnet
 is used to determine the network number and mask
 associated with the network device
-.BR device .
+.Fa device .
 Both
-.I netp
+.Fa netp
 and
-.I maskp
+.Fa maskp
 are
-.I u_int32_t
+.Fa u_int32_t
 pointers.
-A return of -1 indicates an error in which case
-.I errbuf
+A return of \-1 indicates an error in which case
+.Fa errbuf
 is filled in with with an appropriate error message.
-.PP
-.B pcap_dispatch()
+.Pp
+.Fn pcap_dispatch
 is used to collect and process packets.
-.I cnt
+.Fa cnt
 specifies the maximum number of packets to process before returning. A
-.I cnt
-of -1 processes all the packets received in one buffer. A
-.I cnt
+.Fa cnt
+of \-1 processes all the packets received in one buffer. A
+.Fa cnt
 of 0 processes all packets until an error occurs (or
-.B EOF
+.Tn EOF
 is reached).
-.I callback
-specifies a routine to be called with three arguments:
-a
-.I u_char
+.Fa callback
+specifies a routine to be called with three arguments: a
+.Fa u_char
 pointer which is passed in from
-.BR pcap_dispatch() ,
+.Fn pcap_dispatch ,
 a pointer to the
-.I pcap_pkthdr
+.Fa pcap_pkthdr
 struct (which precede the actual network headers and data),
 and a length. The number of packets read is returned.
 Zero is returned when
-.B EOF
-is reached in a ``savefile.'' A return of -1 indicates
-an error in which case
-.B pcap_perror()
+.Tn EOF
+is reached in a savefile.
+A return of \-1 indicates an error in which case
+.Fn pcap_perror
 or
-.BR pcap_geterr()
+.Fn pcap_geterr
 may be used to display the error text.
-.PP
-.B pcap_dump()
-outputs a packet to the ``savefile'' opened with
-.BR pcap_dump_open() .
+.Pp
+.Fn pcap_dump
+outputs a packet to the savefile opened with
+.Fn pcap_dump_open .
 Note that its calling arguments are suitable for use with
-.BR pcap_dispatch() .
-.ft B
-(??? this guy is kind of weird.)
-.ft
-.PP
-.B pcap_inject()
+.Fn pcap_dispatch .
+.Pp
+.Fn pcap_inject
 uses
-.B write(2)
+.Xr write 2
 to inject a raw packet through the network interface.
-.PP
-.B pcap_immediate()
-sets ``immediate'' mode.
-If this isn't supported by the underlying packet capture, -1 is
+.Pp
+.Fn pcap_immediate
+sets
+.Dq immediate
+mode.  If this isn't supported by the underlying packet capture, \-1 is
 returned and the error text can be obtained with
-.B pcap_perror()
+.Fn pcap_perror
 or
-.BR pcap_geterr() .
-.PP
-.B pcap_compile()
+.Fn pcap_geterr .
+.Pp
+.Fn pcap_compile
 is used to compile the string
-.I str
+.Fa str
 into a filter program.
-.I program
+.Fa fp
 is a pointer to a
-.I bpf_program
+.Fa bpf_program
 struct and is filled in by
-.BR pcap_compile() .
-.I optimize
+.Fn pcap_compile .
+.Fa optimize
 controls whether optimization on the resulting code is performed.
-.I netmask
+.Fa netmask
 specifies the netmask of the local net.
-.PP
-.B pcap_setfilter()
-is used to specify the a filter program.
-.I fp
+.Pp
+.Fn pcap_setfilter
+is used to specify the filter program.
+.Fa fp
 is a pointer to an array of
-.I bpf_program
+.Fa bpf_program
 struct, usually the result of a call to
-.BR pcap_compile() .
-.PP
-.B pcap_loop()
+.Fn pcap_compile .
+.Pp
+.Fn pcap_loop
 is similar to
-.B pcap_dispatch()
+.Fn pcap_dispatch
 except it keeps reading packets until
-.I cnt
-packets are processed or an error occurs.
-A negative
-.I cnt
+.Fa cnt
+packets are processed or an error occurs. A negative
+.Fa cnt
 causes
-.B pcap_loop()
+.Fn pcap_loop
 to loop forever (or at least until an error occurs).
-.PP
-.B pcap_next()
+.Pp
+.Fn pcap_next
 returns a
-.I u_char
+.Fa u_char
 pointer to the next packet.
-.PP
-.B pcap_datalink()
+.Pp
+.Fn pcap_datalink
 returns the link layer type, e.g.
-.BR DLT_EN10MB .
-.PP
-.B pcap_snapshot()
+.Tn DLT_EN10MB .
+.Pp
+.Fn pcap_snapshot
 returns the snapshot length specified when
-.B pcap_open_live
+.Fn pcap_open_live
 was called.
-.PP
-.B pcap_is_swapped()
-returns true if the current ``savefile'' uses a different byte order
-than the current system.
-.PP
-.B pcap_major_version()
-returns the major number of the version of the pcap used to write the
-savefile.
-.PP
-.B pcap_minor_version()
-returns the minor number of the version of the pcap used to write the
-savefile.
-.PP
-.B pcap_file()
-returns the name of the ``savefile.''
-.PP
-.B int pcap_stats()
+.Pp
+.Fn pcap_is_swapped
+returns true if the current savefile
+uses a different byte order than the current system.
+.Pp
+.Fn pcap_major_version()
+returns the major number of the version of the pcap used to write the savefile.
+.Pp
+.Fn pcap_minor_version
+returns the minor number of the version of the pcap used to write the savefile.
+.Pp
+.Fn pcap_file
+returns the name of the savefile.
+.Pp
+.Fn pcap_stats
 returns 0 and fills in a
-.B pcap_stat
+.Fa pcap_stat
 struct with packet statistics. If there is an error or the underlying
-packet capture doesn't support packet statistics, -1 is returned and
+packet capture doesn't support packet statistics, \-1 is returned and
 the error text can be obtained with
-.B pcap_perror()
+.Fn pcap_perror
 or
-.BR pcap_geterr() .
-.PP
-.B pcap_fileno()
-returns the file descriptor number of the ``savefile.''
-.PP
-.B pcap_perror()
+.Fn pcap_geterr .
+.Pp
+.Fn pcap_fileno
+returns the file descriptor number of the savefile.
+.Pp
+.Fn pcap_perror
 prints the text of the last pcap library error on
-.BR stderr ,
+.Dv stderr ,
 prefixed by
-.IR prefix .
-.PP
-.B pcap_geterr()
+.Fa prefix .
+.Pp
+.Fn pcap_geterr
 returns the error text pertaining to the last pcap library error.
-.PP
-.B pcap_strerror()
+.Pp
+.Fn pcap_strerror
 is provided in case
-.BR strerror (1)
+.Xr strerror 1
 isn't available.
-.PP
-.B pcap_close()
+.Pp
+.Fn pcap_close
 closes the files associated with
-.I p
+.Fa p
 and deallocates resources.
-.PP
-.B pcap_dump_close()
-closes the ``savefile.''
-.PP
-.SH SEE ALSO
-tcpdump(8)
+.Pp
+.Fn pcap_dump_close
+closes the savefile.
+.Sh SEE ALSO
+.Xr tcpdump 8
 .\" , tcpslice(1)
-.SH BUGS
-.SH HISTORY