Reordered functions into more logical groups.

Author: sam-github

README.txt

@@ -31,8 +31,18 @@ See below, extracted from in-source comments.
 
 ** pcap - a binding to libpcap
 
-pcap._LIB_VERSION is the libpcap version string, as returned from pcap_lib_version().
 
+-- pcap.DLT = { EN10MB=DLT_EN10MB, [DLT_EN10MB] = "EN10MB", ... }
+
+DLT is a table of common DLT types. The DLT number and name are mapped to each other.
+
+DLT.EN10MB is Ethernet (of all speeds, the name is historical).
+DLT.LINUX_SLL can occur when capturing on Linux with a device of "any".
+
+See <http://www.tcpdump.org/linktypes.html> for more information.
+
+The numeric values are returned by cap:datalink() and accepted as linktype values
+in pcap.open_dead().
 
 
 -- cap = pcap.open_live(device, snaplen, promisc, timeout)
@@ -50,48 +60,24 @@ Open a source device to read packets from.
 
 
 
--- dumper:close()
-
-Manually close a dumper object, freeing it's resources (this will happen on
-garbage collection if not done explicitly).
-
-
--- pcap.DLT = { EN10MB=DLT_EN10MB, [DLT_EN10MB] = "EN10MB", ... }
-
-DLT is a table of common DLT types. The DLT number and name are mapped to each other.
-
-DLT.EN10MB is Ethernet (of all speeds, the name is historical).
-DLT.LINUX_SLL can occur when capturing on Linux with a device of "any".
-
-See <http://www.tcpdump.org/linktypes.html> for more information.
-
-The numeric values are returned by cap:datalink() and accepted as linktype values
-in pcap.open_dead().
-
-
--- cap = pcap.open_dead([linktype, [caplen]])
+-- cap = pcap.open_dead([linktype, [snaplen]])
 
 
 - linktype is one of the DLT numbers, and defaults to pcap.DLT.EN10MB.
 
-- caplen is the maximum size of packet, and defaults to ...
-
-caplen defaults to 0, meaning "no limit" (actually, its changed into
-65535 internally, which is what tcpdump does)
+- snaplen is the maximum size of packet, and defaults to 65535 (also,
+  a value of 0 is changed into 65535 internally, as tcpdump does).
 
 Open a pcap that doesn't read from either a live interface, or an offline pcap
 file. It can be used with cap:dump_open() to write a pcap file, or to compile a
 BPF program.
 
 
--- cap = pcap.open_offline([fname])
-
-fname defaults to "-", stdin.
+-- cap = pcap.open_offline(fname)
 
 Open a savefile to read packets from.
 
-Warning, fname defaulting to stdin causes unsuspecting users to
-think this API is hanging, when they don't actually have a pcap on stdin.
+An fname of "-" is a synonym for stdin.
 
 
 -- cap:close()
@@ -100,14 +86,6 @@ Manually close a cap object, freeing it's resources (this will happen on
 garbage collection if not done explicitly).
 
 
--- dumper = cap:dump_open([fname])
-
-fname defaults to "-", stdout.
-
-Note that the dumper object is independent of the cap object, once
-it's created.
-
-
 -- cap = cap:set_filter(filter, nooptimize)
 
 
@@ -125,6 +103,15 @@ function returns that as a number.
 See pcap.DLT for more information.
 
 
+-- snaplen = cap:snapshot()
+
+The snapshot length.
+
+For a live capture, snapshot is the maximum amount of the packet that will be
+captured, for writing of captures, it is the maximum size of a packet that can
+be written.
+
+
 -- fd = cap:getfd()
 
 Get a selectable file descriptor number which can be used to wait for packets.
@@ -167,12 +154,37 @@ Injects packet.
 Return is bytes sent on success, or nil,emsg on failure.
 
 
