IPQ_READ(3)

🌸 NAME 🌸

okay bestie, this is IPQ_READ(3) — the manual page for ipq_read — straight from the Linux Programmer's Manual, and she reads queue messages from ip_queue and reads them into the supplied buffer. she's giving kernel gossip courier and honestly? iconic. 💅✨

✨ SYNOPSIS ✨

#include <linux/netfilter.h>
#include <libipq.h>

ssize_t ipq_read(const struct ipq_handle *h, unsigned char *buf, size_t
len, int timeout);

💖 DESCRIPTION 💖

okay so the ipq_read function reads a queue message from the kernel and copies it into the memory pointed to by buf, up to a maximum length of len. copy that, bestie.

The h parameter is a context handle, and it must have already come back successfully from a call to ipq_create_handle. no random handles, no shortcuts — she needs the real one.

The caller is responsible for making sure the memory pointed to by buf is large enough to hold len bytes. translation: you brought the buffer, you make sure it fits. 🙈

The timeout parameter can set a timeout for the operation, specified in microseconds. This is implemented internally by the library via the select system call. A value of zero gives normal, backwards-compatible blocking behaviour with no timeout. A negative value causes the function to return immediately. so: zero means normal blocking, negative means return immediately; the timeout itself is in microseconds. 💫

⚠️ bestie, do not access the data returned via buf directly. Use ipq_message_type, ipq_get_packet, and ipq_get_msgerr to access the queue message in the buffer. that's the whole vibe check. 🫶

🫶 RETURN VALUE 🫶

• On failure, -1 is returned. oop.
• On success, a non-zero positive value is returned when no timeout value is specified. positive vibes, positive return.
• On success with a timeout value specified, zero is returned if no data was available to read, or if a non-blocked signal was caught. In the latter case, the global errno value will be set to EINTR. that's EINTR, not a personality flaw.

💅 ERRORS 💅

On error, a descriptive error message will be available via the ipq_errstr function. go read the message, bestie — she left you notes.

🔥 DIAGNOSTICS 🔥

Even when the ipq_read function returns successfully, the queue message copied into the buffer may itself be an error message from a higher level kernel component. Use ipq_message_type to determine if it is an error message, and ipq_get_msgerr to access the value of the message. success at the read level does not automatically mean success at the message level — check before you celebrate. 🔥

💀 BUGS 💀

None known. genuinely none known — no cap, no secret bug section lurking. 💀

👑 AUTHOR 👑

James Morris <jmorris@intercode.com.au> the author, the icon, the legend. 👑

🌈 COPYRIGHT 🌈

Copyright (c) 2000-2001 Netfilter Core Team.

Distributed under the GNU General Public License. open source, bestie. 🌈

🦋 CREDITS 🦋

Joost Remijn implemented the timeout feature, which appeared in the 1.2.4 release of iptables. shoutout Joost for the timeout feature — she ate. 🦋

⭐ SEE ALSO ⭐

• iptables(8)
• libipq(3)
• select(2)

mwah 💋 this page is from Linux iptables 1.2, dated 16 October 2001, and the manual name is IPQ_READ(3).