From ee8bf8f2e9178986ce49c5ebef5545d2d4fb3ad8 Mon Sep 17 00:00:00 2001 From: Duncan Roe Date: Fri, 10 Jan 2020 11:54:43 +1100 Subject: src: doc: Final polish for current round - Ensure all functions that return something have a \returns - Demote more checksum functions to their own groups (reduces number of functions on main pages) - Clarify wording where appropriate - Add \sa (see also) where appropriate - Fix documented function name for nfq_tcp_get_hdr (no other mismatches noticed, but there may be some) - Add warnings regarding changing length of tcp packet - Make group names unique within libnetfilter_queue (else man pages would be overwritten) Signed-off-by: Duncan Roe Signed-off-by: Pablo Neira Ayuso --- src/extra/tcp.c | 46 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 37 insertions(+), 9 deletions(-) (limited to 'src/extra/tcp.c') diff --git a/src/extra/tcp.c b/src/extra/tcp.c index 0f83500..be400c5 100644 --- a/src/extra/tcp.c +++ b/src/extra/tcp.c @@ -32,14 +32,12 @@ */ /** - * nfq_tcp_get - get the TCP header + * nfq_tcp_get_hdr - get the TCP header * \param pktb: pointer to user-space network packet buffer - * - * This function returns NULL if an invalid TCP header is found. On success, - * it returns the TCP header. - * - * \note You have to call nfq_ip_set_transport_header or - * nfq_ip6_set_transport_header first to access the TCP header. + * \returns validated pointer to the TCP header or NULL if the TCP header was + * not set or if a minimal length check fails. + * \note You have to call nfq_ip_set_transport_header() or + * nfq_ip6_set_transport_header() first to set the TCP header. */ EXPORT_SYMBOL struct tcphdr *nfq_tcp_get_hdr(struct pkt_buff *pktb) @@ -58,6 +56,7 @@ struct tcphdr *nfq_tcp_get_hdr(struct pkt_buff *pktb) * nfq_tcp_get_payload - get the TCP packet payload * \param tcph: pointer to the TCP header * \param pktb: pointer to user-space network packet buffer + * \returns Pointer to the TCP payload, or NULL if malformed TCP packet. */ EXPORT_SYMBOL void *nfq_tcp_get_payload(struct tcphdr *tcph, struct pkt_buff *pktb) @@ -79,6 +78,7 @@ void *nfq_tcp_get_payload(struct tcphdr *tcph, struct pkt_buff *pktb) * nfq_tcp_get_payload_len - get the tcp packet payload * \param tcph: pointer to the TCP header * \param pktb: pointer to user-space network packet buffer + * \returns Length of TCP payload (user data) */ EXPORT_SYMBOL unsigned int nfq_tcp_get_payload_len(struct tcphdr *tcph, struct pkt_buff *pktb) @@ -86,10 +86,23 @@ unsigned int nfq_tcp_get_payload_len(struct tcphdr *tcph, struct pkt_buff *pktb) return pktb->tail - pktb->transport_header; } +/** + * \defgroup tcp_internals Internal TCP functions + * + * Most user-space programs will never need these. + * + * @{ + */ + /** * nfq_tcp_compute_checksum_ipv4 - computes IPv4/TCP packet checksum * \param tcph: pointer to the TCP header * \param iph: pointer to the IPv4 header + * \note + * nfq_tcp_mangle_ipv4() invokes this function. + * As long as developers always use __nfq_tcp_mangle_ipv4__ when changing the + * content of a TCP message, there is no need to call + * __nfq_tcp_compute_checksum_ipv4__. */ EXPORT_SYMBOL void nfq_tcp_compute_checksum_ipv4(struct tcphdr *tcph, struct iphdr *iph) @@ -103,6 +116,11 @@ void nfq_tcp_compute_checksum_ipv4(struct tcphdr *tcph, struct iphdr *iph) * nfq_tcp_compute_checksum_ipv6 - computes IPv6/TCP packet checksum * \param tcph: pointer to the TCP header * \param ip6h: pointer to the IPv6 header + * \note + * nfq_tcp_mangle_ipv6() invokes this function. + * As long as developers always use __nfq_tcp_mangle_ipv6__ when changing the + * content of a TCP message, there is no need to call + * __nfq_tcp_compute_checksum_ipv6__. */ EXPORT_SYMBOL void nfq_tcp_compute_checksum_ipv6(struct tcphdr *tcph, struct ip6_hdr *ip6h) @@ -112,6 +130,10 @@ void nfq_tcp_compute_checksum_ipv6(struct tcphdr *tcph, struct ip6_hdr *ip6h) tcph->check = nfq_checksum_tcpudp_ipv6(ip6h, tcph, IPPROTO_TCP); } +/** + * @} + */ + /* * The union cast uses a gcc extension to avoid aliasing problems * (union is compatible to any of its members) @@ -130,6 +152,8 @@ union tcp_word_hdr { * \param buf: pointer to buffer that is used to print the object * \param size: size of the buffer (or remaining room in it). * \param tcph: pointer to a valid tcp header. + * \returns Same as \b snprintf + * \sa __snprintf__(3) * */ EXPORT_SYMBOL @@ -184,8 +208,12 @@ int nfq_tcp_snprintf(char *buf, size_t size, const struct tcphdr *tcph) * \param match_len: length of the existing content you want to mangle * \param rep_buffer: pointer to data you want to use to replace current content * \param rep_len: length of data you want to use to replace current content - * - * \note This function recalculates the IPv4 and TCP checksums for you. + * \returns 1 for success and 0 for failure. See pktb_mangle() for failure case + * \note This function updates the IPv4 length and recalculates the IPv4 & TCP + * checksums for you. + * \warning After changing the length of a TCP message, the application will + * need to mangle sequence numbers in both directions until another change + * puts them in sync again */ EXPORT_SYMBOL int nfq_tcp_mangle_ipv4(struct pkt_buff *pktb, -- cgit v1.2.3