Changeset 6dc74e1


Ignore:
Timestamp:
02/02/10 15:56:19 (11 years ago)
Author:
Shane Alcock <salcock@…>
Branches:
4.0.1-hotfixes, cachetimestamps, develop, dpdk-ndag, etsilive, getfragoff, help, libtrace4, master, ndag_format, pfring, rc-4.0.1, rc-4.0.2, rc-4.0.3, rc-4.0.4, ringdecrementfix, ringperformance, ringtimestampfixes
Children:
8835f5a
Parents:
9dc77f3
Message:
  • Updated all the documentation in libtrace.h - should be way less spelling mistakes, bad grammar, ambiguous descriptions and just plain incorrect statements
File:
1 edited

Legend:

Unmodified
Added
Removed
  • lib/libtrace.h.in

    r226c08b r6dc74e1  
    66 *
    77 * Authors: Daniel Lawson
    8  *          Perry Lorier
     8 *          Perry Lorier
     9 *          Shane Alcock
    910 *         
    1011 * All rights reserved.
     
    4041 * @author Daniel Lawson
    4142 * @author Perry Lorier
     43 * @author Shane Alcock
    4244 *
    4345 * @version $Id: libtrace.h 773 2006-05-01 12:58:09Z perry $
     
    107109    /* GCC warns if the bitfield type is not "unsigned int", however windows
    108110     * generates incorrect code for this (see above), so we define these
    109      * macros.  How Hidious.  So much for C's portability.
     111     * macros.  How Hideous.  So much for C's portability.
    110112     */
    111113    #define LT_BITFIELD8        unsigned int
     
    753755 */
    754756
     757/** Takes a uri and splits it into a format and uridata component.
     758 * @param uri           The uri to be parsed
     759 * @param [out] format  A pointer that will be updated to point to an allocated
     760 *                      string holding the format component of the URI
     761 * @return NULL if an error occured, otherwise return a pointer to the uridata
     762 * component
     763 *
     764 * @note The format component is strdup'd by this function, so be sure to free
     765 * it when you are done with the split URI. Similarly, do not pass a pointer
     766 * to an allocated string into this function as the 'format' parameter, as
     767 * that memory will be leaked and replaced with the strdup'd format.
     768 */
     769DLLEXPORT const char *trace_parse_uri(const char *uri, char **format);
     770
    755771/** Create an input trace from a URI
    756772 *
     
    850866        TRACE_OPTION_META_FREQ,
    851867
    852         /* If enabled, the libtrace event API will ignore time gaps between
     868        /** If enabled, the libtrace event API will ignore time gaps between
    853869         * packets when reading from a trace file */
    854870        TRACE_OPTION_EVENT_REALTIME
     
    10061022/*@}*/
    10071023
    1008 /** @name Reading/Writing packets
     1024/** @name Reading / Writing packets
    10091025 * These members deal with creating, reading and writing packets
    10101026 *
     
    11021118 */
    11031119DLLEXPORT int trace_write_packet(libtrace_out_t *trace, libtrace_packet_t *packet);
     1120
     1121/** Gets the capture format for a given packet.
     1122 * @param packet        The packet to get the capture format for.
     1123 * @return The capture format of the packet
     1124 *
     1125 * @note Due to ability to convert packets between formats relatively easily
     1126 * in Libtrace, the format of the packet right now may not be the format that
     1127 * the packet was originally captured with.
     1128 */
     1129DLLEXPORT
     1130enum base_format_t trace_get_format(struct libtrace_packet_t *packet);
     1131
     1132/** Construct a libtrace packet from a buffer containing the packet payload.
     1133 * @param packet[in,out]        Libtrace Packet object to update with the new
     1134 *                              data.
     1135 * @param linktype              The linktype of the packet data.
     1136 * @param[in] data              The packet data (including linklayer).
     1137 * @param len                   Length of packet data provided in the buffer.
     1138 *
     1139 * @note The constructed packet will be in the PCAP format.
     1140 *
     1141 * @note To be useful, the provided buffer must start with the layer 2 header
     1142 * (or a metadata header, if desired).
     1143 */
     1144DLLEXPORT
     1145void trace_construct_packet(libtrace_packet_t *packet,
     1146                libtrace_linktype_t linktype, const void *data, uint16_t len);
     1147
    11041148/*@}*/
    11051149
     
    11781222
    11791223/** get a pointer to the IPv6 header (if any)
    1180  * @param packet        the packet opaque pointer
    1181  *
    1182  * @return a pointer to the IPv6 header, or NULL if there is no IPv6 header
     1224 * @param packet        The packet to get the IPv6 header for
     1225 *
     1226 * @return A pointer to the IPv6 header, or NULL if there is no IPv6 header
     1227 *
     1228 * If a partial IPv6 header is present, i.e. the packet has been truncated
     1229 * before the end of the IP header, this function will return NULL.
    11831230 *
    11841231 * You should consider using \ref trace_get_layer3 instead of this function.
     
    12001247 * trace_get_payload_from_meta(...) function.
    12011248 *
    1202  * @param packet the libtrace packet
    1203  * @param[out] linktype the linktype of the returned metadata header
    1204  * @param[out] remaining the number of bytes captured after the returned
     1249 * @param packet The libtrace packet
     1250 * @param[out] linktype The linktype of the returned metadata header
     1251 * @param[out] remaining The number of bytes captured after the returned
    12051252 * pointer.
    1206  * @return a pointer to the first metadata header, or NULL if there are no
     1253 * @return A pointer to the first metadata header, or NULL if there are no
    12071254 * metadata headers present.
    12081255 *
     
    12301277 * wireless monitoring header.
    12311278 *
    1232  * If the header is truncated, this function will return NULL, and remaining will be 0.
    1233  * If there are 0 bytes of payload, the function will return a pointer, and remaining will be 0.
    1234  *
    1235  * @param[in] meta a pointer to a header
    1236  * @param[in,out] linktype the linktype of meta (updated to indicate the
     1279 * If the metadata header passed into this function is truncated, this
     1280 * function will return NULL, and remaining will be set to 0.
     1281 *
     1282 * If there are 0 bytes of payload following the provided metadata header, the
     1283 * function will return a pointer to where the header would otherwise be and
     1284 * remaining will be 0.
     1285 *
     1286 * Therefore, be sure to check the value of remaining after calling this
     1287 * function!
     1288 *
     1289 * @param[in] meta A pointer to a metadata header
     1290 * @param[in,out] linktype The linktype of meta (updated to indicate the
    12371291 * linktype of the returned header if applicable).
    1238  * @param[in,out] remaining the number of bytes after the meta pointer.
    1239  * @return a pointer to the payload of the metadata header. If meta is not a
     1292 * @param[in,out] remaining The number of bytes after the meta pointer.
     1293 * @return A pointer to the payload of the metadata header. If meta is not a
    12401294 * pointer to a metadata header, NULL is returned and linktype remains
    12411295 * unchanged.
     
    12551309 * byte of the packet that was actually received by the network interface.
    12561310 *
    1257  * @param packet the libtrace packet
    1258  * @param[out] linktype the linktype of the returned layer 2 header
    1259  * @param[out] remaining the number of bytes left in the packet after the
     1311 * @param packet The libtrace packet to find the layer 2 header for
     1312 * @param[out] linktype The linktype of the returned layer 2 header
     1313 * @param[out] remaining The number of bytes left in the packet after the
    12601314 * returned pointer.
    1261  * @return a pointer to the first byte of the packet as it was seen on the
    1262  * wire.
     1315 * @return A pointer to the first byte of the packet as it was seen on the
     1316 * wire. If no layer 2 header is present, this function will return NULL.
    12631317 *
    12641318 * remaining may be NULL, otherwise it will be filled in by the function.
     
    12681322                uint32_t *remaining);
    12691323
    1270 /** Gets a pointer to the next header given a pointer to a layer2 header
    1271  *
    1272  * @param l2                    The pointer to the current layer2 header
    1273  * @param linktype              The type of the layer2 header
     1324/** Gets a pointer to the next header following a layer 2 header
     1325 *
     1326 * @param l2                    The pointer to the current layer 2 header
     1327 * @param linktype              The type of the layer 2 header
    12741328 * @param[out] ethertype        An optional output variable of the ethernet type of the new header
    12751329 * @param[in,out] remaining     Updated with the length remaining
    12761330 *
    1277  * @return a pointer to the transport layer header, or NULL if header isn't
    1278  * present.
    1279  *
    1280  * Remaining must point to the number of bytes captured of the layer2 header
     1331 * @return A pointer to the header following the provided layer 2 header, or
     1332 * NULL if no subsequent header is present.
     1333 *
     1334 * Remaining must point to the number of bytes captured from the layer 2 header
    12811335 * and beyond.  It will be decremented by the number of bytes skipped to find
    12821336 * the payload.
    12831337 *
    1284  * If the layer2 header is complete but there are zero bytes of payload after the end of the header,
    1285  * a pointer to where the payload would be is returned and remaining will be set to 0.  If the
    1286  * layer2 header is incomplete (truncated), then NULL is returned and remaining will be set to 0.
     1338 * If the layer 2 header is complete but there are zero bytes of payload after
     1339 * the end of the header, a pointer to where the payload would be is returned
     1340 * and remaining will be set to 0.  If the layer 2 header is incomplete
     1341 * (truncated), then NULL is returned and remaining will be set to 0.
     1342 * Therefore, it is very important to check the value of remaining after
     1343 * calling this function.
    12871344 *
    12881345 */
     
    12931350
    12941351
    1295 /** Get a pointer to the layer 3 header.
    1296  * @param packet                The packet opaque pointer
    1297  * @param[out] ethertype        The ethertype of the layer 3 header
    1298  * @param[out] remaining        The amount of space available after this header
    1299  *                              has been removed.
    1300  *
    1301  * @return a pointer to the layer 3 header.
     1352/** Get a pointer to the layer 3 (e.g. IP) header.
     1353 * @param packet  The libtrace packet to find the layer 3 header for
     1354 * @param[out] ethertype The ethertype of the layer 3 header
     1355 * @param[out] remaining The amount of captured data remaining in the packet starting from the returned pointer, i.e. including the layer 3 header.
     1356 *
     1357 * @return A pointer to the layer 3 header. If no layer 3 header is present in
     1358 * the packet, NULL is returned. If the layer 3 header is truncated, a valid
     1359 * pointer will still be returned so be sure to check the value of remaining
     1360 * before attempting to process the returned header.
     1361 *
    13021362 * remaining may be NULL, otherwise it will be set to the number of captured
    13031363 * bytes after the pointer returned.
     
    13081368
    13091369/** Gets a pointer to the transport layer header (if any)
    1310  * @param packet        a pointer to a libtrace_packet structure
    1311  * @param[out] proto    transport layer protocol
    1312  *
    1313  * @return a pointer to the transport layer header, or NULL if there is no
    1314  * header
     1370 * @param packet   The libtrace packet to find the transport header for
     1371 * @param[out] proto    The protocol present at the transport layer.
     1372 * @param[out] remaining The amount of captured data remaining in the packet
     1373 * starting from the returned pointer, i.e. including the transport header.
     1374 *
     1375 * @return A pointer to the transport layer header. If no transport header is
     1376 * present in the packet, NULL is returned. If the transport header is
     1377 * truncated, a valid pointer will still be returned so be sure to check the
     1378 * value of remaining before attempting to process the returned header.
     1379 *
     1380 * remaining may be NULL, otherwise it will be set to the number of captured
     1381 * bytes after the returned pointer.
    13151382 *
    13161383 * @note proto may be NULL if proto is unneeded.
     
    13191386                uint8_t *proto, uint32_t *remaining);
    13201387
    1321 /** Gets a pointer to the payload given a pointer to the IP header
    1322  * @param ip            The IP Header
    1323  * @param[out] proto    An output variable of the IP protocol
    1324  * @param[in,out] remaining Updated with the number of bytes remaining
    1325  *
    1326  * @return a pointer to the transport layer header, or NULL if header isn't
    1327  * present.
    1328  *
    1329  * Remaining will be decremented by the size of the IPv4 header (including any options).
    1330  * If the IPv4 header is complete but there are zero bytes of payload after the IPv4 header, a pointer
    1331  * to where the payload would be is returned and remaining will be set to 0.  If the IPv4 header is
    1332  * incomplete, NULL will be returned and remaining will be set to 0.
    1333  *
    1334  * proto may be NULL, in which case it won't be updated
     1388/** Gets a pointer to the payload following an IPv4 header
     1389 * @param ip            The IPv4 Header
     1390 * @param[out] proto    The protocol of the header following the IPv4 header
     1391 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1392 *
     1393 * @return A pointer to the transport layer header, or NULL if no subsequent
     1394 * header is present.
     1395 *
     1396 * When calling this function, remaining must contain the number of captured
     1397 * bytes remaining in the packet starting from the IPv4 header (including the
     1398 * IPv4 header itself).
     1399 *
     1400 * remaining will be decremented by the size of the IPv4 header (including any
     1401 * options). If the IPv4 header is complete but there are zero bytes of payload
     1402 * after the IPv4 header, a pointer to where the payload would be is returned
     1403 * and remaining will be set to 0.  If the IPv4 header is incomplete, NULL will
     1404 * be returned and remaining will be set to 0. Therefore, it is very important
     1405 * to check the value of remaining after calling this function.
     1406 *
     1407 * proto may be NULL, in which case it won't be updated.
    13351408 *
    13361409 * @note This is similar to trace_get_transport_from_ip in libtrace2
     
    13391412                uint32_t *remaining);
    13401413
    1341 /** Gets a pointer to the payload given a pointer to the IPv6 header
     1414/** Gets a pointer to the payload following an IPv6 header
    13421415 * @param ipptr         The IPv6 Header
    1343  * @param[out] proto    An output variable of the protocol of the next header
    1344  * @param[in,out] remaining Updated with the number of bytes remaining
    1345  *
    1346  * @return a pointer to the transport layer header, or NULL if the IPv6 header
    1347  * isn't complete.
    1348  *
    1349  * Remaining will be decremented by the size of the IPv6 header (including any options).
    1350  * If the IPv6 header is complete but there are zero bytes of payload after the IPv6 header, a pointer
    1351  * to where the payload would be is returned and remaining will be set to 0.  If the IPv6 header is
    1352  * incomplete, NULL will be returned and remaining will be set to 0.
     1416 * @param[out] proto    The protocol of the header following the IPv6 header
     1417 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1418 *
     1419 * @return A pointer to the transport layer header, or NULL if no subsequent
     1420 * header is present.
     1421 *
     1422 * When calling this function, remaining must contain the number of captured
     1423 * bytes remaining in the packet starting from the IPv6 header (including the
     1424 * IPv6 header itself).
     1425 *
     1426 * remaining will be decremented by the size of the IPv6 header (including any
     1427 * options). If the IPv6 header is complete but there are zero bytes of payload
     1428 * after the IPv6 header, a pointer to where the payload would be is returned
     1429 * and remaining will be set to 0.  If the IPv6 header is incomplete, NULL will
     1430 * be returned and remaining will be set to 0. Therefore, it is very important
     1431 * to check the value of remaining after calling this function.
    13531432 *
    13541433 * proto may be NULL, in which case it won't be updated.
     
    13581437                uint8_t *proto, uint32_t *remaining);
    13591438
    1360 /** Gets a pointer to the payload given a pointer to the link header
    1361  * @param ip            The link pointer
    1362  * @param[out] type     An output variable of the ethernet type
    1363  * @param[in,out] remaining Updated with the number of bytes remaining
    1364  *
    1365  * @return a pointer to the transport layer header, or NULL if header isn't
    1366  * present.
    1367  *
    1368  * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1369  * of bytes captured of the linklayer and beyond.  It will be updated after
    1370  * this function to the number of bytes remaining after the IP header (and any
    1371  * IP options) have been removed.
    1372  *
    1373  * type may be NULL if not needed.
     1439/** Gets a pointer to the payload following a link header
     1440 * @param ip            A pointer to the link layer header
     1441 * @param linktype      The linktype of the link header being examined
     1442 * @param[out] type     An output variable for the ethernet type
     1443 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1444 *
     1445 * @return A pointer to the header following the link header, or NULL if no
     1446 * subsequent header is present.
     1447 *
     1448 * When calling this function, remaining must contain the number of captured
     1449 * bytes remaining in the packet starting from the link header (including the
     1450 * link header itself). remaining will be updated to contain the number of
     1451 * bytes remaining after the link header has been skipped.
     1452 *
     1453 * @deprecated This function is deprecated: you should be using
     1454 * trace_get_payload_from_layer2() or trace_get_payload_from_meta() instead.
    13741455 *
    13751456 */
     
    13781459                uint16_t *type, uint32_t *remaining);
    13791460
    1380 /** Skips over any 802.1q header, if present.
    1381  * @param vlan      A pointer to the vlan header
    1382  * @param[out] type  The ethernet type, replaced with the vlan ether type
    1383  * @param[in,out] remaining Updated with the number of bytes remaining
    1384  *
    1385  * @return a pointer to the header beyond the vlan header, if present.
     1461/** Gets a pointer to the payload following an 802.1q (VLAN) header.
     1462 * @param vlan      A pointer to the VLAN header
     1463 * @param[out] type  The ethernet type, replaced with the VLAN ether type
     1464 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1465 *
     1466 * @return A pointer to the header beyond the VLAN header, if one is present.
    13861467 * Otherwise, returns NULL. 
    13871468 *
    1388  * Remaining will be decremented by the size of the vlan header.  If the vlan
    1389  * header is complete but there are zero bytes of payload after the vlan
    1390  * header, a pointer to where the payload would be is returned and remaining
    1391  * will be set to 0.  If the vlan header is incomplete, NULL will be returned
    1392  * and remaining will be set to 0.
    1393  *
    1394  * type will be set to the ethertype contained within the vlan payload.
     1469 * When calling this function, remaining must contain the number of captured
     1470 * bytes remaining in the packet starting from the VLAN header (including the
     1471 * VLAN header itself). remaining will be updated to contain the number of
     1472 * bytes remaining after the VLAN header has been skipped.
     1473 *
     1474 * If the VLAN header is complete but there are zero bytes of payload after
     1475 * the VLAN header, a pointer to where the payload would be is returned and
     1476 * remaining will be set to 0.  If the VLAN header is incomplete, NULL will be
     1477 * returned and remaining will be set to 0. Therefore, it is important to check
     1478 * the value of remaining after calling this function.
     1479 *
     1480 * type will be set to the ethertype of the VLAN payload. This parameter is not
     1481 * mandatory, but is highly recommended.
    13951482 *
    13961483 */
     
    13981485                void *vlan, uint16_t *type, uint32_t *remaining);
    13991486
    1400 /** Skips over a MPLS header
    1401  * @param mpls      A pointer to the mpls header
     1487/** Gets a pointer to the payload following an MPLS header.
     1488 * @param mpls      A pointer to the MPLS header
    14021489 * @param[out] type  The ethernet type, replaced by the ether type of the
    1403  * following header - 0x0000 if an Ethernet header is deemed to be next
    1404  * @param[in,out] remaining     Updated with the number of bytes remaining
    1405  *
    1406  * @return a pointer to the header beyond the MPLS label, if present. Will
    1407  * return NULL if there is not enough bytes remaining to skip past the MPLS
    1408  * label.
    1409  *
    1410  * Remaining will be decremented by the size of the MPLS header.  If the MPLS
    1411  * header is complete but there are zero bytes of payload after the MPLS
    1412  * header, a pointer to where the payload would be is returned and remaining
    1413  * will be set to 0.  If the MPLS header is incomplete, NULL will be returned
    1414  * and remaining will be set to 0.
    1415  *
    1416  * Type must point to the value of the ethernet type. Libtrace will assert
    1417  * fail if type is NULL.
    1418  *
    1419  * NOTE that this function will only remove one MPLS label at a time - the type
    1420  * will be set to 0x8847 if there is another MPLS label after the one
    1421  * removed by this function.
     1490 * returned header - 0x0000 if an Ethernet header is returned
     1491 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1492 *
     1493 * @return A pointer to the header beyond the MPLS label, if one is present.
     1494 * Will return NULL if there is not enough bytes remaining to skip past the
     1495 * MPLS label.
     1496 *
     1497 * When calling this function, remaining must contain the number of captured
     1498 * bytes remaining in the packet starting from the MPLS header (including the
     1499 * MPLS header itself). remaining will be updated to contain the number of
     1500 * bytes remaining after the MPLS header has been skipped.
     1501 *
     1502 * If the MPLS header is complete but there are zero bytes of payload after
     1503 * the MPLS header, a pointer to where the payload would be is returned and
     1504 * remaining will be set to 0.  If the MPLS header is incomplete, NULL will be
     1505 * returned and remaining will be set to 0. Therefore, it is important to check
     1506 * the value of remaining after calling this function.
     1507 *
     1508 * type will be set to the ethertype of the MPLS payload. This parameter is
     1509 * mandatory - it may not be NULL.
     1510 *
     1511 * @note This function will only remove one MPLS label at a time - the type
     1512 * will be set to 0x8847 if there is another MPLS label following the one
     1513 * skipped by this function.
    14221514 *
    14231515 */
     
    14251517                void *mpls, uint16_t *type, uint32_t *remaining);
    14261518
    1427 /** Skips over a PPPoE header and the following PPP header
     1519/** Gets a pointer to the payload following a PPPoE header
    14281520 * @param pppoe      A pointer to the PPPoE header
    14291521 * @param[out] type  The ethernet type, replaced by the ether type of the
    1430  * next header - 0x0000 if an Ethernet header is deemed to be next
    1431  * @param[in,out] remaining     Updated with the number of bytes remaining
    1432  *
    1433  * @return a pointer to the header beyond the PPPoE header. NOTE that this
     1522 * returned header - 0x0000 if an Ethernet header is returned
     1523 * @param[in,out] remaining  Updated with the number of captured bytes remaining
     1524 *
     1525 * @return A pointer to the header beyond the PPPoE header. NOTE that this
    14341526 * function will also skip over the PPP header that will immediately follow
    14351527 * the PPPoE header. This function will return NULL if there are not enough
    14361528 * bytes remaining to skip past both the PPPoE and PPP headers.
    14371529 *
    1438  * Remaining will be decremented by the size of the PPPoE and PPP headers.  If
    1439  * the headers are complete but there are zero bytes of payload after the PPP
    1440  * header, a pointer to where the payload would be is returned and remaining
    1441  * will be set to 0.  If the PPP or PPPoE header is incomplete, NULL will be
    1442  * returned and remaining will be set to 0.
    1443  *
    1444  * Type must point to the value of the ethernet type. Libtrace will assert
    1445  * fail if type is NULL.
     1530 * When calling this function, remaining must contain the number of captured
     1531 * bytes remaining in the packet starting from the PPPoE header (including the
     1532 * PPPoE header itself). remaining will be updated to contain the number of
     1533 * bytes remaining after the PPPoE and PPP headers have been removed.
     1534 *
     1535 * If the PPPoE and PPP headers are complete but there are zero bytes of
     1536 * payload after the PPP header, a pointer to where the payload would be is
     1537 * returned and remaining will be set to 0.  If the PPPoE or PPP header is
     1538 * incomplete, NULL will be returned and remaining will be set to 0. Therefore,
     1539 * it is important to check the value of remaining after calling this function.
     1540 *
     1541 * type will be set to the ether type of the PPP payload. This parameter is
     1542 * mandatory - it may not be NULL.
    14461543 *
    14471544 */
     
    14491546                void *pppoe, uint16_t *type, uint32_t *remaining);
    14501547
    1451 /** Gets a pointer to the payload given a pointer to a tcp header
    1452  * @param tcp           The tcp Header
    1453  * @param[in,out] remaining Updated with the number of bytes remaining
    1454  *
    1455  * @return a pointer to the tcp payload, or NULL if the tcp header is truncated.
    1456  *
    1457  * Remaining will be decremented by the size of the TCP header.  If the TCP
    1458  * header is complete but there are zero bytes of payload after the TCP
    1459  * header, a pointer to where the payload would be is returned and remaining
    1460  * will be set to 0.  If the TCP header is incomplete, NULL will be returned
    1461  * and remaining will be set to 0.
     1548/** Gets a pointer to the payload following a TCP header
     1549 * @param tcp           A pointer to the TCP header
     1550 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1551 *
     1552 * @return A pointer to the TCP payload, or NULL if the TCP header is truncated.
     1553 *
     1554 * When calling this function, remaining must contain the number of captured
     1555 * bytes remaining in the packet starting from the TCP header (including the
     1556 * TCP header itself). remaining will be updated to contain the number of
     1557 * bytes remaining after the TCP header has been skipped.
     1558 *
     1559 * If the TCP header is complete but there are zero bytes of payload after
     1560 * the TCP header, a pointer to where the payload would be is returned and
     1561 * remaining will be set to 0.  If the TCP header is incomplete, NULL will be
     1562 * returned and remaining will be set to 0. Therefore, it is important to check
     1563 * the value of remaining after calling this function.
    14621564 *
    14631565 */
     
    14651567                uint32_t *remaining);
    14661568
    1467 /** Gets a pointer to the payload given a pointer to a udp header
    1468  * @param udp           The udp Header
    1469  * @param[in,out] remaining Updated with the number of bytes remaining
    1470  *
    1471  * @return a pointer to the udp payload, or NULL if the udp header is truncated.
    1472  *
    1473  * Remaining will be decremented by the size of the TCP header.  If the TCP
    1474  * header is complete but there are zero bytes of payload after the TCP
    1475  * header, a pointer to where the payload would be is returned and remaining
    1476  * will be set to 0.  If the TCP header is incomplete, NULL will be returned
    1477  * and remaining will be set to 0.
     1569/** Gets a pointer to the payload following a UDP header
     1570 * @param udp           A pointer to the UDP header
     1571 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1572 *
     1573 * @return A pointer to the UDP payload, or NULL if the UDP header is truncated.
     1574 *
     1575 * When calling this function, remaining must contain the number of captured
     1576 * bytes remaining in the packet starting from the UDP header (including the
     1577 * UDP header itself). remaining will be updated to contain the number of
     1578 * bytes remaining after the UDP header has been skipped.
     1579 *
     1580 * If the UDP header is complete but there are zero bytes of payload after
     1581 * the UDP header, a pointer to where the payload would be is returned and
     1582 * remaining will be set to 0.  If the UDP header is incomplete, NULL will be
     1583 * returned and remaining will be set to 0. Therefore, it is important to check
     1584 * the value of remaining after calling this function.
    14781585 *
    14791586 */
    14801587DLLEXPORT void *trace_get_payload_from_udp(libtrace_udp_t *udp, uint32_t *remaining);
    14811588
    1482 /** Gets a pointer to the payload given a pointer to a icmp header
    1483  * @param icmp          The icmp Header
    1484  * @param[in,out] remaining Updated with the number of bytes remaining
    1485  *
    1486  * @return a pointer to the icmp payload, or NULL if the icmp header is truncated.
    1487  *
    1488  * Remaining will be decremented by the size of the TCP header.  If the TCP
    1489  * header is complete but there are zero bytes of payload after the TCP
    1490  * header, a pointer to where the payload would be is returned and remaining
    1491  * will be set to 0.  If the TCP header is incomplete, NULL will be returned
    1492  * and remaining will be set to 0.
    1493  *
     1589/** Gets a pointer to the payload following a ICMP header
     1590 * @param icmp           A pointer to the ICMP header
     1591 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1592 *
     1593 * @return A pointer to the ICMP payload, or NULL if the ICMP header is
     1594 * truncated.
     1595 *
     1596 * When calling this function, remaining must contain the number of captured
     1597 * bytes remaining in the packet starting from the ICMP header (including the
     1598 * ICMP header itself). remaining will be updated to contain the number of
     1599 * bytes remaining after the ICMP header has been skipped.
     1600 *
     1601 * If the ICMP header is complete but there are zero bytes of payload after
     1602 * the ICMP header, a pointer to where the payload would be is returned and
     1603 * remaining will be set to 0.  If the ICMP header is incomplete, NULL will be
     1604 * returned and remaining will be set to 0. Therefore, it is important to check
     1605 * the value of remaining after calling this function.
     1606 *
     1607 * @note In the case of some ICMP messages, the payload may be the IP header
     1608 * from the packet that triggered the ICMP message.
     1609 *
    14941610 */
    14951611DLLEXPORT void *trace_get_payload_from_icmp(libtrace_icmp_t *icmp,
    14961612                uint32_t *remaining);
    14971613
    1498 /** get a pointer to the TCP header (if any)
    1499  * @param packet        the packet opaque pointer
    1500  *
    1501  * @return a pointer to the TCP header, or NULL if there is not a TCP packet
    1502  *
    1503  * @note you should probably use trace_get_transport()
     1614/** Get a pointer to the TCP header (if present)
     1615 * @param packet        The packet to get the TCP header from
     1616 *
     1617 * @return A pointer to the TCP header, or NULL if there is not a complete TCP
     1618 * header present in the packet.
     1619 *
     1620 * This is a short-cut function enabling quick and easy access to the TCP
     1621 * header if that is all you care about. However, we recommend the use of the
     1622 * more generic trace_get_transport() function instead.
     1623 *
     1624 * @note Unlike trace_get_transport(), this function will return NULL if the
     1625 * TCP header is incomplete or truncated.
    15041626 */
    15051627DLLEXPORT SIMPLE_FUNCTION
    15061628libtrace_tcp_t *trace_get_tcp(libtrace_packet_t *packet);
    15071629
    1508 /** get a pointer to the TCP header (if any) given a pointer to the IP header
    1509  * @param ip            The IP header
    1510  * @param[in,out] remaining Updated with the number of bytes remaining
    1511  *
    1512  * @return a pointer to the TCP header, or NULL if this is not a TCP packet
    1513  *
    1514  * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1515  * of bytes captured of the TCP header and beyond.  It will be decremented by
    1516  * the number of bytes in the TCP header (including any TCP options).
     1630/** Get a pointer to the TCP header following an IPv4 header (if present)
     1631 * @param ip            The IP header to find the subsequent TCP header for
     1632 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1633 *
     1634 * @return A pointer to the TCP header, or NULL if no TCP header is present in
     1635 * the packet.
     1636 *
     1637 * When calling this function, remaining must contain the number of captured
     1638 * bytes remaining in the packet starting from the IP header (including the
     1639 * IP header itself). remaining will be updated to contain the number of
     1640 * bytes remaining after the IP header has been skipped.
     1641 *
     1642 * If the IP header is complete but there are zero bytes of payload after
     1643 * the IP header, a pointer to where the payload would be is returned and
     1644 * remaining will be set to 0.  If the IP header is incomplete, NULL will be
     1645 * returned and remaining will be set to 0. Therefore, it is important to check
     1646 * the value of remaining after calling this function.
     1647 *
     1648 * @note This function is rather redundant now that the layer 3 header is
     1649 * cached. There should be no performance advantage for the user to call this
     1650 * function over just calling trace_get_transport().
    15171651 *
    15181652 * @note The last parameter has changed from libtrace2
     
    15211655libtrace_tcp_t *trace_get_tcp_from_ip(libtrace_ip_t *ip, uint32_t *remaining);
    15221656
    1523 /** get a pointer to the UDP header (if any)
    1524  * @param packet        the packet opaque pointer
    1525  *
    1526  * @return a pointer to the UDP header, or NULL if this is not a UDP packet
     1657/** Get a pointer to the UDP header (if present)
     1658 * @param packet        The packet to get the UDP header from
     1659 *
     1660 * @return A pointer to the UDP header, or NULL if there is not a complete UDP
     1661 * header present in the packet.
     1662 *
     1663 * This is a short-cut function enabling quick and easy access to the UDP
     1664 * header if that is all you care about. However, we recommend the use of the
     1665 * more generic trace_get_transport() function instead.
     1666 *
     1667 * @note Unlike trace_get_transport(), this function will return NULL if the
     1668 * UDP header is incomplete or truncated.
    15271669 */
    15281670DLLEXPORT SIMPLE_FUNCTION
    15291671libtrace_udp_t *trace_get_udp(libtrace_packet_t *packet);
    15301672
    1531 /** get a pointer to the UDP header (if any) given a pointer to the IP header
    1532  * @param       ip      The IP header
    1533  * @param[in,out] remaining Updated with the number of bytes remaining
    1534  *
    1535  * @return a pointer to the UDP header, or NULL if this is not an UDP packet
    1536  *
    1537  * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1538  * of bytes captured of the UDP header and beyond.  This function will
    1539  * decremented it by the length of the UDP header.
    1540  *
    1541  * @note Beware the change from libtrace2 from skipped to remaining
     1673/** Get a pointer to the UDP header following an IPv4 header (if present)
     1674 * @param ip            The IP header to find the subsequent UDP header for
     1675 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1676 *
     1677 * @return A pointer to the UDP header, or NULL if no UDP header is present in
     1678 * the packet.
     1679 *
     1680 * When calling this function, remaining must contain the number of captured
     1681 * bytes remaining in the packet starting from the IP header (including the
     1682 * IP header itself). remaining will be updated to contain the number of
     1683 * bytes remaining after the IP header has been skipped.
     1684 *
     1685 * If the IP header is complete but there are zero bytes of payload after
     1686 * the IP header, a pointer to where the payload would be is returned and
     1687 * remaining will be set to 0.  If the IP header is incomplete, NULL will be
     1688 * returned and remaining will be set to 0. Therefore, it is important to check
     1689 * the value of remaining after calling this function.
     1690 *
     1691 * @note This function is rather redundant now that the layer 3 header is
     1692 * cached. There should be no performance advantage for the user to call this
     1693 * function over just calling trace_get_transport().
     1694 *
     1695 * @note The last parameter has changed from libtrace2
    15421696 */
    15431697DLLEXPORT SIMPLE_FUNCTION
    15441698libtrace_udp_t *trace_get_udp_from_ip(libtrace_ip_t *ip,uint32_t *remaining);
    15451699
    1546 /** get a pointer to the ICMP header (if any)
    1547  * @param packet        the packet opaque pointer
    1548  *
    1549  * @return a pointer to the ICMP header, or NULL if this is not a ICMP packet
     1700/** Get a pointer to the ICMP header (if present)
     1701 * @param packet        The packet to get the ICMP header from
     1702 *
     1703 * @return A pointer to the ICMP header, or NULL if there is not a complete
     1704 * ICMP header present in the packet.
     1705 *
     1706 * This is a short-cut function enabling quick and easy access to the ICMP
     1707 * header if that is all you care about. However, we recommend the use of the
     1708 * more generic trace_get_transport() function instead.
     1709 *
     1710 * @note Unlike trace_get_transport(), this function will return NULL if the
     1711 * ICMP header is incomplete or truncated.
    15501712 */
    15511713DLLEXPORT SIMPLE_FUNCTION
    15521714libtrace_icmp_t *trace_get_icmp(libtrace_packet_t *packet);
    15531715
    1554 /** get a pointer to the ICMP header (if any) given a pointer to the IP header
    1555  * @param ip            The IP header
    1556  * @param[in,out] remaining Updated with the number of bytes remaining
    1557  *
    1558  * @return a pointer to the ICMP header, or NULL if this is not an ICMP packet
    1559  *
    1560  * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1561  * of bytes captured of the ICMP header and beyond.  It will be decremented by
    1562  * the length of the ICMP head in bytes.
    1563  *
    1564  * @note Beware the change from libtrace2 from skipped to remaining
     1716/** Get a pointer to the ICMP header following an IPv4 header (if present)
     1717 * @param ip            The IP header to find the subsequent ICMP header for
     1718 * @param[in,out] remaining Updated with the number of captured bytes remaining
     1719 *
     1720 * @return A pointer to the ICMP header, or NULL if no UDP header is present in
     1721 * the packet.
     1722 *
     1723 * When calling this function, remaining must contain the number of captured
     1724 * bytes remaining in the packet starting from the IP header (including the
     1725 * IP header itself). remaining will be updated to contain the number of
     1726 * bytes remaining after the IP header has been skipped.
     1727 *
     1728 * If the IP header is complete but there are zero bytes of payload after
     1729 * the IP header, a pointer to where the payload would be is returned and
     1730 * remaining will be set to 0.  If the IP header is incomplete, NULL will be
     1731 * returned and remaining will be set to 0. Therefore, it is important to check
     1732 * the value of remaining after calling this function.
     1733 *
     1734 * @note This function is rather redundant now that the layer 3 header is
     1735 * cached. There should be no performance advantage for the user to call this
     1736 * function over just calling trace_get_transport().
     1737 *
     1738 * @note The last parameter has changed from libtrace2
    15651739 */
    15661740DLLEXPORT SIMPLE_FUNCTION
    15671741libtrace_icmp_t *trace_get_icmp_from_ip(libtrace_ip_t *ip,uint32_t *remaining);
    15681742
    1569 /** Get the destination MAC address
    1570  * @param packet        the packet opaque pointer
    1571  * @return a pointer to the destination mac, (or NULL if there is no
    1572  * destination MAC)
     1743/** Gets the destination MAC address for a given packet
     1744 * @param packet        The packet to extract the destination MAC address from
     1745 *
     1746 * @return A pointer to the destination MAC address field in the layer 2
     1747 * header, (or NULL if there is no destination MAC address or layer 2 header
     1748 * available)
     1749 *
     1750 * @note This is a zero-copy function, so the memory that the returned pointer
     1751 * points to is part of the packet itself.
    15731752 */
    15741753DLLEXPORT SIMPLE_FUNCTION
    15751754uint8_t *trace_get_destination_mac(libtrace_packet_t *packet);
    15761755
    1577 /** Get the source MAC address
    1578  * @param packet        the packet opaque pointer
    1579  * @return a pointer to the source mac, (or NULL if there is no source MAC)
     1756/** Gets the source MAC address for a given packet
     1757 * @param packet        The packet to extract the source MAC address from
     1758 *
     1759 * @return A pointer to the source MAC address field in the layer 2
     1760 * header, (or NULL if there is no source MAC address or layer 2 header
     1761 * available)
     1762 *
     1763 * @note This is a zero-copy function, so the memory that the returned pointer
     1764 * points to is part of the packet itself.
    15801765 */
    15811766DLLEXPORT SIMPLE_FUNCTION
    15821767uint8_t *trace_get_source_mac(libtrace_packet_t *packet);
    15831768
    1584 /** Get the source IP address
    1585  * @param packet        the packet opaque pointer
    1586  * @param addr          a pointer to a sockaddr to store the address in, or NULL to use
    1587  *                      static storage.
    1588  * @return NULL if there is no source address, or a sockaddr holding a v4 or v6
    1589  * address, or on some platforms a sockaddr holding a MAC address.
     1769/** Get the source IP address for a given packet
     1770 * @param packet        The packet to extract the source IP address from
     1771 * @param addr          A pointer to a sockaddr structure to store the address
     1772 *                      in. If NULL, static storage is used instead.
     1773 * @return A pointer to a sockaddr holding a v4 or v6 IP address or on some
     1774 * platforms a sockaddr holding a MAC address. Returns NULL if no source IP
     1775 * address was available.
     1776 *
     1777 * @note The best way to use this function is to pass in a pointer to the
     1778 * struct sockaddr_storage for the addr parameter. This will avoid problems
     1779 * with trying to shoe-horn an IPv6 address into a sockaddr that only supports
     1780 * IPv4.
    15901781 */
    15911782DLLEXPORT SIMPLE_FUNCTION
     
    15931784                struct sockaddr *addr);
    15941785
    1595 /** Get the destination IP address
    1596  * @param packet        the packet opaque pointer
    1597  * @param addr          a pointer to a sockaddr to store the address in, or NULL to use
    1598  *                      static storage.
    1599  * @return NULL if there is no destination address, or a sockaddr holding a v4
    1600  * or v6 address, or on some platforms a sockaddr holding a MAC address.
     1786/** Get the destination IP address for a given packet
     1787 * @param packet        The packet to extract the destination IP address from
     1788 * @param addr          A pointer to a sockaddr structure to store the address
     1789 *                      in. If NULL, static storage is used instead.
     1790 * @return A pointer to a sockaddr holding a v4 or v6 IP address or on some
     1791 * platforms a sockaddr holding a MAC address. Returns NULL if no destination
     1792 * IP address was available.
     1793 *
     1794 * @note The best way to use this function is to pass in a pointer to the
     1795 * struct sockaddr_storage for the addr parameter. This will avoid problems
     1796 * with trying to shoe-horn an IPv6 address into a sockaddr that only supports
     1797 * IPv4.
    16011798 */
    16021799DLLEXPORT SIMPLE_FUNCTION
     
    16041801                struct sockaddr *addr);
    16051802
    1606 /*@}*/
    1607 
    1608 /** parse an ip or tcp option
    1609  * @param[in,out] ptr   the pointer to the current option
    1610  * @param[in,out] len   the length of the remaining buffer
    1611  * @param[out] type     the type of the option
    1612  * @param[out] optlen   the length of the option
    1613  * @param[out] data     the data of the option
     1803
     1804/** Parses an IP or TCP option
     1805 * @param[in,out] ptr   The pointer to the current option
     1806 * @param[in,out] len   The total length of all the remaining options
     1807 * @param[out] type     The type of the option
     1808 * @param[out] optlen   The length of the option
     1809 * @param[out] data     The data of the option
    16141810 *
    16151811 * @return bool true if there is another option (and the fields are filled in)
     
    16281824                        unsigned char **data);
    16291825
     1826/*@}*/
    16301827
    16311828/** @name Time
    1632  * These functions deal with time that a packet arrived and return it
    1633  * in various formats
     1829 * These functions deal with the timestamp describing when a packet was
     1830 * captured and can convert it into various formats
    16341831 * @{
    16351832 */
    1636 /** Get the current time in DAG time format
    1637  * @param packet        the packet opaque pointer
     1833
     1834/** Get the packet timestamp in the DAG time format
     1835 * @param packet        The packet to extract the timestamp from
    16381836 *
    16391837 * @return a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
     
    16431841uint64_t trace_get_erf_timestamp(const libtrace_packet_t *packet);
    16441842
    1645 /** Get the current time in struct timeval
    1646  * @param packet        the packet opaque pointer
    1647  *
    1648  * @return time that this packet was seen in a struct timeval
     1843/** Get the packet timestamp as a struct timeval
     1844 * @param packet        The packet to extract the timestamp from
     1845 *
     1846 * @return The time that this packet was captured in a struct timeval
    16491847 */
    16501848DLLEXPORT SIMPLE_FUNCTION
    16511849struct timeval trace_get_timeval(const libtrace_packet_t *packet);
    16521850
    1653 /** Get the current time in struct timespec
    1654  * @param packet        the packet opaque pointer
    1655  *
    1656  * @return time that this packet was seen in a struct timespec
     1851/** Get the packet timestamp as a struct timespec
     1852 * @param packet        The packet to extract the timestamp from
     1853 *
     1854 * @return The time that this packet was captured in a struct timespec
    16571855 */
    16581856DLLEXPORT SIMPLE_FUNCTION
    16591857struct timespec trace_get_timespec(const libtrace_packet_t *packet);
    16601858
    1661 /** Get the current time in floating point seconds
    1662  * @param packet        the packet opaque pointer
    1663  *
    1664  * @return time that this packet was seen in 64bit floating point seconds from
    1665  * the unix epoch (1970-01-01 00:00:00 UTC).
     1859/** Get the packet timestamp in floating point seconds
     1860 * @param packet        The packet to extract the timestamp from
     1861 *
     1862 * @return time that this packet was seen in 64-bit floating point seconds from
     1863 * the UNIX epoch (1970-01-01 00:00:00 UTC).
    16661864 */
    16671865DLLEXPORT SIMPLE_FUNCTION
    16681866double trace_get_seconds(const libtrace_packet_t *packet);
    16691867
    1670 /** Seek within a trace
    1671  * @param trace         trace to seek
    1672  * @param seconds       time to seek to
    1673  * @return 0 on success.
    1674  * Make the next packet read to be the first packet to occur at or after the
    1675  * time searched for.  This must be called in the configuration state (ie,
    1676  * before trace_start() or after trace_pause().
     1868/** Seek within an input trace to a time specified in floating point seconds
     1869 * @param trace         The input trace to seek within
     1870 * @param seconds       The time to seek to, in floating point seconds
     1871 * @return 0 on success, -1 if the seek fails. Use trace_perror() to determine
     1872 * the error that occurred.
     1873 *
     1874 * This will make the next packet read to be the first packet to occur at or
     1875 * after the specified time.  This must be called in the configuration state
     1876 * (i.e. before trace_start() or after trace_pause()).
     1877 *
     1878 * The time format accepted by this function is 64-bit floating point seconds
     1879 * since the UNIX epoch (1970-01-01 00:00:00 UTC), i.e. the same format as
     1880 * trace_get_seconds().
     1881 *
    16771882 * @note This function may be extremely slow.
    16781883 */
    16791884DLLEXPORT int trace_seek_seconds(libtrace_t *trace, double seconds);
    16801885
    1681 /** Seek within a trace
    1682  * @param trace         trace to seek
    1683  * @param tv            time to seek to
    1684  * @return 0 on success.
    1685  * Make the next packet read to be the first packet to occur at or after the
    1686  * time searched for.  This must be called in the configuration state (ie,
    1687  * before trace_start() or after trace_pause().
     1886/** Seek within an input trace to a time specified as a timeval
     1887 * @param trace         The input trace to seek within
     1888 * @param tv            The time to seek to, as a timeval
     1889 *
     1890 * @return 0 on success, -1 if the seek fails. Use trace_perror() to determine
     1891 * the error that occurred.
     1892 *
     1893 * This will make the next packet read to be the first packet to occur at or
     1894 * after the specified time.  This must be called in the configuration state
     1895 * (i.e. before trace_start() or after trace_pause()).
     1896 *
    16881897 * @note This function may be extremely slow.
    16891898 */
    16901899DLLEXPORT int trace_seek_timeval(libtrace_t *trace, struct timeval tv);
    16911900
    1692 /** Seek within a trace
    1693  * @param trace         trace to seek
    1694  * @param ts            erf timestamp
    1695  * @return 0 on success.
    1696  * Make the next packet read to be the first packet to occur at or after the
    1697  * time searched for.  This must be called in the configuration state (ie,
    1698  * before trace_start() or after trace_pause().
     1901/** Seek within an input trace to a time specified as an ERF timestamp
     1902 * @param trace         The input trace to seek within
     1903 * @param tv            The time to seek to, as an ERF timestamp
     1904 *
     1905 * @return 0 on success, -1 if the seek fails. Use trace_perror() to determine
     1906 * the error that occurred.
     1907 *
     1908 * This will make the next packet read to be the first packet to occur at or
     1909 * after the specified time.  This must be called in the configuration state
     1910 * (i.e. before trace_start() or after trace_pause()).
     1911 *
     1912 * The time format accepted by this function is the ERF timestamp, which is a
     1913 * 64-bit value where the upper 32 bits are seconds since the UNIX epoch and
     1914 * the lower 32 bits are partial seconds.
     1915 *
    16991916 * @note This function may be extremely slow.
    17001917 */
     
    17051922/** @name Sizes
    17061923 * This section deals with finding or setting the various different lengths
    1707  * a packet can have
     1924 * that a packet can have, e.g. capture lengths, wire lengths, etc.
    17081925 * @{
    17091926 */
    1710 /** Get the size of the packet in the trace (in bytes)
    1711  * @param packet        the packet opaque pointer
    1712  * @return the size of the packet in the trace
    1713  * @note Due to this being a header capture, or anonymisation, this may not
    1714  * be the same size as the original packet.  See get_wire_length() for the
    1715  * original size of the packet.
     1927/** Get the current size of the packet (in bytes), taking into account any
     1928 * truncation or snapping that may have previously been performed.
     1929 *
     1930 * @param packet        The packet to determine the capture length for
     1931 * @return The size of the packet read from the input trace, i.e. what is
     1932 * actually available to libtrace at the moment.
     1933 *
     1934 * @note Most traces are header captures, so this value may not be the same
     1935 * as the size of the packet when it was captured. Use trace_get_wire_length()
     1936 * to get the original size of the packet.
     1937 
    17161938 * @note This can (and often is) different for different packets in a trace!
     1939 
    17171940 * @note This is sometimes called the "snaplen".
     1941 *
    17181942 * @note The return size refers to the network-level payload of the packet and
    17191943 * does not include any capture framing headers. For example, an Ethernet
    17201944 * packet with an empty TCP packet will return sizeof(ethernet_header) +
    1721  * sizeof(ip_header) + sizeof(tcp_header), but not the capture file
     1945 * sizeof(ip_header) + sizeof(tcp_header), but not the capture format
    17221946 * (pcap/erf/etc) header.
    17231947 */
     
    17251949size_t trace_get_capture_length(const libtrace_packet_t *packet);
    17261950
    1727 /** Get the size of the packet as it was seen on the wire (in bytes).
    1728  * @param packet        the packet opaque pointer
    1729  * @return the size of the packet as it was on the wire.
    1730  * @note Due to the trace being a header capture, or anonymisation this may
    1731  * not be the same as the Capture Len.
    1732  * @note trace_get_wire_length \em{includes} FCS.  This is different to pcap based tools.
     1951/** Get the size of the packet as it was originally seen on the wire (in bytes).
     1952 * @param packet        The packet to determine the wire length for
     1953 * @return The size of the packet as it was on the wire.
     1954 *
     1955 * @note This value may not be the same as the capture length, due to
     1956 * truncation.
     1957 *
     1958 * @note trace_get_wire_length \em{includes} the Frame Check Sequence. This is
     1959 * different behaviour compared to most PCAP-based tools.
     1960 *
    17331961 * @note The return size refers to the network-level payload of the packet and
    17341962 * does not include any capture framing headers. For example, an Ethernet
    17351963 * packet with an empty TCP packet will return sizeof(ethernet_header) +
    1736  * sizeof(ip_header) + sizeof(tcp_header), but not the capture file
     1964 * sizeof(ip_header) + sizeof(tcp_header), but not the capture format
    17371965 * (pcap/erf/etc) header.
    17381966 */
     
    17411969
    17421970/** Get the length of the capture framing headers (in bytes).
    1743  * @param packet        the packet opaque pointer
    1744  * @return the size of the packet as it was on the wire.
    1745  * @note this length corresponds to the difference between the size of a
    1746  * captured packet in memory, and the captured length of the packet
     1971 * @param packet        The packet to determine the framing length for
     1972 * @return The size of the capture format header encapsulating the packet.
     1973 *
     1974 * @note This length corresponds to the difference between the amount of
     1975 * memory required to store a captured packet and the capture length reported
     1976 * by trace_capture_length()
    17471977 */
    17481978DLLEXPORT SIMPLE_FUNCTION
    17491979size_t trace_get_framing_length(const libtrace_packet_t *packet);
    17501980
    1751 /** Truncate ("snap") the packet at the suggested length
    1752  * @param packet        the packet opaque pointer
    1753  * @param size          the new length of the packet (in bytes)
    1754  * @return the new capture length of the packet, or the original capture
    1755  * length of the packet if unchanged
     1981/** Truncate ("snap") the packet to the suggested length
     1982 * @param packet        The packet to truncate
     1983 * @param size          The new length of the packet (in bytes)
     1984 *
     1985 * @return The new capture length of the packet or the original capture
     1986 * length of the packet if unchanged.
     1987 *
     1988 * This function will modify the capture length of the given packet. The wire
     1989 * length will not be changed, so you can always determine what the original
     1990 * packet size was, prior to the truncation.
     1991 *
     1992 * @note You can only use this function to decrease the capture length. Any
     1993 * attempt to increase capture length will have no effect.
    17561994 */
    17571995DLLEXPORT size_t trace_set_capture_length(libtrace_packet_t *packet, size_t size);
     
    17601998
    17611999
    1762 /** Get the type of the link layer
    1763  * @param packet        the packet opaque pointer
    1764  * @return libtrace_linktype_t
     2000/** Gets the link layer type for a packet
     2001 * @param packet        The packet to extract the link layer type for
     2002 * @return A libtrace_linktype_t describing the link layer protocol being used
     2003 * by this packet.
    17652004 */
    17662005DLLEXPORT SIMPLE_FUNCTION
    17672006libtrace_linktype_t trace_get_link_type(const libtrace_packet_t *packet);
    17682007
    1769 /** Set the direction flag, if it has one
    1770  * @param packet        the packet opaque pointer
    1771  * @param direction     the new direction
     2008/** Set the direction flag for a packet, if the capture format supports
     2009 * direction tagging.
     2010 *
     2011 * @param packet        The packet to set the direction for
     2012 * @param direction     The new direction
    17722013 * @returns -1 on error, or the direction that was set.
     2014 *
     2015 * @note Few capture formats actually support direction tagging. Most notably,
     2016 * we cannot set the direction on PCAP packets.
    17732017 */
    17742018DLLEXPORT libtrace_direction_t trace_set_direction(libtrace_packet_t *packet, libtrace_direction_t direction);
    17752019
    1776 /** Get the direction flag, if it has one
    1777  * @param packet        the packet opaque pointer
    1778  * @return a value containing the direction flag, or -1 if this is not supported
     2020/** Get the direction flag for a packet, if it has one.
     2021 * @param packet  The packet to get the direction for
     2022 *
     2023 * @return A value representing the direction flag, or -1 if this is not
     2024 * supported by the capture format.
     2025 *
    17792026 * The direction is defined as 0 for packets originating locally (ie, outbound)
    1780  * and 1 for packets originating remotely (ie, inbound).
    1781  * Other values are possible, which might be overloaded to mean special things
    1782  * for a special trace.
     2027 * and 1 for packets originating remotely (ie, inbound). Other values are
     2028 * possible, which might be overloaded to mean special things for certain
     2029 * traces, e.g. in the Waikato traces, 2 is used to represent an "Unknown"
     2030 * direction.
     2031 *
     2032 * For DAG/ERF traces, the direction is extracted from the "Interface" bits in
     2033 * the ERF header, which can range from 0 - 3.
    17832034 */
    17842035DLLEXPORT SIMPLE_FUNCTION
     
    17862037
    17872038/** @name BPF
    1788  * This section deals with using Berkley Packet Filters
     2039 * This section deals with using Berkley Packet Filters to filter input traces
    17892040 * @{
    17902041 */
    1791 /** setup a BPF filter
    1792  * @param filterstring a char * containing the bpf filter string
    1793  * @return opaque pointer pointer to a libtrace_filter_t object
     2042/** Creates a BPF filter
     2043 * @param filterstring The filter string describing the BPF filter to create
     2044 * @return An opaque pointer to a libtrace_filter_t object
     2045 *
    17942046 * @note The filter is not actually compiled at this point, so no correctness
    1795  * tests are performed here. trace_create_filter will always return ok, but
     2047 * tests are performed here. trace_create_filter() will always return ok, but
    17962048 * if the filter is poorly constructed an error will be generated when the
    1797  * filter is actually used
     2049 * filter is actually used.
    17982050 */
    17992051DLLEXPORT SIMPLE_FUNCTION
    18002052libtrace_filter_t *trace_create_filter(const char *filterstring);
    18012053
    1802 /** Setup a BPF filter based on pre-compiled byte-code.
     2054/** Create a BPF filter based on pre-compiled byte-code.
    18032055 * @param bf_insns      A pointer to the start of the byte-code
    18042056 * @param bf_len        The number of BPF instructions 
    1805  * @returns             an opaque pointer to a libtrace_filter_t object
     2057 * @return              An opaque pointer to a libtrace_filter_t object
    18062058 * @note                The supplied byte-code is not checked for correctness.
     2059 *                      Instead, incorrect byte-code will generate an error
     2060 *                      once the filter is actually used.
    18072061 * @author              Scott Raynel
    18082062 */
     
    18112065
    18122066/** Apply a BPF filter to a packet
    1813  * @param filter        the filter opaque pointer
    1814  * @param packet        the packet opaque pointer
     2067 * @param filter        The filter to be applied       
     2068 * @param packet        The packet to be matched against the filter
    18152069 * @return >0 if the filter matches, 0 if it doesn't, -1 on error.
     2070 *
    18162071 * @note Due to the way BPF filters are built, the filter is not actually
    18172072 * compiled until the first time trace_create_filter is called. If your filter
    18182073 * is incorrect, it will generate an error message and assert, exiting the
    1819  * program. This behaviour may change to more graceful handling of this error
     2074 * program. This behaviour may change to a more graceful handling of this error
    18202075 * in the future.
    18212076 */
     
    18242079
    18252080/** Destroy a BPF filter
    1826  * @param filter        the filter opaque pointer
    1827  * Deallocate all the resources associated with a BPF filter
     2081 * @param filter        The filter to be destroyed
     2082 *
     2083 * Deallocates all the resources associated with a BPF filter.
    18282084 */
    18292085DLLEXPORT void trace_destroy_filter(libtrace_filter_t *filter);
     
    18312087
    18322088/** @name Portability
    1833  * This section has functions that causes annoyances to portability for one
    1834  * reason or another.
     2089 * This section contains functions that deal with portability issues, e.g. byte
     2090 * ordering.
    18352091 * @{
    18362092 */
    18372093
    1838 /** Convert an ethernet address to a string
     2094/** Converts an ethernet address to a printable string
    18392095 * @param addr  Ethernet address in network byte order
    1840  * @param buf   Buffer to store the ascii representation, or NULL
     2096 * @param buf   Buffer to store the ascii representation, or NULL to indicate
     2097 * that static storage should be used.
    18412098 * @return buf, or if buf is NULL then a statically allocated buffer.
    18422099 *
    18432100 * This function is similar to the GNU ether_ntoa_r function, with a few
    1844  * minor differences.  if NULL is passed as buf, then the function will
    1845  * use an internal static buffer, if NULL isn't passed then the function
     2101 * minor differences.  If NULL is passed as buf, then the function will
     2102 * use an internal static buffer. If NULL isn't passed then the function
    18462103 * will use that buffer instead.
    18472104 *
    1848  * @note the type of addr isn't struct ether_addr as it is with ether_ntoa_r,
     2105 * The address pointers returned by trace_get_source_mac() and
     2106 * trace_get_destination_mac() can be passed directly into this function.
     2107 *
     2108 * @note The type of addr isn't struct ether_addr as it is with ether_ntoa_r,
    18492109 * however it is bit compatible so that a cast will work.
    18502110 */
     
    18522112
    18532113/** Convert a string to an ethernet address
    1854  * @param buf   Ethernet address in hex format delimited with :'s.
    1855  * @param addr  buffer to store the binary representation, or NULL
    1856  * @return addr, or if addr is NULL, then a statically allocated buffer.
     2114 * @param buf   A string containing an Ethernet address in hex format
     2115 * delimited with :'s.
     2116 * @param addr  Buffer to store the binary representation, or NULL to indicate
     2117 * that static storage should be used.
     2118 * @return addr, or if addr is NULL then a statically allocated buffer.
    18572119 *
    18582120 * This function is similar to the GNU ether_aton_r function, with a few
    1859  * minor differences.  if NULL is passed as addr, then the function will
    1860  * use an internal static buffer, if NULL isn't passed then the function will
     2121 * minor differences.  If NULL is passed as addr, then the function will
     2122 * use an internal static buffer. If NULL isn't passed then the function will
    18612123 * use that buffer instead.
    18622124 *
     2125 * The address returned by this function will be in network byte order.
     2126 *
    18632127 * @note the type of addr isn't struct ether_addr as it is with ether_aton_r,
    18642128 * however it is bit compatible so that a cast will work.
     
    18682132/*@}*/
    18692133
    1870 
    1871 /** Which port is the server port */
     2134/** @name Ports
     2135 * This section contains functions for dealing with port numbers at the
     2136 * transport layer.
     2137 *
     2138 * @{
     2139 */
     2140
     2141/** An indication of which port is the "server" port for a given port pair */
    18722142typedef enum {
    18732143        USE_DEST,       /**< Destination port is the server port */
     
    18752145} serverport_t;
    18762146
    1877 /** Get the source port
    1878  * @param packet        the packet to read from
    1879  * @return a port in \em HOST byte order, or equivalent to ports for this
    1880  * protocol, or 0 if this protocol has no ports.
     2147/** Gets the source port for a given packet
     2148 * @param packet        The packet to get the source port from
     2149 * @return The source port in HOST byte order or 0 if no suitable port number
     2150 * can be extracted from the packet.
     2151 *
     2152 * This function will return 0 if the transport protocol is known not to
     2153 * use port numbers, e.g. ICMP. 0 is also returned if no transport header is
     2154 * present in the packet or the transport header has been truncated such that
     2155 * the port fields are not readable.
     2156 *
     2157 * @note If the transport protocol is not known by libtrace, the first two
     2158 * bytes of the transport header will be treated as the source port field.
    18812159 */
    18822160DLLEXPORT SIMPLE_FUNCTION
    18832161uint16_t trace_get_source_port(const libtrace_packet_t *packet);
    18842162
    1885 /** Get the destination port
    1886  * @param packet        the packet to read from
    1887  * @return a port in \em HOST byte order, or equivilent to ports for this
    1888  * protocol, or 0 if this protocol has no ports.
     2163/** Gets the destination port for a given packet
     2164 * @param packet        The packet to get the destination port from
     2165 * @return The destination port in HOST byte order or 0 if no suitable port
     2166 * number can be extracted from the packet.
     2167 *
     2168 * This function will return 0 if the transport protocol is known not to
     2169 * use port numbers, e.g. ICMP. 0 is also returned if no transport header is
     2170 * present in the packet or the transport header has been truncated such that
     2171 * the port fields are not readable.
     2172 *
     2173 * @note If the transport protocol is not known by libtrace, the third and
     2174 * fourth bytes of the transport header will be treated as the destination
     2175 * port field.
     2176 *
    18892177 */
    18902178DLLEXPORT SIMPLE_FUNCTION
    18912179uint16_t trace_get_destination_port(const libtrace_packet_t *packet);
    18922180
    1893 /** hint at the server port in specified protocol
    1894  * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
    1895  * @param source        the source port from the packet
    1896  * @param dest          the destination port from the packet
    1897  * @return one of USE_SOURCE or USE_DEST depending on which one you should use
    1898  * @note ports must be in \em HOST byte order!
     2181/** Hint at which of the two provided ports is the server port.
     2182 *
     2183 * @param protocol      The IP layer protocol, eg 6 (tcp), 17 (udp)
     2184 * @param source        The source port from the packet
     2185 * @param dest          The destination port from the packet
     2186 *
     2187 * @return one of USE_SOURCE or USE_DEST describing on which of the two ports
     2188 * is most likely to be the server port.
     2189 *
     2190 * @note Ports must be provided in HOST byte order!
     2191 *
     2192 * This function is based almost entirely on heuristics and should not be
     2193 * treated as a definitive means of identifying the server port. However, it
     2194 * is deterministic, so it is very handy for identifying both halves of the
     2195 * same flow.
    18992196 */
    19002197DLLEXPORT SIMPLE_FUNCTION
    19012198int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
    1902 
    1903 /** Takes a uri and splits it into a format and uridata component.
    1904  * @param uri           the uri to be parsed
    1905  * @param format        destination location for the format component of the uri
    1906  * @return 0 if an error occured, otherwise return the uridata component
    1907  */
    1908 DLLEXPORT const char *trace_parse_uri(const char *uri, char **format);
    1909 
    1910 /** Gets the format type for a given packet.
    1911  * @param packet        the packet opaque pointer
    1912  * @return the format of the packet
    1913  */
    1914 DLLEXPORT
    1915 enum base_format_t trace_get_format(struct libtrace_packet_t *packet);
    1916 
    1917 /** Construct a packet from a buffer.
    1918  * @param packet[in,out]        Libtrace Packet object to update with the new
    1919  *                              data.
    1920  * @param linktype              The linktype of the packet.
    1921  * @param[in] data              The packet data (including linklayer)
    1922  * @param len                   Length of packet data
    1923  */
    1924 DLLEXPORT
    1925 void trace_construct_packet(libtrace_packet_t *packet,
    1926                 libtrace_linktype_t linktype, const void *data, uint16_t len);
    19272199
    19282200/*@}*/
     
    19342206 * The trace_get_wireless_* functions provide an abstract interface for
    19352207 * retrieving information from wireless traces. They take a pointer to the
    1936  * wireless monitoring header (usually found with trace_get_link(packet)) and
     2208 * wireless monitoring header (usually found with trace_get_packet_meta()) and
    19372209 * the linktype of the header passed in.
    19382210 *
     
    19462218
    19472219#ifndef ARPHRD_80211_RADIOTAP
    1948 /* libc doesn't define this yet, but it seems to be what everyone is using
    1949  */
     2220/** libc doesn't define this yet, so we have to do so ourselves */
    19502221#define ARPHRD_80211_RADIOTAP 803
    19512222#endif
    19522223
    1953 /** Get the wireless Timer Syncronisation Function
    1954  *
    1955  * Gets the value of the timer syncronisation function for this frame, which
     2224/** Get the wireless Timer Synchronisation Function
     2225 *
     2226 * Gets the value of the timer synchronisation function for this frame, which
    19562227 * is a value in microseconds indicating the time that the first bit of the
    19572228 * MPDU was received by the MAC.
    19582229 *
    1959  * @param link the wireless header
    1960  * @param linktype the linktype of the wireless header passed in
    1961  * @param[out] tsft the value of the timer syncronisation function.
     2230 * @param link The wireless meta header
     2231 * @param linktype The linktype of the wireless meta header passed in
     2232 * @param[out] tsft The value of the timer synchronisation function.
    19622233 * @return true if the field was available, false if not.
    19632234 */
     
    19652236        libtrace_linktype_t linktype, uint64_t *tsft);
    19662237
    1967 /** Get the wireless rate
    1968  * @param link the wireless header
    1969  * @param linktype the linktype of the wireless header passed in
    1970  * @param[out] rate the data-rate of the frame in units of 500kbps
     2238/** Get the wireless data rate
     2239 *
     2240 * @param link The wireless meta header
     2241 * @param linktype The linktype of the wireless meta header passed in
     2242 * @param[out] rate The data-rate of the frame in units of 500kbps
    19712243 * @return true if the field was available, false if not.
    19722244 */
     
    19752247
    19762248/** Get the wireless channel frequency
    1977  * @param link the wireless header
    1978  * @param linktype the linktype of the wireless header passed in
    1979  * @param[out] freq the frequency in MHz of the channel the frame was transmitted
    1980  * or received on.
     2249 * @param link The wireless meta header
     2250 * @param linktype The linktype of the wireless meta header passed in
     2251 * @param[out] freq The frequency in MHz of the channel the frame was
     2252 * transmitted or received on.
    19812253 * @return true if the field was available, false if not.
    19822254 */
     
    19852257
    19862258/** Get the wireless signal strength in dBm
    1987  * @param link the wireless header
    1988  * @param linktype the linktype of the wireless header passed in
    1989  * @param[out] strength the RF signal power at the antenna, in dB difference
     2259 * @param link The wireless meta header
     2260 * @param linktype The linktype of the wireless meta header passed in
     2261 * @param[out] strength The RF signal power at the antenna, in dB difference
    19902262 * from 1mW.
    19912263 * @return true if the field was available, false if not.
     
    19952267
    19962268/** Get the wireless noise strength in dBm
    1997  * @param link the wireless header
    1998  * @param linktype the linktype of the wireless header passed in
    1999  * @param[out] strength the RF noise power at the antenna, in dB difference
     2269 * @param link The wireless meta header
     2270 * @param linktype The linktype of the wireless meta header passed in
     2271 * @param[out] strength The RF noise power at the antenna, in dB difference
    20002272 * from 1mW.
    20012273 * @return true if the field was available, false if not.
     
    20052277
    20062278/** Get the wireless signal strength in dB
    2007  * @param link the wireless header
    2008  * @param linktype the linktype of the wireless header passed in
    2009  * @param[out] strength the RF signal power at the antenna,in dB difference
     2279 * @param link The wireless meta header
     2280 * @param linktype The linktype of the wireless meta header passed in
     2281 * @param[out] strength The RF signal power at the antenna, in dB difference
    20102282 * from a fixed reference.
    20112283 * @return true if the field was available, false if not.
     
    20152287
    20162288/** Get the wireless noise strength in dB
    2017  * @param link the wireless header
    2018  * @param linktype the linktype of the wireless header passed in
    2019  * @param[out] strength the RF noise power at the antenna, in dB difference
     2289 * @param link The wireless meta header
     2290 * @param linktype The linktype of the wireless meta header passed in
     2291 * @param[out] strength The RF noise power at the antenna, in dB difference
    20202292 * from a fixed reference.
    20212293 * @return true if the field was available, false if not.
     
    20252297
    20262298/** Get the wireless transmit attenuation
    2027  * @param link the wireless header
    2028  * @param linktype the linktype of the wireless header passed in
    2029  * @param[out] attenuation the transmit power as a unitless distance from maximum
    2030  * power set at factory calibration. 0 indicates maximum transmission power.
     2299 * @param link The wireless meta header
     2300 * @param linktype The linktype of the wireless meta header passed in
     2301 * @param[out] attenuation The transmit power as a unitless distance from
     2302 * maximum power set at factory calibration. 0 indicates maximum transmission
     2303 * power.
    20312304 * @return true if the field was available, false if not.
    20322305 */
     
    20352308
    20362309/** Get the wireless transmit attenuation in dB
    2037  * @param link the wireless header
    2038  * @param linktype the linktype of the wireless header passed in
    2039  * @param[out] attenuation the transmit power as dB difference from maximum power
    2040  * set at factory calibration. 0 indicates maximum power.
     2310 * @param link The wireless meta header
     2311 * @param linktype The linktype of the wireless meta header passed in
     2312 * @param[out] attenuation The transmit power as dB difference from maximum
     2313 * power set at factory calibration. 0 indicates maximum power.
    20412314 * @return true if the field was available, false if not.
    20422315 */
     
    20442317        libtrace_linktype_t linktype, uint16_t *attenuation);
    20452318
    2046 /** Get the wireless transmit power in dBm @param link the wireless header
    2047  * @param linktype the linktype of the wireless header passed in
    2048  * @param[out] txpower the transmit power as dB from a 1mW reference. This is the absolute power level measured at the antenna port. 
     2319/** Get the wireless transmit power in dBm
     2320 * @param link The wireless meta header
     2321 * @param linktype The linktype of the wireless meta header passed in
     2322 * @param[out] txpower The transmit power as dB from a 1mW reference. This is
     2323 * the absolute power level measured at the antenna port. 
    20492324 * @return true if the field was available, false if not.
    20502325 */
    2051 DLLEXPORT bool trace_get_wireless_tx_power_dbm(void *linkptr, libtrace_linktype_t
    2052                 linktype, int8_t *txpower);
     2326DLLEXPORT bool trace_get_wireless_tx_power_dbm(void *linkptr,
     2327                libtrace_linktype_t linktype, int8_t *txpower);
    20532328
    20542329/** Get the wireless antenna
    2055  * @param link the wireless header
    2056  * @param linktype the linktype of the wireless header passed in
    2057  * @param[out] antenna which antenna was used to transmit or receive the frame.
     2330 * @param link The wireless meta header
     2331 * @param linktype The linktype of the wireless meta header passed in
     2332 * @param[out] antenna The antenna that was used to transmit or receive the
     2333 * frame.
    20582334 * @return true if the field was available, false if not.
    20592335 */
Note: See TracChangeset for help on using the changeset viewer.