[PATCH libnetfilter_queue 1/5] src: doc: Miscellaneous updates

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



(These updates only cover functions used in a recent project)

 src/extra/ipv4.c: - nfq_ip_set_transport_header(): Add explanatory notes
                   - nfq_ip_mangle()
                     - Advise that there is a return code
                     - Note that IPv4 length is updated as well as checksum

 src/extra/pktbuff.c: - pktb_alloc(): Minor rewording (English usage)
                      - pktb_mangle(): Document

 src/extra/udp.c: - nfq_udp_get_hdr(): Fix params
                  - nfq_udp_get_payload(): Fix params
                  - nfq_udp_get_payload_len(): Fix params
                  - nfq_udp_mangle_ipv4(): Rewrite documentation

 src/nlmsg.c: - nfq_nlmsg_verdict_put(): Document
              - nfq_nlmsg_cfg_put_cmd():
                - Change name (was: nfq_nlmsg_cfg_build_request)
                - Fix params
                - Delete function return documentation (void fn)
              - nfq_nlmsg_cfg_put_params(); Document (params only)
              - nfq_nlmsg_cfg_put_qmaxlen(): Document (params only)
              - nfq_nlmsg_parse:
                - Change name (was: nfq_pkt_parse)
                - Fix params

Signed-off-by: Duncan Roe <duncan_roe@xxxxxxxxxxxxxxx>
---
 src/extra/ipv4.c    |  9 +++++++--
 src/extra/pktbuff.c | 15 ++++++++++++++-
 src/extra/udp.c     | 28 +++++++++++++++-------------
 src/nlmsg.c         | 36 +++++++++++++++++++++++++++---------
 4 files changed, 63 insertions(+), 25 deletions(-)

diff --git a/src/extra/ipv4.c b/src/extra/ipv4.c
index a93d113..20f3c12 100644
--- a/src/extra/ipv4.c
+++ b/src/extra/ipv4.c
@@ -59,6 +59,10 @@ EXPORT_SYMBOL(nfq_ip_get_hdr);
  * nfq_ip_set_transport_header - set transport header
  * \param pktb: pointer to network packet buffer
  * \param iph: pointer to the IPv4 header
