See also:
pcap_open_offline(), pcap_open_dead(), pcap_findalldevs(), pcap_close()
pcap_t* pcap_open_offline ( const char * fname,
char * errbuf
)
Open a savefile in the tcpdump/libpcap format to read packets.
pcap_open_offline() is called to open a "savefile" for reading. fname specifies the name of the file to open. The file has the same format as those used by tcpdump(1) and tcpslice(1). The name "-" in a synonym for stdin. Alternatively, you may call pcap_fopen_offline() to read dumped data from an existing open stream fp. Note that on Windows, that stream should be opened in binary mode. errbuf is used to return error text and is only set when pcap_open_offline() or pcap_fopen_offline() fails and returns NULL.
See also:
pcap_open_live(), pcap_dump_open(), pcap_findalldevs(), pcap_close()
int pcap_parsesrcstr ( const char * source,
int * type,
char * host,
char * port,
char * name,
char * errbuf
)
Parse the source string and returns the pieces in which the source can be split.
This call is the other way round of pcap_createsrcstr(). It accepts a null-terminated string and it returns the parameters related to the source. This includes:
the type of the source (file, winpcap on a remote adapter, winpcap on local adapter), which is determined by the source prefix (PCAP_SRC_IF_STRING and so on)
the host on which the capture has to be started (only for remote captures)
the 'raw' name of the source (file name, name of the remote adapter, name of the local adapter), without the source prefix. The string returned does not include the type of the source itself (i.e. the string returned does not include "file://" or rpcap:// or such).
The user can omit some parameters in case it is not interested in them.
Parameters:
source,: a null-terminated string containing the WinPcap source. This source starts with an identifier according to the new Source Specification Syntax .
type,: pointer to an integer, which is used to return the code corrisponding to the selected source. The code will be one defined in the Source identification Codes .
In case the source string does not exists (i.e. 'source == NULL') or it is empty ('*source == NULL'), it returns PCAP_SRC_IF_LOCAL (i.e. you are ready to call pcap_open_live() ). This behavior is kept only for compatibility with older applications (e.g. tcpdump); therefore we suggest to move to the new syntax for sources.
This parameter can be NULL in case the user is not interested in that.
host,: user-allocated buffer (of size PCAP_BUF_SIZE) that is used to return the host name on which the capture has to be started. This value is meaningful only in case of remote capture; otherwise, the returned string will be empty (""). This parameter can be NULL in case the user is not interested in that.
port,: user-allocated buffer (of size PCAP_BUF_SIZE) that is used to return the port that has to be used by the RPCAP protocol to contact the other host. This value is meaningful only in case of remote capture and if the user wants to use a non-standard port; otherwise, the returned string will be empty (""). In case of remote capture, an emply string means "use the standard RPCAP port". This parameter can be NULL in case the user is not interested in that.
name,: user-allocated buffer (of size PCAP_BUF_SIZE) that is used to return the source name, without the source prefix. If the name does not exist (for example because source contains 'rpcap://' that means 'default local adapter'), it returns NULL. This parameter can be NULL in case the user is not interested in that.
errbuf,: pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one). This parameter can be NULL in case the user is not interested in that.
Returns:
'0' if everything is fine, '-1' if some errors occurred. The requested values (host name, network port, type of the source) are returned into the proper variables passed by reference.
void pcap_perror ( pcap_t * p,
char * prefix
)
print the text of the last pcap library error on stderr, prefixed by prefix.
See also:
pcap_geterr()
SOCKET pcap_remoteact_accept ( const char * address,
const char * port,
const char * hostlist,
char * connectinghost,
struct pcap_rmtauth * auth,
char * errbuf
)
Block until a network connection is accepted (active mode only).
This function has been defined to allow the client dealing with the 'active mode'. In other words, in the 'active mode' the server opens the connection toward the client, so that the client has to open a socket in order to wait for connections. When a new connection is accepted, the RPCAP protocol starts as usual; the only difference is that the connection is initiated by the server.
This function accepts only ONE connection, then it closes the waiting socket. This means that if some error occurs, the application has to call it again in order to accept another connection.
This function returns when a new connection (coming from a valid host 'connectinghost') is accepted; it returns error otherwise.
Parameters:
address,: a string that keeps the network address we have to bind to; usually it is NULL (it means 'bind on all local addresses').
port,: a string that keeps the network port on which we have to bind to; usually it is NULL (it means 'bind on the predefined port', i.e. RPCAP_DEFAULT_NETPORT_ACTIVE).
hostlist,: a string that keeps the host name of the host from whom we are expecting a connection; it can be NULL (it means 'accept connection from everyone'). Host names are separated by a whatever character in the RPCAP_HOSTLIST_SEP list.
connectinghost,: a user-allocated buffer that will contain the name of the host is trying to connect to us. This variable must be at least RPCAP_HOSTLIST_SIZE bytes..
auth,: a pointer to a pcap_rmtauth structure. This pointer keeps the information required to authenticate the RPCAP connection to the remote host.
errbuf,: a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one).
Returns:
The SOCKET identifier of the new control connection if everything is fine, a negative number if some errors occurred. The error message is returned into the errbuf variable. In case it returns '-1', this means 'everything is fine', but the host cannot be admitted. In case it returns '-2', in means 'unrecoverable error' (for example it is not able to bind the socket, or something like that). In case it returns '-3', it means 'authentication failed'. The authentication check is performed only if the connecting host is among the ones that are allowed to connect to this host.
The host that is connecting to us is returned into the hostlist variable, which ust be allocated by the user. This variable contains the host name both in case the host is allowed, and in case the connection is refused.
Warning:
Although this function returns the socket established by the new control connection, this value should not be used. This value will be stored into some libpcap internal variables and it will be managed automatically by the library. In other words, all the following calls to findalldevs() and pcap_open() will check if the host is among one that already has a control connection in place; if so, that one will be used.
This function has several problems if used inside a thread, which is stopped when this call is blocked into the accept(). In this case, the socket on which we accept connections is not freed (thread termination is a very dirty job), so that we are no longer able to accept other connections until the program (i.e. the process) stops. In order to solve the problem, call the pcap_remoteact_cleanup().
void pcap_remoteact_cleanup ( )
Clean the socket that is currently used in waiting active connections.
This function does a very dirty job. The fact is that is the waiting socket is not freed if the pcap_remoteaccept() is killed inside a new thread. This function is able to clean the socket in order to allow the next calls to pcap_remoteact_accept() to work.
This function is useful *only* if you launch pcap_remoteact_accept() inside a new thread, and you stops (not very gracefully) the thread (for example because the user changed idea, and it does no longer want to wait for an active connection). So, basically, the flow should be the following:
launch a new thread
call the pcap_remoteact_accept
if this new thread is killed, call pcap_remoteact_cleanup().
This function has no effects in other cases.
Returns:
None.
int pcap_remoteact_close ( const char * host,
char * errbuf
)
Drop an active connection (active mode only).
This function has been defined to allow the client dealing with the 'active mode'. This function closes an active connection that is still in place and it purges the host name from the 'activeHost' list. From this point on, the client will not have any connection with that host in place.
Parameters:
host,: a string that keeps the host name of the host for which we want to close the active connection.
errbuf,: a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one).
Returns:
'0' if everything is fine, '-1' if some errors occurred. The error message is returned into the errbuf variable.
int pcap_remoteact_list ( char * hostlist,
char sep,
int size,
char * errbuf
)
Return the hostname of the host that have an active connection with us (active mode only).
This function has been defined to allow the client dealing with the 'active mode'. This function returns the list of hosts that are currently having an active connection with us. This function is useful in order to delete an active connection that is still in place.
Parameters:
hostlist,: a user-allocated string that will keep the list of host that are currently connected with us.
sep,: the character that has to be sued as a separator between the hosts (',' for example).
size,: size of the hostlist buffer.
errbuf,: a pointer to a user-allocated buffer (of size PCAP_ERRBUF_SIZE) that will contain the error message (in case there is one).
Returns:
'0' if everything is fine, '-1' if some errors occurred. The error message is returned into the errbuf variable.
int pcap_sendpacket ( pcap_t * p,
u_char * buf,
int size
)
Send a raw packet.
This function allows to send a raw packet to the network. p is the interface that will be used to send the packet, buf contains the data of the packet to send (including the various protocol headers), size is the dimension of the buffer pointed by buf, i.e. the size of the packet to send. The MAC CRC doesn't need to be included, because it is transparently calculated and added by the network interface driver. The return value is 0 if the packet is succesfully sent, -1 otherwise.
See also:
pcap_open_live()
pcap_send_queue* pcap_sendqueue_alloc ( u_int memsize )
Allocate a send queue.
This function allocates a send queue, i.e. a buffer containing a set of raw packets that will be transimtted on the network with pcap_sendqueue_transmit().
memsize is the size, in bytes, of the queue, therefore it determines the maximum amount of data that the queue will contain.
Use pcap_sendqueue_queue() to insert packets in the queue.
See also:
pcap_sendqueue_queue(), pcap_sendqueue_transmit(), pcap_sendqueue_destroy()
void pcap_sendqueue_destroy ( pcap_send_queue * queue )
Destroy a send queue.
Deletes a send queue and frees all the memory associated with it.
See also:
pcap_sendqueue_alloc(), pcap_sendqueue_queue(), pcap_sendqueue_transmit()
int pcap_sendqueue_queue ( pcap_send_queue * queue,
const struct pcap_pkthdr * pkt_header,
const u_char * pkt_data
)
Add a packet to a send queue.
pcap_sendqueue_queue() adds a packet at the end of the send queue pointed by the queue parameter. pkt_header points to a pcap_pkthdr structure with the timestamp and the length of the packet, pkt_data points to a buffer with the data of the packet.
The pcap_pkthdr structure is the same used by WinPcap and libpcap to store the packets in a file, therefore sending a capture file is straightforward. 'Raw packet' means that the sending application will have to include the protocol headers, since every packet is sent to the network 'as is'. The CRC of the packets needs not to be calculated, because it will be transparently added by the network interface.
See also:
pcap_sendqueue_alloc(), pcap_sendqueue_transmit(), pcap_sendqueue_destroy()
u_int pcap_sendqueue_transmit ( pcap_t * p,
pcap_send_queue * queue,
int sync
)
Send a queue of raw packets to the network.
This function transmits the content of a queue to the wire. p is a pointer to the adapter on which the packets will be sent, queue points to a pcap_send_queue structure containing the packets to send (see pcap_sendqueue_alloc() and pcap_sendqueue_queue()), sync determines if the send operation must be synchronized: if it is non-zero, the packets are sent respecting the timestamps, otherwise they are sent as fast as possible.
The return value is the amount of bytes actually sent. If it is smaller than the size parameter, an error occurred during the send. The error can be caused by a driver/adapter problem or by an inconsistent/bogus send queue.
Note:
Using this function is more efficient than issuing a series of pcap_sendpacket(), because the packets are buffered in the kernel driver, so the number of context switches is reduced. Therefore, expect a better throughput when using pcap_sendqueue_transmit.
When Sync is set to TRUE, the packets are synchronized in the kernel with a high precision timestamp. This requires a non-negligible amount of CPU, but allows normally to send the packets with a precision of some microseconds (depending on the accuracy of the performance counter of the machine). Such a precision cannot be reached sending the packets with pcap_sendpacket().
See also:
pcap_sendqueue_alloc(), pcap_sendqueue_queue(), pcap_sendqueue_destroy()
int pcap_set_datalink ( pcap_t * p,
int dlt
)
Set the current data link type of the pcap descriptor to the type specified by dlt. -1 is returned on failure.
int pcap_setbuff ( pcap_t * p,
int dim
)
Set the size of the kernel buffer associated with an adapter.
dim specifies the size of the buffer in bytes. The return value is 0 when the call succeeds, -1 otherwise. If an old buffer was already created with a previous call to pcap_setbuff(), it is deleted and its content is discarded. pcap_open_live() creates a 1 MByte buffer by default.
See also:
pcap_open_live(), pcap_loop(), pcap_dispatch()
int pcap_setfilter ( pcap_t * p,
struct bpf_program * fp
)
Associate a filter to a capture.
pcap_setfilter() is used to specify a filter program. fp is a pointer to a bpf_program struct, usually the result of a call to pcap_compile(). -1 is returned on failure, in which case pcap_geterr() may be used to display the error text; 0 is returned on success.
See also:
pcap_compile(), pcap_compile_nopcap()
int pcap_setmintocopy ( pcap_t * p,
int size
)
Set the minumum amount of data received by the kernel in a single call.
pcap_setmintocopy() changes the minimum amount of data in the kernel buffer that causes a read from the application to return (unless the timeout expires). If the value of size is large, the kernel is forced to wait the arrival of several packets before copying the data to the user. This guarantees a low number of system calls, i.e. low processor usage, and is a good setting for applications like packet-sniffers and protocol analyzers. Vice versa, in presence of a small value for this variable, the kernel will copy the packets as soon as the application is ready to receive them. This is useful for real time applications that need the best responsiveness from the kernel.
See also:
pcap_open_live(), pcap_loop(), pcap_dispatch()
int pcap_setmode ( pcap_t * p,
int mode
)
Set the working mode of the interface p to mode.
Valid values for mode are MODE_CAPT (default capture mode) and MODE_STAT (statistical mode). See the tutorial "ref wpcap_tut9" for details about statistical mode.
int pcap_setnonblock ( pcap_t * p,
int nonblock,
char * errbuf
)
Switch between blocking and nonblocking mode.
pcap_setnonblock() puts a capture descriptor, opened with pcap_open_live(), into "non-blocking" mode, or takes it out of "non-blocking" mode, depending on whether the nonblock argument is non-zero or zero. It has no effect on "savefiles". If there is an error, -1 is returned and errbuf is filled in with an appropriate error message; otherwise, 0 is returned. In "non-blocking" mode, an attempt to read from the capture descriptor with pcap_dispatch() will, if no packets are currently available to be read, return 0 immediately rather than blocking waiting for packets to arrive. pcap_loop() and pcap_next() will not work in "non-blocking" mode.
See also:
pcap_getnonblock(), pcap_dispatch()
struct pcap_samp* pcap_setsampling ( pcap_t * p )
Define a sampling method for packet capture.
This function allows applying a sampling method to the packet capture process. The currently sampling methods (and the way to set them) are described into the struct pcap_samp. In other words, the user must set the appropriate parameters into it; these will be applied as soon as the capture starts.
Warning:
Sampling parameters cannot be changed when a capture is active. These parameters must be applied before starting the capture. If they are applied when the capture is in progress, the new settings are ignored.
Sampling works only when capturing data on Win32 or reading from a file. It has not been implemented on other platforms. Sampling works on remote machines provided that the probe (i.e. the capturing device) is a Win32 workstation.
int pcap_snapshot ( pcap_t * p )
Return the dimension of the packet portion (in bytes) that is delivered to the application.
pcap_snapshot() returns the snapshot length specified when pcap_open_live was called.
See also:
pcap_open_live(), pcap_compile(), pcap_compile_nopcap()
int pcap_stats ( pcap_t * p,
struct pcap_stat * ps
)
Return statistics on current capture.
pcap_stats() returns 0 and fills in a pcap_stat struct. The values represent packet statistics from the start of the run to the time of the call. If there is an error or the underlying packet capture doesn't support packet statistics, -1 is returned and the error text can be obtained with pcap_perror() or pcap_geterr(). pcap_stats() is supported only on live captures, not on "savefiles"; no statistics are stored in "savefiles", so no statistics are available when reading from a "savefile".
See also:
pcap_stats_ex(), pcap_open_live()
struct pcap_stat* pcap_stats_ex ( pcap_t * p,
int * pcap_stat_size
)
Return statistics on current capture.
pcap_stats_ex() extends the pcap_stats() allowing to return more statistical parameters than the old call. One of the advantages of this new call is that the pcap_stat structure is not allocated by the user; instead, it is returned back by the system. This allow to extend the pcap_stat structure without affecting backward compatibility on older applications. These will simply check at the values of the members at the beginning of the structure, while only newest applications are able to read new statistical values, which are appended in tail.
To be sure not to read a piece of mamory which has not been allocated by the system, the variable pcap_stat_size will return back the size of the structure pcap_stat allocated by the system.
Parameters:
p,: pointer to the pcap_t currently in use.
pcap_stat_size,: pointer to an integer that will contain (when the function returns back) the size of the structure pcap_stat as it has been allocated by the system.
Returns:
: a pointer to a pcap_stat structure, that will contain the statistics related to the current device. The return value is NULL in case of errors, and the error text can be obtained with pcap_perror() or pcap_geterr().
Warning:
pcap_stats_ex() is supported only on live captures, not on "savefiles"; no statistics are stored in "savefiles", so no statistics are available when reading from a "savefile".
See also:
pcap_stats()
char* pcap_strerror ( int error )
Provided in case strerror() isn't available.
See also:
pcap_perror(), pcap_geterr()