pipe

QNX SDP8.0Utilities ReferenceUtilities

Pipe manager (QNX OS)

Syntax:

pipe [-1Pd] [-a atomic_write_size] [-s pipe_buffer_size]
     [-t max:low:high:inc] [-U string]

Runs on:

QNX OS

Options:

-1
(One) Unblock poll() for writing when _PC_PIPE_BUF bytes are available. (The default is 1 byte.) For more information about _PC_PIPE_BUF, see the Description section below.
-a atomic_write_size
Set the atomic write size for _PC_PIPE_BUF. (The default is 5120 bytes.) For more information about _PC_PIPE_BUF, see the Description section below.
-d
Don't daemonize.
-P
Synchronize the modification of POSIX attributes to the host filesystem.
-s pipe_buffer_size
Set the buffer size per pipe. (The default is 5120 bytes.)
-t max:low:high:inc
Set the thread pool parameter in the specified order for maximum, low-water, high-water and increment. The default parameters are as follows:
Thread pool parameter Default
max (maximum) 12
low (low-water) 2
high (high-water) 4
inc (increment) 1
-U string
Once running, run as the specified user, so that the program doesn't need to run as root. The string can be in one of these forms:
  • uid[:gid[,sup_gid]*]
  • user_name[,sup_gid]*

In the second form, the primary group is the one specified for user_name in /etc/passwd.

Description:

The pipe manager implements the subset of file I/O known as pipes (or anonymous FIFOs). A simple form of interprocess communication, pipes are mostly used to connect the output of one process to the input of another to form a series of filters.

The atomic_write_size is the size for which it's guaranteed that a write() of data won't be interleaved with data from any other process; in other words the amount of data that will be written atomically. This is required when there are multiple writers sending data to a single reader. The POSIX maximum is referred to as PIPE_BUF, and can be queried at runtime using fpathconf(_PC_PIPE_BUF). It isn't recommended to lower this value from the default 5120 bytes in case application code is using the PIPE_BUF manifest from <limits.h> rather than a runtime fpathconf() determination.

The pipe_buffer_size is the total buffer size per pipe. Effectively, the pipe utility can hold this many (unread) bytes before write() clients start to block or fail with EAGAIN (based on their O_NONBLOCK disposition). The pipe_buffer_size must be set to at least the atomic_write_size. Otherwise, it will be automatically adjusted as equal to the atomic_write_size.

There is no simple mechanism (such as fpathconf()) to query the pipe-buffering capacity, but it can be determined by writing one byte at a time to an empty O_NONBLOCK pipe and counting how many are consumed until an EAGAIN error (full-pipe indication) is returned. Increasing this value could make pipelines more elastic, in terms of decoupling the writer from the reader processes, at the expense of using extra system memory for each pipe. Across a sample of OSs, pipe-buffering capacity is in the 4–16 KB range.

Strict POSIX conformance requires that the atime and mtime attributes of a FIFO be updated for every read() and write() operation. As FIFOs operate by redirecting access of the FIFO from the host filesystem to the pipe server, maintaining these attributes requires additional synchronization messages from the pipe server back to the host filesystem. In most cases, this level of synchronization isn't required, and by default is performed only at the last close() of the FIFO. For strict POSIX conformance, specify the -P option.

The -1 option sets the behavior for poll() write notification of the pipe utility. The original behavior was to satisfy or unblock poll() clients even if 1 byte of buffer space was available. POSIX specifies a different behavior. Since the atomic write size and the total buffer size are both equal to 5120 bytes, poll() would be satisfied only on an empty pipe, which may impact performance or establish a lock-step timing between the writing and reading processes. If this option is enabled, consider also increasing the -s to be larger than PIPE_BUF so that the pipe doesn't have to completely drain before a poll() for write is satisfied.

Exit status:

The pipe utility terminates only if an error occurs during startup. If pipe fails during startup, it prints a diagnostic message to the standard output stream and then exits with a nonzero status.

Page updated: