Changeset 37592ce


Ignore:
Timestamp:
11/02/07 15:49:32 (14 years ago)
Author:
Perry Lorier <perry@…>
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:
e53fbe1
Parents:
edd8a9e
Message:

Try and clarify the documentation about the *remaining parameter in the
trace_get_payload_from_* functions

File:
1 edited

Legend:

Unmodified
Added
Removed
  • lib/libtrace.h.in

    r988e253 r37592ce  
    940940 * @param packet the packet pointer
    941941 * @param[out] linktype the linktype of the returned pointer
    942  * @param[out] remaining the capture length (number of valid bytes from the
    943  * pointer)
     942 * @param[out] remaining the capture length (the number of captured bytes from
     943 * the returned pointer)
    944944 * @return a pointer to the first byte of the packet
    945945 */
     
    964964 *
    965965 * @return a pointer to the IPv4 header, or NULL if there is no IPv4 header
     966 *
     967 * You should consider using \ref trace_get_layer3 instead of this function.
    966968 */
    967969DLLEXPORT SIMPLE_FUNCTION
     
    972974 *
    973975 * @return a pointer to the IPv6 header, or NULL if there is no IPv6 header
     976 *
     977 * You should consider using \ref trace_get_layer3 instead of this function.
    974978 */
    975979DLLEXPORT SIMPLE_FUNCTION
     
    991995 * @param packet the libtrace packet
    992996 * @param[out] linktype the linktype of the returned metadata header
    993  * @param[out] remaining the amount of space availabled after this header
    994  * @return a pointer to the first metadata header, or NULL if there are no metadata headers present.
     997 * @param[out] remaining the number of bytes captured after the returned
     998 * pointer.
     999 * @return a pointer to the first metadata header, or NULL if there are no
     1000 * metadata headers present.
    9951001 *
    9961002 * remaining may be NULL, however linktype must be provided.
     
    10651071 *
    10661072 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1067  * of bytes captured of the layer2 header and beyond.  It will be updated after
    1068  * this function to the number of bytes remaining after the layer2 header
    1069  * was removed.
     1073 * of bytes captured of the layer2 header and beyond.  It will be decremented
     1074 * by the number of bytes skipped to find the payload.
    10701075 *
    10711076 */
     
    10831088 *
    10841089 * @return a pointer to the layer 3 header.
    1085  * remaining may be NULL, otherwise it will be filled in by the remaining size
    1086  * of the captured packet.
     1090 * remaining may be NULL, otherwise it will be set to the number of captured
     1091 * bytes after the pointer returned.
    10871092 */
    10881093DLLEXPORT SIMPLE_FUNCTION
     
    10941099 * @param[out] proto    transport layer protocol
    10951100 *
    1096  * @return a pointer to the transport layer header, or NULL if there is no header
     1101 * @return a pointer to the transport layer header, or NULL if there is no
     1102 * header
    10971103 *
    10981104 * @note proto may be NULL if proto is unneeded.
    10991105 */
    1100 DLLEXPORT void *trace_get_transport(const libtrace_packet_t *packet, uint8_t *proto,
    1101                 uint32_t *remaining);
     1106DLLEXPORT void *trace_get_transport(const libtrace_packet_t *packet,
     1107                uint8_t *proto, uint32_t *remaining);
    11021108
    11031109/** Gets a pointer to the payload given a pointer to the IP header
     
    11061112 * @param[in,out] remaining Updated with the number of bytes remaining
    11071113 *
    1108  * @return a pointer to the transport layer header, or NULL if header isn't present.
     1114 * @return a pointer to the transport layer header, or NULL if header isn't
     1115 * present.
    11091116 *
    11101117 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1111  * of bytes captured of the IP header and beyond.  It will be updated after this
    1112  * function to the number of bytes remaining after the IP header (and any IP options)
    1113  * have been removed.
     1118 * of bytes captured of the IP header and beyond.  It will be decremented by
     1119 * the length of the IPv4 header (including any options).
    11141120 *
    11151121 * proto may be NULL if not needed.
     
    11251131 * @param[in,out] remaining Updated with the number of bytes remaining
    11261132 *
    1127  * @return a pointer to the transport layer header, or NULL if the IPv6 header isn't complete.
     1133 * @return a pointer to the transport layer header, or NULL if the IPv6 header
     1134 * isn't complete.
    11281135 *
    11291136 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1130  * of bytes captured of the IP header and beyond.  It will be updated after this
    1131  * function to the number of bytes remaining after the IP header (and any IP options)
    1132  * have been removed.
     1137 * of bytes captured of the IP header and beyond.  It will be decremented by
     1138 * this function by the length of the IPV6 header.
    11331139 *
    11341140 * proto may be NULL if not needed.
     
    11591165
    11601166/** Skips over any 802.1q headers, if present.
    1161  * @param ethernet      A pointer to the payload following an ethernet header -usually the result of calling trace_get_payload_from_link
     1167 * @param ethernet      A pointer to the payload following an ethernet header
     1168 * -usually the result of calling trace_get_payload_from_link
    11621169 * @param[in,out] type  The ethernet type, replaced with the vlan ether type
    11631170 * @param[in,out] remaining Updated with the number of bytes remaining
     
    11671174 *
    11681175 * Remaining may be NULL. If Remaining is not NULL it must point to the number
    1169  * of bytes captured past (but not including) the link layer. It will be
    1170  * updated after this function to the number of bytes remaining after the
    1171  * vlan header. If it is unchanged then no vlan header exists.
     1176 * of bytes captured past (but not including) the link layer. This function
     1177 * will decrement it by the length of the 802.1q headers if present.
    11721178 *
    11731179 * Type must point to the value of the ethernet type. Libtrace will assert
     
    11851191 *
    11861192 * Remaining may be NULL.  If remaining is not NULL it must point to the number
    1187  * of bytes captured of the TCP header and beyond.  It will be updated after
    1188  * this function to the number of bytes remaining after the TCP header (and any
    1189  * TCP options) have been removed.
     1193 * of bytes captured of the TCP header and beyond.  It will be decremented by
     1194 * this function by the length of the TCP header (including any options).
    11901195 *
    11911196 */
     
    12001205 *
    12011206 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1202  * of bytes captured of the UDP header and beyond.  It will be updated after
     1207 * of bytes captured of the UDP header and beyond.  It will be decremented by
    12031208 * this function to the number of bytes remaining after the UDP header.
    12041209 *
     
    12131218 *
    12141219 * Remaining may be NULL.  If remaining is not NULL it must point to the number
    1215  * of bytes captured of the ICMP header and beyond.  It will be updated after
    1216  * this function to the number of bytes remaining after the ICMP header.
     1220 * of bytes captured of the ICMP header and beyond.  It will be decremented
     1221 * by the number of bytes in the ICMP header.
    12171222 *
    12181223 */
     
    12241229 *
    12251230 * @return a pointer to the TCP header, or NULL if there is not a TCP packet
     1231 *
     1232 * @note you should probably use trace_get_transport()
    12261233 */
    12271234DLLEXPORT SIMPLE_FUNCTION
     
    12351242 *
    12361243 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1237  * of bytes captured of the TCP header and beyond.  It will be updated after
    1238  * this function to the number of bytes remaining after the TCP header (and any
    1239  * TCP options) have been removed.
     1244 * of bytes captured of the TCP header and beyond.  It will be decremented by
     1245 * the number of bytes in the TCP header (including any TCP options).
    12401246 *
    12411247 * @note The last parameter has changed from libtrace2
     
    12591265 *
    12601266 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1261  * of bytes captured of the UDP header and beyond.  It will be updated after
    1262  * this function to the number of bytes remaining after the UDP header have
    1263  * been removed.
     1267 * of bytes captured of the UDP header and beyond.  This function will
     1268 * decremented it by the length of the UDP header.
    12641269 *
    12651270 * @note Beware the change from libtrace2 from skipped to remaining
     
    12831288 *
    12841289 * Remaining may be NULL.  If Remaining is not NULL it must point to the number
    1285  * of bytes captured of the ICMP header and beyond.  It will be updated after
    1286  * this function to the number of bytes remaining after the ICMP header.
     1290 * of bytes captured of the ICMP header and beyond.  It will be decremented by
     1291 * the length of the ICMP head in bytes.
    12871292 *
    12881293 * @note Beware the change from libtrace2 from skipped to remaining
Note: See TracChangeset for help on using the changeset viewer.