The Open Group Base Specifications Issue 7
IEEE Std 1003.1-2008, 2016 Edition
Copyright © 2001-2016 The IEEE and The Open Group

#### NAME

> pipe - create an interprocess channel

#### SYNOPSIS

> ``#include <unistd.h>
> int pipe(int` fildes`[2]);
> ``

#### DESCRIPTION

> The pipe() function shall create a pipe and place two file descriptors, one each into the arguments fildes[0] and fildes[1], that refer to the open file descriptions for the read and write ends of the pipe. The file descriptors shall be allocated as described in File Descriptor Allocation. The O_NONBLOCK and FD_CLOEXEC flags shall be clear on both file descriptors. (The fcntl() function can be used to set both these flags.)

> Data can be written to the file descriptor fildes[1] and read from the file descriptor fildes[0]. A read on the file descriptor fildes[0] shall access data written to the file descriptor fildes[1] on a first-in-first-out basis. It is unspecified whether fildes[0] is also open for writing and whether fildes[1] is also open for reading.

> A process has the pipe open for reading (correspondingly writing) if it has a file descriptor open that refers to the read end, fildes[0] (write end, fildes[1]).

> The pipe's user ID shall be set to the effective user ID of the calling process.

> The pipe's group ID shall be set to the effective group ID of the calling process.

> Upon successful completion, pipe() shall mark for update the last data access, last data modification, and last file status change timestamps of the pipe.

#### RETURN VALUE

> Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to indicate the error, no file descriptors shall be allocated and the contents of fildes shall be left unmodified.

#### ERRORS

> The pipe() function shall fail if:

> [EMFILE]
>   All, or all but one, of the file descriptors available to the process are currently open.
> [ENFILE]
>   The number of simultaneously open files in the system would exceed a system-imposed limit.

The following sections are informative.

#### EXAMPLES

> ##### Using a Pipe to Pass Data Between a Parent Process and a Child Process

> The following example demonstrates the use of a pipe to transfer data between a parent process and a child process. Error handling is excluded, but otherwise this code demonstrates good practice when using pipes: after the fork() the two processes close the unused ends of the pipe before they commence transferring data.

>     #include <stdlib.h>
>     #include <unistd.h>
>     ...

>     int fildes[2];
>     const int BSIZE = 100;
>     char buf[BSIZE];
>     ssize_t nbytes;
>     int status;

>     status = pipe(fildes);
>     if (status == -1 ) {
>         /* an error occurred */
>         ...
>     }

>     switch (fork()) {
>     case -1: /* Handle error */
>         break;

>     case 0:  /* Child - reads from pipe */
>         close(fildes[1]);                       /* Write end is unused */
>         nbytes = read(fildes[0], buf, BSIZE);   /* Get data from pipe */
>         /* At this point, a further read would see end-of-file ... */
>         close(fildes[0]);                       /* Finished with pipe */
>         exit(EXIT_SUCCESS);

>     default:  /* Parent - writes to pipe */
>         close(fildes[0]);                       /* Read end is unused */
>         write(fildes[1], "Hello world\n", 12);  /* Write data on pipe */
>         close(fildes[1]);                       /* Child will see EOF */
>         exit(EXIT_SUCCESS);
>     }

#### APPLICATION USAGE

> None.

#### RATIONALE

> The wording carefully avoids using the verb "to open" in order to avoid any implication of use of open(); see also write().

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> File Descriptor Allocation, fcntl, read, write

> XBD <fcntl.h>, <unistd.h>

#### CHANGE HISTORY

> First released in Issue 1. Derived from Issue 1 of the SVID.

#### Issue 6

> The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:

> - The DESCRIPTION is updated to indicate that certain dispositions of fildes[0] and fildes[1] are unspecified.

> IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/65 is applied, adding the example to the EXAMPLES section.

#### Issue 7

> SD5-XSH-ERN-156 is applied, updating the DESCRIPTION to state the setting of the pipe's user ID and group ID.

> Changes are made related to support for finegrained timestamps.

> POSIX.1-2008, Technical Corrigendum 2, XSH/TC2-2008/0247 [835] and XSH/TC2-2008/0248 [467,835] are applied.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2016 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]