+-- dumper = cap:dump_open(fname)
+
+Open a dump file to write packets to.
+
+An fname of "-" is a synonym for stdout.
+
+Note that the dumper object is independent of the cap object, once
+it's created (so the cap object can be closed if its not going to
+be used).
+
+
+-- dumper:close()
+
+Manually close a dumper object, freeing it's resources (this will happen on
+garbage collection if not done explicitly).
+
+
 -- dumper = dumper:dump(pkt, [timestamp, [wirelen]])
 
-pkt to dump
+pkt is the packet to write to the dumpfile.
+
+timestamp of packet, defaults to 0, meaning the current time.
+
+wirelen was the original length of the packet before being truncated to header
+(defaults to length of header, the correct value if it was not truncated).
 
-timestamp of packet, defaults to 0, meaning the current time
-wire length of packet, defaults to pkt's length
+If only the header of the packet is available, wirelen should be set to the
+original packet length before it was truncated. Also, be very careful to not
+write a header that is longer than the caplen (which will 65535 unless a
+different value was specified in open_live or open_dead), the pcap file
+will not be valid.
 
 Returns self on sucess.
 Returns nil and an error msg on failure.
@@ -198,3 +210,8 @@ Combine seperate seconds and microseconds into one numeric seconds.
 -- seci, useci = pcap.secs2tv(secs)
 
 Split one numeric seconds into seperate seconds and microseconds.
+
+
+-- pcap._LIB_VERSION = ...
+
+The libpcap version string, as returned from pcap_lib_version().

pcap.c

@@ -28,9 +28,6 @@ THE POSSIBILITY OF SUCH DAMAGE.
 
 /*-
 ** pcap - a binding to libpcap
-
-pcap._LIB_VERSION is the libpcap version string, as returned from pcap_lib_version().
-
 */
 
 #include <assert.h>
@@ -146,51 +143,6 @@ static int checkpcapopen(lua_State* L, pcap_t** cap, const char* errbuf)
 
 /* Wrap pcap_t */
 
