---
name: "ipq_read"
section: "3"
platform: "linux"
package: "iptables"
version: "1:1.8.13-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ipq_read"
---

# ipq\_read(3)

read queue messages from ip\_queue and read into supplied buffer

## NAME

ipq\_read — read queue messages from ip\_queue and read into supplied buffer

## 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

The **ipq\_read** function reads a queue message from the kernel and copies it to the memory pointed to by  *buf* to a maximum length of *len*.

The *h* parameter is a context handle which must previously have been returned  successfully from a call to **ipq\_create\_handle**.

The caller is responsible for ensuring that the memory pointed to by *buf* is large enough to contain *len* bytes.

The *timeout* parameter may be used to 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 provides normal, backwards-compatible blocking behaviour with no timeout.  A negative value causes the function to return immediately.

Data returned via *buf* should not be accessed directly.  Use the  **ipq\_message\_type**, **ipq\_get\_packet**, and **ipq\_get\_msgerr** functions to access the queue message in the buffer.

## RETURN VALUE

On failure, -1 is returned.\
 On success, a non-zero positive value is returned when no timeout value is specified.\
 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**.

## ERRORS

On error, a descriptive error message will be available via the **ipq\_errstr** function.

## DIAGNOSTICS

While the **ipq\_read** function may return successfully, the queue message copied to 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.

## BUGS

None known.

## AUTHOR

James Morris \<jmorris@intercode.com.au\>

## COPYRIGHT

Copyright (c) 2000-2001 Netfilter Core Team.

Distributed under the GNU General Public License.

## CREDITS

Joost Remijn implemented the timeout feature, which appeared in the 1.2.4 release of iptables.

## SEE ALSO

[**iptables**(8)](/iptables/8.md), [**libipq**(3)](/libipq/3.md), [**select**(2)](/select/2.md).