Module ewpcap

Copyright © 2012-2021 Michael Santos <michael.santos@gmail.com>

Data Types

ewpcap_resource()

ewpcap_resource() = #ewpcap_resource{}

ewpcap_stat()

ewpcap_stat() = #ewpcap_stat{}

filter_options()

filter_options() = [{optimize, boolean()} | {netmask, non_neg_integer()}]

open_options()

open_options() = [{snaplen, non_neg_integer()} | {promisc, boolean()} | {to_ms, non_neg_integer()} | {filter, iodata()} | {buffer, non_neg_integer()} | {monitor, boolean()} | {time_unit, time_unit()} | {immediate, boolean()} | {timeout, immediate | infinity | non_neg_integer()}]

time_unit()

time_unit() = timestamp | microsecond

Function Index

close/1Closes the pcap descriptor.
dev/0Returns the default device used by PCAP.
dirty_scheduler_enabled/0Indicates whether ewpcap is using the dirty scheduler.
filter/2Compile a PCAP filter and apply it to the PCAP descriptor.
filter/3
getifaddrs/0Returns a list of interfaces.
open/0Open a network interface using the default device.
open/1Open a network interface using the specified device.
open/2Open a network interface and begin receiving packets.
read/1Convenience function wrapping receive, returning the packet contents.
read/2
stats/1To use the return value as a record, include the header:.
write/2Write the packet to the network.

Function Details

close/1

close(Ewpcap_resource::ewpcap_resource()) -> ok

Closes the pcap descriptor.

dev/0

dev() -> {ok, string()} | {error, string()}

Returns the default device used by PCAP.

dirty_scheduler_enabled/0

dirty_scheduler_enabled() -> boolean()

Indicates whether ewpcap is using the dirty scheduler

filter/2

filter(Res::ewpcap_resource(), Filter::iodata()) -> ok | {error, string() | enomem}

Compile a PCAP filter and apply it to the PCAP descriptor.

Since the library passes the filter string to pcap_compile(3PCAP) directly, any bugs in pcap_compile() may cause the Erlang VM to crash. Do not use filters from untrusted sources.

Filters are limited to 8192 bytes by default since it may be possible for very large filters to cause a stack overflow. For example:

 ewpcap:open(<<>>, [{filter, string:copies("ip and ", 50000) ++ "ip"}, {limit, -1}])

filter/3

filter(Ewpcap_resource::ewpcap_resource(), Filter::iodata(), Options::filter_options()) -> ok | {error, string() | enomem}

getifaddrs/0

getifaddrs() -> {ok, [] | [{string(), [proplists:proplist()]}]} | {error, string()}

Returns a list of interfaces. Ifname can be used as the first parameter to open/1 and open/2.

This function is modelled on inet:getifaddrs/0 but uses pcap_findalldevs(3PCAP) to look up the interface attributes:

* getifaddrs/0 may return pseudo devices, such as the "any" device on Linux

* getifaddrs/0 will only return the list of devices that can be used with open/1 and open/2. An empty list ({ok, []}) may be returned if the user does not have permission to open any of the system interfaces

open/0

open() -> {ok, ewpcap_resource()} | {error, string() | enomem}

Open a network interface using the default device.

open/0 defaults to:

* promiscuous mode disabled

* a snaplen (packet length) of 65535 bytes

* uses immediate mode

* the time unit is an erlang timestamp in the same format as now/0

* no filter (all packets are received)

See open/2.

open/1

open(Dev::iodata()) -> {ok, ewpcap_resource()} | {error, string() | enomem}

Open a network interface using the specified device.

open/1 defaults to:

* promiscuous mode disabled

* a snaplen (packet length) of 65535 bytes

* uses immediate mode

* the time unit is an erlang timestamp in the same format as now/0

* no filter (all packets are received)

See open/2.

open/2

open(Dev::iodata(), Options::open_options()) -> {ok, ewpcap_resource()} | {error, string() | enomem}

Open a network interface and begin receiving packets.

The returned Socket in the 'ok' tuple must be kept by the process. When the socket goes out of scope, the pcap filter will be shut down and all resources associated with the socket will be freed. See also close/1.

Dev is the name of the network device. If an empty binary (<<>>) is passed in, pcap will select a default interface.

If an error occurs, the PCAP string describing the error is returned to the caller.

The timeout` option sets `pcap_set_timeout(3PCAP)` and `pcap_set_immediate_mode(3PCAP)`. By default, ewpcap uses `immediate` mode and returns packets as they are received. Setting timeout to an integer value disables `immediate` mode and buffers any packets until either the timeout is reached or the buffer is filled. If ewpcap is dropping packets (see stats/1), the PCAP buffer size can be increased (should be some multiple of the snaplen). Wireless devices can be set to use monitor mode (rfmon) by passing in themonitor' option.

The timestamp in the message can be formatted either as a now/0 tuple or returned in microseconds.

For filter options, see filter/3.

Packets are returned as messages to the caller:

{ewpcap, Ref, DatalinkType, Time, Length, Packet}

Ref is a reference identifying the socket handle.

The DataLinkType is an integer representing the link layer, e.g., ethernet, Linux cooked socket.

The Time is a tuple in the same format as erlang:now/0, {MegaSecs, Secs, MicroSecs} or microseconds.

The Length corresponds to the actual packet length on the wire. The captured packet may have been truncated. To get the captured packet length, use byte_size(Packet).

The Packet is a binary holding the captured data.

Errors will be sent to the caller and the pcap filter will be terminated:

{ewpcap_error, Ref, Error}

read/1

read(Res::ewpcap_resource()) -> {ok, binary()} | {error, string()}

Convenience function wrapping receive, returning the packet contents.

read/2

read(Ewpcap_resource::ewpcap_resource(), Timeout::infinity | non_neg_integer()) -> {ok, binary()} | {error, string() | eagain}

stats/1

stats(Ewpcap_resource::ewpcap_resource()) -> {ok, ewpcap_stat()} | {error, string()}

To use the return value as a record, include the header:

-include_lib("ewpcap/include/ewpcap.hrl").

stats/1 returns statistics about dropped packets. See pcap_stats(3PCAP) for details.

The ewpcap_stat records contains these fields:

recv : number of packets received

drop : number of packets dropped due to insufficient buffer

ifdrop : number of packets dropped by the network interface

capt : always 0 (was number of packets received by the application (Win32 only))

write/2

write(Ewpcap_resource::ewpcap_resource(), Data::iodata()) -> ok | {error, string()}

Write the packet to the network. See pcap_sendpacket(3PCAP).


Generated by EDoc