-/*-
--- cap = pcap.open_live(device, snaplen, promisc, timeout)
-
-Open a source device to read packets from.
-
-- device is the physical device (defaults to "any")
-- snaplen is the size to capture, where 0 means max possible (defaults to 0)
-- promisc is whether to set the device into promiscuous mode (default is false)
-- timeout is the timeout for reads in seconds (default is 0, return if no packets available)
-
-*/
-static int lpcap_open_live(lua_State *L)
-{
-    const char *device = luaL_optstring(L, 1, "any");
-    int snaplen = luaL_optint(L, 2, 0);
-    int promisc = lua_toboolean(L, 3);
-    int to_ms = 1000 * luaL_optint(L, 4, 0); /* convert to milliseconds */
-    pcap_t** cap = pushpcapopen(L);
-    char errbuf[PCAP_ERRBUF_SIZE];
-    if(snaplen == 0)
-        snaplen = 0xffff;
-    *cap = pcap_open_live(device, snaplen, promisc, to_ms, errbuf);
-    return checkpcapopen(L, cap, errbuf);
-}
-
-
-/*-
--- dumper:close()
-
-Manually close a dumper object, freeing it's resources (this will happen on
-garbage collection if not done explicitly).
-*/
-static int lpcap_dump_close (lua_State *L)
-{
-    pcap_dumper_t** dumper = luaL_checkudata(L, 1, L_PCAP_DUMPER_REGID);
-
-    if(*dumper)
-        pcap_dump_close(*dumper);
-
-    *dumper = NULL;
-
-    return 0;
-}
-
-
 /*-
 -- pcap.DLT = { EN10MB=DLT_EN10MB, [DLT_EN10MB] = "EN10MB", ... }
 
@@ -247,6 +199,32 @@ static void pcap_make_dlt(lua_State* L)
 }
 
 
+/*-
+-- cap = pcap.open_live(device, snaplen, promisc, timeout)
+
+Open a source device to read packets from.
+
+- device is the physical device (defaults to "any")
+- snaplen is the size to capture, where 0 means max possible (defaults to 0)
+- promisc is whether to set the device into promiscuous mode (default is false)
+- timeout is the timeout for reads in seconds (default is 0, return if no packets available)
+
+*/
+static int lpcap_open_live(lua_State *L)
+{
+    const char *device = luaL_optstring(L, 1, "any");
+    int snaplen = luaL_optint(L, 2, 0);
+    int promisc = lua_toboolean(L, 3);
+    int to_ms = 1000 * luaL_optint(L, 4, 0); /* convert to milliseconds */
+    pcap_t** cap = pushpcapopen(L);
+    char errbuf[PCAP_ERRBUF_SIZE];
+    if(snaplen == 0)
+        snaplen = 0xffff;
+    *cap = pcap_open_live(device, snaplen, promisc, to_ms, errbuf);
+    return checkpcapopen(L, cap, errbuf);
+}
+
+
 /*-
 -- cap = pcap.open_dead([linktype, [snaplen]])
 
@@ -310,37 +288,6 @@ static int lpcap_close (lua_State *L)
 }
 
 
-/*-
--- dumper = cap:dump_open(fname)
-
-Open a dump file to write packets to.
-
-An fname of "-" is a synonym for stdout.
-
-Note that the dumper object is independent of the cap object, once
-it's created (so the cap object can be closed if its not going to
-be used).
-*/
-static int lpcap_dump_open(lua_State *L)
-{
-    pcap_t* cap = checkpcap(L);
-    const char* fname = luaL_checkstring(L, 2);
-    pcap_dumper_t** dumper = lua_newuserdata(L, sizeof(*dumper));
-
-    *dumper = NULL;
-
-    luaL_getmetatable(L, L_PCAP_DUMPER_REGID);
-    lua_setmetatable(L, -2);
-
-    *dumper = pcap_dump_open(cap, fname);
-
-    if (!*dumper) {
-        return pusherr(L, cap);
-    }
-
-    return 1;
-}
-
 /* Current libpcap says to use PCAP_NETMASK_UNKNOWN if you don't know the
    netmask, older libpcaps says to use 0, so we do one or the other
    depending on whether the macro exists.
@@ -529,6 +476,57 @@ static pcap_dumper_t* checkdumper(lua_State* L)
     return *dumper;
 }
 
+/*-
+-- dumper = cap:dump_open(fname)
+
+Open a dump file to write packets to.
+
+An fname of "-" is a synonym for stdout.
+
+Note that the dumper object is independent of the cap object, once
+it's created (so the cap object can be closed if its not going to
+be used).
+*/
+static int lpcap_dump_open(lua_State *L)
+{
+    pcap_t* cap = checkpcap(L);
+    const char* fname = luaL_checkstring(L, 2);
+    pcap_dumper_t** dumper = lua_newuserdata(L, sizeof(*dumper));
+
+    *dumper = NULL;
+
+    luaL_getmetatable(L, L_PCAP_DUMPER_REGID);
+    lua_setmetatable(L, -2);
+
+    *dumper = pcap_dump_open(cap, fname);
+
+    if (!*dumper) {
+        return pusherr(L, cap);
+    }
+
+    return 1;
+}
+
+
+/*-
+-- dumper:close()
+
+Manually close a dumper object, freeing it's resources (this will happen on
+garbage collection if not done explicitly).
+*/
+static int lpcap_dump_close (lua_State *L)
+{
+    pcap_dumper_t** dumper = luaL_checkudata(L, 1, L_PCAP_DUMPER_REGID);
+
+    if(*dumper)
+        pcap_dump_close(*dumper);
+
+    *dumper = NULL;
+
+    return 0;
+}
+
+
 /*-
 -- dumper = dumper:dump(pkt, [timestamp, [wirelen]])
 
@@ -645,6 +643,11 @@ static int lpcap_secs2tv(lua_State* L)
     return 2;
 }
 
+/*-
+-- pcap._LIB_VERSION = ...
+
+The libpcap version string, as returned from pcap_lib_version().
+*/
 static const luaL_reg pcap_module[] =
 {
     {"open_live", lpcap_open_live},