+ *
+ * Sets the \b transport_header field in \b pktb
+ *
+ * Level 4 helper functions need this to be set.
  */
 int nfq_ip_set_transport_header(struct pkt_buff *pktb, struct iphdr *iph)
 {
@@ -97,8 +101,9 @@ EXPORT_SYMBOL(nfq_ip_set_checksum);
  * \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 checksum (if needed).
+ * \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
+ * checksum (if necessary)
  */
 int nfq_ip_mangle(struct pkt_buff *pkt, unsigned int dataoff,
 		  unsigned int match_offset, unsigned int match_len,
diff --git a/src/extra/pktbuff.c b/src/extra/pktbuff.c
index 1c15a00..25b173b 100644
--- a/src/extra/pktbuff.c
+++ b/src/extra/pktbuff.c
@@ -36,7 +36,7 @@
  * \param extra Extra memory in the tail to be allocated (for mangling)
  *
  * This function returns a packet buffer that contains the packet data and
- * some extra memory room in the tail (in case of requested).
+ * some extra memory room in the tail (if requested).
  *
  * \return a pointer to a new queue handle or NULL on failure.
  */
@@ -224,6 +224,19 @@ static int enlarge_pkt(struct pkt_buff *pkt, unsigned int extra)
 	return 1;
 }
 
+/**
+ * pktb_mangle - adjust contents of a packet
+ * \param pkt Pointer to packet buffer
+ * \param dataoff Offset to layer 3 header. Specify zero to access layer 2 (IP)
+ * header
+ * \param match_offset Further offset to content that you want to mangle
+ * \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
+ * \returns 1 for success and 0 for failure. Failure will occur if the \b extra
+ * argument to the pktb_alloc() call that created \b pkt is less than the excess
+ * of \b rep_len over \b match_len
+ */
 int pktb_mangle(struct pkt_buff *pkt,
 		 unsigned int dataoff,
 		 unsigned int match_offset,
diff --git a/src/extra/udp.c b/src/extra/udp.c
index f89d314..92165b4 100644
--- a/src/extra/udp.c
+++ b/src/extra/udp.c
@@ -31,8 +31,7 @@
 
 /**
  * nfq_udp_get_hdr - get the UDP header.
- * \param head: pointer to the beginning of the packet
- * \param tail: pointer to the tail of the packet
+ * \param pktb: Pointer to network packet buffer
  *
  * This function returns NULL if invalid UDP header is found. On success,
  * it returns the UDP header.
@@ -52,8 +51,8 @@ EXPORT_SYMBOL(nfq_udp_get_hdr);
 
 /**
  * nfq_udp_get_payload - get the UDP packet payload.
- * \param udph: the pointer to the UDP header.
- * \param tail: pointer to the tail of the packet
+ * \param udph: Pointer to UDP header
+ * \param pktb: Pointer to network packet buffer
  */
 void *nfq_udp_get_payload(struct udphdr *udph, struct pkt_buff *pktb)
 {
@@ -73,7 +72,8 @@ EXPORT_SYMBOL(nfq_udp_get_payload);
 
 /**
  * nfq_udp_get_payload_len - get the udp packet payload.
- * \param udp: the pointer to the udp header.
+ * \param udph: Pointer to UDP header
+ * \param pktb: Pointer to network packet buffer
  */
 unsigned int nfq_udp_get_payload_len(struct udphdr *udph, struct pkt_buff *pktb)
 {
@@ -120,14 +120,16 @@ nfq_udp_compute_checksum_ipv6(struct udphdr *udph, struct ip6_hdr *ip6h)
 EXPORT_SYMBOL(nfq_udp_compute_checksum_ipv6);
 
 /**
- * nfq_tcp_mangle_ipv4 - mangle TCP/IPv4 packet buffer
- * \param pktb: pointer to network packet buffer
- * \param match_offset: offset to content that you want to mangle
- * \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.
+ * nfq_udp_mangle_ipv4 - Mangle UDP/IPv4 packet buffer
+ * \param pktb: Pointer to network packet buffer
+ * \param match_offset: Offset from start of UDP data of content that you want
+ * to mangle
+ * \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
+ * \returns 1 for success and 0 for failure. See pktb_mangle() for failure case
+ * \note This function updates the IPv4 and UDP lengths and recalculates their
+ * checksums for you.
  */
 int
 nfq_udp_mangle_ipv4(struct pkt_buff *pkt,
diff --git a/src/nlmsg.c b/src/nlmsg.c
index ba28c77..ac0adab 100644
--- a/src/nlmsg.c
+++ b/src/nlmsg.c
@@ -30,6 +30,16 @@
  * @{
  */
 
+/**
+ * nfq_nlmsg_verdict_put - Put a verdict into a Netlink header
+ * \param nlh Pointer to netlink message
+ * \param id ID assigned to packet by netfilter
+ * \param verdict verdict to return to netfilter (NF_ACCEPT, NF_DROP)
+ *
+ * See examples/nf-queue.c, line 46 for an example of how to use this function.
+ * The calling sequence is \b main --> \b mnl_cb_run --> \b queue_cb -->
+ * \b nfq_send_verdict --> \b nfq_nlmsg_verdict_put
+ */
 void nfq_nlmsg_verdict_put(struct nlmsghdr *nlh, int id, int verdict)
 {
 	struct nfqnl_msg_verdict_hdr vh = {
@@ -63,13 +73,10 @@ EXPORT_SYMBOL(nfq_nlmsg_verdict_put_pkt);
  */
 
 /**
- * nfq_nlmsg_cfg_build_request- build netlink config message
- * \param buf Buffer where netlink message is going to be written.
- * \param cfg Structure that contains the config parameters.
- * \param command nfqueue nfnetlink command.
- *
- * This function returns a pointer to the netlink message. If something goes
- * wrong it returns NULL.
+ * nfq_nlmsg_cfg_put_cmd Add netlink config command to netlink message
+ * \param nlh Pointer to netlink message
+ * \param pf Packet family (e.g. AF_INET)
+ * \param cmd nfqueue nfnetlink command.
  *
  * Possible commands are:
  *
@@ -95,6 +102,12 @@ void nfq_nlmsg_cfg_put_cmd(struct nlmsghdr *nlh, uint16_t pf, uint8_t cmd)
 }
 EXPORT_SYMBOL(nfq_nlmsg_cfg_put_cmd);
 
+/**
+ * nfq_nlmsg_cfg_put_params Add parameter to netlink message
+ * \param nlh Pointer to netlink message
+ * \param mode one of NFQNL_COPY_NONE, NFQNL_COPY_META or NFQNL_COPY_PACKET
+ * \param range value of parameter
+ */
 void nfq_nlmsg_cfg_put_params(struct nlmsghdr *nlh, uint8_t mode, int range)
 {
 	struct nfqnl_msg_config_params params = {
@@ -105,6 +118,11 @@ void nfq_nlmsg_cfg_put_params(struct nlmsghdr *nlh, uint8_t mode, int range)
 }
 EXPORT_SYMBOL(nfq_nlmsg_cfg_put_params);
 
+/**
+ * nfq_nlmsg_cfg_put_qmaxlen Add queue maximum length to netlink message
+ * \param nlh Pointer to netlink message
+ * \param queue_maxlen Maximum queue length
+ */
 void nfq_nlmsg_cfg_put_qmaxlen(struct nlmsghdr *nlh, uint32_t queue_maxlen)
 {
 	mnl_attr_put_u32(nlh, NFQA_CFG_QUEUE_MAXLEN, htonl(queue_maxlen));
@@ -172,9 +190,9 @@ static int nfq_pkt_parse_attr_cb(const struct nlattr *attr, void *data)
 }
 
 /**
- * nfq_pkt_parse - set packet attributes from netlink message
+ * nfq_nlmsg_parse - set packet attributes from netlink message
  * \param nlh netlink message that you want to read.
- * \param pkt pointer to the packet to set.
+ * \param attr pointer to array of attributes to set.
  *
  * This function returns MNL_CB_ERROR if any error occurs, or MNL_CB_OK on
  * success.
-- 
2.14.5




[Index of Archives]     [Netfitler Users]     [Berkeley Packet Filter]     [LARTC]     [Bugtraq]     [Yosemite Forum]

  Powered by Linux