TABLE OF CONTENTS miamipcap.library/--general information-- miamipcap.library/--PCap callbacks-- miamipcap.library/MiamiPCapAmigaBPFHandle miamipcap.library/MiamiPCapAmigaDump miamipcap.library/MiamiPCapAmigaDumpClose miamipcap.library/MiamiPCapAmigaDumpOpen miamipcap.library/MiamiPCapAmigaFile miamipcap.library/MiamiPCapBPFImage miamipcap.library/MiamiPCapClose miamipcap.library/MiamiPCapCompile miamipcap.library/MiamiPCapDatalink miamipcap.library/MiamiPCapDispatch miamipcap.library/MiamiPCapGeterr miamipcap.library/MiamiPCapInit miamipcap.library/MiamiPCapIsSwapped miamipcap.library/MiamiPCapLookupdev miamipcap.library/MiamiPCapLookupnet miamipcap.library/MiamiPCapLoop miamipcap.library/MiamiPCapMajorVersion miamipcap.library/MiamiPCapMinorVersion miamipcap.library/MiamiPCapNext miamipcap.library/MiamiPCapOpenLive miamipcap.library/MiamiPCapOpenOffline miamipcap.library/MiamiPCapPerror miamipcap.library/MiamiPCapSetCallbackType miamipcap.library/MiamiPCapSetFilter miamipcap.library/MiamiPCapSnapshot miamipcap.library/MiamiPCapStats miamipcap.library/MiamiPCapStrerror miamipcap.library/--general information-- Miami:libs/miamipcap.library is an implementation of the libpcap software suite, a packet monitoring mechanism built on top of BPF, which provides high-level filtering functions. MiamiPCap is implemented on top of MiamiBPF, which in turn uses the packet monitoring mechanism in Miami 1.9.3 and above, i.e. MiamiPCap only works with the registered version of Miami. The main advantage of MiamiPCap over lower-level packet monitoring mechanisms is that MiamiPCap allows an application to specify ASCII filter strings to select a set of packets, e.g. something like icmp[0] != 8 and icmp!= 0 which would select all ICMP packets that are not echo requests or replies. MiamiPCap has a built-in compiler and code optimizer to convert such ASCII strings into the binary BPF program code sequences required by the underlying MiamiBPF suite. The primary use of MiamiPCap is in programs such as TCPDump. miamipcap.library/--PCap callbacks-- miamipcap.library/--PCap callbacks-- PCap calls a callback function in your program for each packet received, which has not been filtered out. The proper declaration of the callback function is: void pcapcallback(void *user,struct pcap_pkthdr *pkthdr,char *packet); The default CPU type for callbacks is MIAMICPU_M68KREG (parameters passed on the stack), regardless of which API is used. miamipcap.library versions 3 and higher support the new call MiamiPCapSetCallbackType() to change the CPU type used for callbacks. miamipcap.library/MiamiPCapAmigaBPFHandle NAME MiamiPCapAmigaBPFHandle -- returns the BPF handle associated with a pcap unit SYNOPSIS bpfhandle = MiamiPCapAmigaBPFHandle( p ); D0 A0 int MiamiPCapAmigaBPFHandle( pcap_t *p ); FUNCTION Returns the BPF handle associated with a pcap unit. INPUTS p - pcap unit handle RESULT bpfhandle (D0) - BPF handle miamipcap.library/MiamiPCapAmigaDump miamipcap.library/MiamiPCapAmigaDump NAME MiamiPCapAmigaDump -- dump a packet to a save file SYNOPSIS MiamiPCapAmigaDump( filehandle, h, sp ); A0 A1 A2 void MiamiPCapAmigaDump( pcap_dumper_t *filehandle, struct pcap_pkthdr *h, u_char *sp ); FUNCTION Dumps the packet specified in sp to the specified save file, using the packet header passed in h. The file handle MUST have been created by an earlier call to MiamiPCapAmigaDumpOpen. INPUTS filehandle - file handle h - packet header sp - data miamipcap.library/MiamiPCapAmigaDumpClose NAME MiamiPCapAmigaDumpClose -- closes an open save file SYNOPSIS MiamiPCapAmigaDumpClose( filehandle ); A0 void MiamiPCapAmigaDumpClose( pcap_dumper_t *filehandle ); FUNCTION Closes the indicated save file. The file must have been opened earlier by a call to MiamiPCapAmigaDumpOpen. INPUTS filehandle - file handle miamipcap.library/MiamiPCapAmigaDumpOpen NAME MiamiPCapAmigaDumpOpen -- opens a save file to dump packets SYNOPSIS filehandle = MiamiPCapAmigaDumpOpen( p, fname ); D0 A0 A1 pcap_dumper_t *MiamiPCapAmigaDumpOpen( pcap_t *p, char *fname ); FUNCTION Opens a save file for the specified unit. The returned file handle can later be used in MiamiPCapAmigaDump calls to dump packets to the save file. A return value of NULL indicates that an error has occured. The filehandle later needs to be closed by calling MiamiPCapAmigaDumpClose. INPUTS p - pcap unit handle fname - file name RESULT filehandle (D0) - file handle miamipcap.library/MiamiPCapAmigaFile miamipcap.library/MiamiPCapAmigaFile NAME MiamiPCapAmigaFile -- return Amiga file handle for save file SYNOPSIS handle = MiamiPCapAmigaFile( p ); D0 A0 BPTR MiamiPCapAmigaFile( pcap_t *p ); FUNCTION returns the Amiga file handle for the current save file. For pOS a (struct pOS_FileHandle *) is returned instead of a BPTR. INPUTS p - pcap unit handle RESULT handle (D0) - filehandle miamipcap.library/MiamiPCapBPFImage miamipcap.library/MiamiPCapBPFImage NAME MiamiPCapBPFImage -- disassemble a compiled BPF instruction SYNOPSIS d = MiamiPCapBPFImage( pi, n ); D0 A0 D0 char *MiamiPCapBPFImage( struct bpf_insn *pi, int n ); FUNCTION Disassembles a compiled BPF instruction into a text string. The two parameters are the BPF instruction and the offset (PC) of the instruction relative to the BPF program. The returned string contains the disassembled text representing the BPF instruction. The text pointer points to static space that does not have to be freed. It is overwritten with the next call to MiamiPCapBPFImage. INPUTS pi - bpf instruction n - instruction offset (PC) RESULT d (D0) - disassembled code miamipcap.library/MiamiPCapClose miamipcap.library/MiamiPCapClose NAME MiamiPCapClose -- closes a pcap unit SYNOPSIS MiamiPCapClose( p ); A0 void MiamiPCapClose( pcap_t *p ); FUNCTION Closes a pcap unit which was previously opened by a call to MiamiPCapOpenLive or MiamiPCapOpenOffline. INPUTS p - pcap unit handle miamipcap.library/MiamiPCapCompile miamipcap.library/MiamiPCapCompile NAME MiamiPCapCompile -- compile a filter string into a BPF program SYNOPSIS error = MiamiPCapCompile( p, program, buf, optimize, mask ); D0 A0 A1 A2 D0 D1 int MiamiPCapCompile( pcap_t *p, struct bpf_program *program, char *buf, int optimize, bpf_u_int32 mask ); FUNCTION Compiles the filter string passed in 'buf' into a BPF program. The resulting program is stored in the structure passed in 'program'. If 'optimize' is different from zero then the BPF code optimizer is executed on the resulting program to compress the code. 'optimize' should always be used except if you suspect a bug in the optimizer. 'mask' is the netmask for the interface the program is supposed to execute on. The function returns zero on success and a non-zero value on failure. INPUTS p - pcap unit handle program - BPF program structure buf - filter string optimize - optimize flag mask - netmask RESULT error (D0) - error code miamipcap.library/MiamiPCapDatalink miamipcap.library/MiamiPCapDatalink NAME MiamiPCapDatalink -- return the datalink layer packet type SYNOPSIS type = MiamiPCapDatalink( p ); D0 A0 int MiamiPCapDatalink( pcap_t *p ); FUNCTION returns the datalink layer packet type, i.e. one of the DLT_... constants in . For MiamiBPF the only possible value is currently DLT_MIAMI. INPUTS p - pcap unit handle RESULT type (D0) - type miamipcap.library/MiamiPCapDispatch miamipcap.library/MiamiPCapDispatch NAME MiamiPCapDispatch -- collect and process packets SYNOPSIS count = MiamiPCapDispatch( p, cnt, callback, user ); D0 A0 D0 A1 A2 int MiamiPCapDispatch( pcap_t *p, int cnt, pcap_handler callback, u_char *user ); FUNCTION Collect and process packets for the specified pcap unit. cnt specifies the maximum number of packets to process before returning. A cnt of -1 processes all the packets received in one buffer. A cnt of 0 processes all packets until an error occurs (or EOF is reached for a save file). callback specifies a PCap callback functions, as explained in -- PCap callbacks --. The parameter 'user' is the user parameter for the callback function. The returned value contains the number of packets read. 0 is returned if EOF is reached in a save file. -1 is returned to indicate an error. INPUTS p - pcap unit handle cnt - maximum number of packets callback - packet callback user - user data for callback RESULT count (D0) - packet count miamipcap.library/MiamiPCapGeterr miamipcap.library/MiamiPCapGeterr NAME MiamiPCapGeterr -- returns the current error string buffer SYNOPSIS errbuf = MiamiPCapGeterr( p ); D0 A0 char *MiamiPCapGeterr( pcap_t *p ); FUNCTION Returns a pointer to the current error string buffer, i.e. the ebuf parameter for the MiamiPCapOpenLive or MiamiPCapOpenOffline call INPUTS p - pcap unit handle RESULT errbuf (D0) - error buffer miamipcap.library/MiamiPCapInit miamipcap.library/MiamiPCapInit NAME MiamiPCapInit -- initialize MiamiPCap SYNOPSIS MiamiPCapInit( MiamiBase, SocketBase ); A0 A0 void MiamiPCapInit( struct Library *MiamiBase, struct Library *SocketBase ); FUNCTION Initializes MiamiPCap for use. You MUST call this function before calling any other function in miamipcap.library. INPUTS MiamiBase - Library base of miami.library SocketBase - Library base of bsdsocket.library NOTE You need to open miami.library V6 or higher and bsdsocket.library V4 or higher before calling this function. Mind the version numbers ! Using miamipcap.library with older library versions will cause crashes. miamipcap.library/MiamiPCapIsSwapped miamipcap.library/MiamiPCapIsSwapped NAME MiamiPCapIsSwapped -- check byte order of save file SYNOPSIS bool = MiamiPCapIsSwapped( p ); D0 A0 int MiamiPCapIsSwapped( pcap_t *p ); FUNCTION returns TRUE if the save file for this pcap unit uses a different byte order than the current system, and FALSE if the byte order is the same. INPUTS p - pcap unit handle RESULT bool (D0) - bool miamipcap.library/MiamiPCapLookupdev miamipcap.library/MiamiPCapLookupdev NAME MiamiPCapLookupdev -- finds a suitable interface name SYNOPSIS name = MiamiPCapLookupdev( ebuf ); D0 A0 char *MiamiPCapLookupdev( char *ebuf ); FUNCTION Finds a suitable interface name for use with MiamiPCap, that can be used as a default name if the user has not explicitly specified an interface. A NULL return value indicates that an error has occured. If the return value is non-NULL, then it is a pointer to a valid interface name in static storage, i.e. the pointer does not have to be freed, but the name will be overwritten by future calls to MiamiPCapLookupdev. INPUTS ebuf - buffer for error string RESULT name (D0) - interface name miamipcap.library/MiamiPCapLookupnet miamipcap.library/MiamiPCapLookupnet NAME MiamiPCapLookupnet -- finds the interface address and netmask SYNOPSIS error = MiamiPCapLookupnet( device, netp, maskp, ebuf ); D0 A0 A1 A2 A3 int MiamiPCapLookupnet( char *device, bpf_u_int32 *netp, bpf_u_int32 *maskp, char *ebuf ); FUNCTION Finds the interface (IP) address and the netmask for the specified interface. The return code is zero for success and non-zero for failure, in which case the error buffer will contain an error message. The pointers netp and maskp need to point to variables of type bpf_u_int32, which will be filled with the IP address and netmask of the specified interface, respectively. INPUTS device - interface name netp - pointer to address maskp - pointer to netmask ebuf - buffer for error string RESULT error (D0) - error code miamipcap.library/MiamiPCapLoop miamipcap.library/MiamiPCapLoop NAME MiamiPCapLoop -- loop to collect and process packets SYNOPSIS count = MiamiPCapLoop( p, cnt, callback, user ); D0 A0 D0 A1 A2 int MiamiPCapLoop( pcap_t *p, int cnt, pcap_handler callback, u_char *user ); FUNCTION Same as MiamiPCapDispatch, but with one difference: MiamiPCapDispatch returns as soon as some packets have been read (or another condition such as a timeout or an error has occured). MiamiPCapLoop keeps reading until cnt packets have been read or an error has occured. INPUTS p - pcap unit handle cnt - number of packets callback - packet callback user - user data for callback RESULT count (D0) - packet count miamipcap.library/MiamiPCapMajorVersion NAME MiamiPCapMajorVersion -- return major version number for save file SYNOPSIS version = MiamiPCapMajorVersion( p ); D0 A0 int MiamiPCapMajorVersion( pcap_t *p ); FUNCTION returns the major version number of the pcap used to write the save file. INPUTS p - pcap unit handle RESULT version (D0) - version miamipcap.library/MiamiPCapMinorVersion NAME MiamiPCapMinorVersion -- return minor version number for save file SYNOPSIS version = MiamiPCapMinorVersion( p ); D0 A0 int MiamiPCapMinorVersion( pcap_t *p ); FUNCTION returns the minor version number of the pcap used to write the save file. INPUTS p - pcap unit handle RESULT version (D0) - version miamipcap.library/MiamiPCapNext miamipcap.library/MiamiPCapNext NAME MiamiPCapNext -- read one packet SYNOPSIS packet = MiamiPCapNext( p, h ); D0 A0 A1 u_char *MiamiPCapNext( pcap_t *p, struct pcap_pkthdr *h ); FUNCTION Similar to MiamiPCapDispatch, but reads only a single packet and returns the pointer to the packet data. No callback function is called. The specified packet header is used as a template when reading the packet. INPUTS p - pcap unit handle h - packet header RESULT packet (D0) - packet data miamipcap.library/MiamiPCapOpenLive miamipcap.library/MiamiPCapOpenLive NAME MiamiPCapOpenLive -- open a live pcap unit SYNOPSIS p = MiamiPCapOpenLive( device, snaplen, promisc, toms, ebuf ); D0 A0 D0 D1 D2 A1 pcap_t *MiamiPCapOpenLive( char *device, int snaplen, int promisc, int toms, char *ebuf ); FUNCTION Opens a live PCap monitoring unit, for the specified interface. A return value of NULL indicates that an error has occured, in which case the buffer bassed in ebuf will contain an ASCII error message. snaplen is the maximum packet size you want PCap to preserve. promisc is a boolean variable indicating promiscuous mode and currently MUST be zero. Promiscuous mode is not currently supported because of limitations in the Amiga SANA-II standard. If toms is a non-zero value then it is considered a read timeout in milliseconds for later calls to the packet monitoring functions. A value of zero means 'no timeout', i.e. wait indefinitely. The error string buffer passed to MiamiPCapOpenLive is used not only for this single function call, but for ALL error strings resulting from future function calls for this pcap unit. INPUTS device - interface name snaplen - maximum packet length to copy promisc - promisc mode, currently MUST be zero toms - timeout in milliseconds ebuf - buffer for error string RESULT p (D0) - pcap unit handle miamipcap.library/MiamiPCapOpenOffline miamipcap.library/MiamiPCapOpenOffline NAME MiamiPCapOpenOffline -- open a savefile for reading SYNOPSIS p = MiamiPCapOpenOffline( fname, ebuf ); D0 A0 A1 pcap_t *MiamiPCapOpenOffline( char *fname, char *ebuf ); FUNCTION Opens an offline PCap monitoring unit. Packets are read from the specified file, not from the network. The file must have been created by MiamiPCap earlier. A return value of NULL indicates that an error has occured, in which case the buffer bassed in ebuf will contain an ASCII error message. The error string buffer passed to MiamiPCapOpenLive is used not only for this single function call, but for ALL error strings resulting from future function calls for this pcap unit. INPUTS fname - file name ebuf - buffer for error string RESULT p (D0) - pcap unit handle miamipcap.library/MiamiPCapPerror miamipcap.library/MiamiPCapPerror NAME MiamiPCapPerror -- prints the current pcap error string to the console SYNOPSIS MiamiPCapPerror( p, prefix ); A0 A1 void MiamiPCapPerror( pcap_t *p, char *prefix ); FUNCTION Prints the current pcap error string to the console, in the same format used by the Un*x perror() function call. INPUTS p - pcap unit handle prefix - error prefix miamipcap.library/MiamiPCapSetCallbackType NAME MiamiPCapSetCallbackType -- set the CPU for callbacks (V3) SYNOPSIS success = MiamiPCapSetCallbackType( pi, c ); D0 A0 D0 long MiamiPCapSetCallbackType( pcap_t *pi, long c ); FUNCTION Set the CPU used for callbacks, i.e. one of MIAMICPU_... The default CPU is MIAMICPU_M68KREG, regardless of which API (68k or PPC) is used. Other CPU types require special support in miamipcap.library and Miami. If the requested CPU is not supported for callbacks then FALSE is returned. Otherwise TRUE is returned and all subsequent callbacks use the new CPU calling conventions. INPUTS pi - pcap unit handle c - CPU type RESULT success (D0) - success indicator miamipcap.library/MiamiPCapSetFilter miamipcap.library/MiamiPCapSetFilter NAME MiamiPCapSetFilter -- attach a program to a pcap unit as a filter SYNOPSIS error = MiamiPCapSetFilter( p, prog ); D0 A0 A1 int MiamiPCapSetFilter( pcap_t *p, struct bpf_program *prog ); FUNCTION Ataches a compiled program to the specified pcap unit as a filter. The program has to be a valid BPF program, typically returned by a previous call to MiamiPCapCompile. The new filter replaces the previous filter (if any). A return code of zero indicates success, a non-zero return code indicates failure. INPUTS p - pcap unit handle prog - compiled program RESULT error (D0) - error code miamipcap.library/MiamiPCapSnapshot miamipcap.library/MiamiPCapSnapshot NAME MiamiPCapSnapshot -- return the maximum snapshot length SYNOPSIS len = MiamiPCapSnapshot( p ); D0 A0 int MiamiPCapSnapshot( pcap_t *p ); FUNCTION returns the maximum packet length used for snapshot (i.e. the value passed in the snaplen parameter to MiamiPCapOpenLive. INPUTS p - pcap unit handle RESULT len (D0) - length miamipcap.library/MiamiPCapStats miamipcap.library/MiamiPCapStats NAME MiamiPCapStats -- return packet statistics SYNOPSIS error = MiamiPCapStats( p, st ); D0 A0 A1 int MiamiPCapStats( pcap_t *p, pcap_stat *st ); FUNCTION Returns statistics for the specified pcap unit handle, by filling in the statistics structure passed to the function. If the returned error code is 0 then the contents of the statistics structure are valid. INPUTS p - pcap unit handle st - statistics RESULT error (D0) - error code miamipcap.library/MiamiPCapStrerror miamipcap.library/MiamiPCapStrerror NAME MiamiPCapStrerror -- converts an error number to an error string SYNOPSIS errstr = MiamiPCapStrerror( errnum ); D0 D0 char *MiamiPCapStrerror( int errnum ); FUNCTION Converts an error number into an error string. The returned pointer points to static storage and does not have to be freed. It is overwritten with the next call to MiamiPCapStrerror. The returned pointer is independent of pcap units and NOT identical to the error string buffer for any particular pcap unit. INPUTS errnum - error number RESULT errstr (D0) - error string .