| .\" Copyright (C) 2005, 2008, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" (A few fragments remain from an earlier (1992) version by |
| .\" Drew Eckhardt <drew@cs.colorado.edu>.) |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified by Michael Haardt <michael@moria.de> |
| .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" Modified 2005, mtk: added an example program |
| .\" Modified 2008-01-09, mtk: rewrote DESCRIPTION; minor additions |
| .\" to EXAMPLE text. |
| .\" 2008-10-10, mtk: add description of pipe2() |
| .\" |
| .TH PIPE 2 2020-06-09 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| pipe, pipe2 \- create pipe |
| .SH SYNOPSIS |
| .nf |
| .B #include <unistd.h> |
| .PP |
| /* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64; see NOTES */ |
| .B struct fd_pair { |
| .B " long fd[2];" |
| .B "};" |
| .B struct fd_pair pipe(); |
| .PP |
| /* On all other architectures */ |
| .BI "int pipe(int " pipefd "[2]);" |
| |
| .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| .BR "#include <fcntl.h>" " /* Obtain O_* constant definitions */" |
| .B #include <unistd.h> |
| .PP |
| .BI "int pipe2(int " pipefd "[2], int " flags ); |
| .fi |
| .SH DESCRIPTION |
| .BR pipe () |
| creates a pipe, a unidirectional data channel that |
| can be used for interprocess communication. |
| The array |
| .IR pipefd |
| is used to return two file descriptors referring to the ends of the pipe. |
| .IR pipefd[0] |
| refers to the read end of the pipe. |
| .IR pipefd[1] |
| refers to the write end of the pipe. |
| Data written to the write end of the pipe is buffered by the kernel |
| until it is read from the read end of the pipe. |
| For further details, see |
| .BR pipe (7). |
| .PP |
| If |
| .IR flags |
| is 0, then |
| .BR pipe2 () |
| is the same as |
| .BR pipe (). |
| The following values can be bitwise ORed in |
| .IR flags |
| to obtain different behavior: |
| .TP |
| .B O_CLOEXEC |
| Set the close-on-exec |
| .RB ( FD_CLOEXEC ) |
| flag on the two new file descriptors. |
| See the description of the same flag in |
| .BR open (2) |
| for reasons why this may be useful. |
| .TP |
| .BR O_DIRECT " (since Linux 3.4)" |
| .\" commit 9883035ae7edef3ec62ad215611cb8e17d6a1a5d |
| Create a pipe that performs I/O in "packet" mode. |
| Each |
| .BR write (2) |
| to the pipe is dealt with as a separate packet, and |
| .BR read (2)s |
| from the pipe will read one packet at a time. |
| Note the following points: |
| .RS |
| .IP * 3 |
| Writes of greater than |
| .BR PIPE_BUF |
| bytes (see |
| .BR pipe (7)) |
| will be split into multiple packets. |
| The constant |
| .BR PIPE_BUF |
| is defined in |
| .IR <limits.h> . |
| .IP * |
| If a |
| .BR read (2) |
| specifies a buffer size that is smaller than the next packet, |
| then the requested number of bytes are read, |
| and the excess bytes in the packet are discarded. |
| Specifying a buffer size of |
| .BR PIPE_BUF |
| will be sufficient to read the largest possible packets |
| (see the previous point). |
| .IP * |
| Zero-length packets are not supported. |
| (A |
| .BR read (2) |
| that specifies a buffer size of zero is a no-op, and returns 0.) |
| .RE |
| .IP |
| Older kernels that do not support this flag will indicate this via an |
| .B EINVAL |
| error. |
| .IP |
| Since Linux 4.5, |
| .\" commit 0dbf5f20652108106cb822ad7662c786baaa03ff |
| .\" FIXME . But, it is not possible to specify O_DIRECT when opening a FIFO |
| it is possible to change the |
| .B O_DIRECT |
| setting of a pipe file descriptor using |
| .BR fcntl (2). |
| .TP |
| .B O_NONBLOCK |
| Set the |
| .BR O_NONBLOCK |
| file status flag on the open file descriptions |
| referred to by the new file descriptors. |
| Using this flag saves extra calls to |
| .BR fcntl (2) |
| to achieve the same result. |
| .SH RETURN VALUE |
| On success, zero is returned. |
| On error, \-1 is returned, |
| .I errno |
| is set appropriately, and |
| .I pipefd |
| is left unchanged. |
| .PP |
| On Linux (and other systems), |
| .BR pipe () |
| does not modify |
| .I pipefd |
| on failure. |
| A requirement standardizing this behavior was added in POSIX.1-2008 TC2. |
| .\" http://austingroupbugs.net/view.php?id=467 |
| The Linux-specific |
| .BR pipe2 () |
| system call |
| likewise does not modify |
| .I pipefd |
| on failure. |
| .SH ERRORS |
| .TP |
| .B EFAULT |
| .I pipefd |
| is not valid. |
| .TP |
| .B EINVAL |
| .RB ( pipe2 ()) |
| Invalid value in |
| .IR flags . |
| .TP |
| .B EMFILE |
| The per-process limit on the number of open file descriptors has been reached. |
| .TP |
| .B ENFILE |
| The system-wide limit on the total number of open files has been reached. |
| .TP |
| .B ENFILE |
| The user hard limit on memory that can be allocated for pipes |
| has been reached and the caller is not privileged; see |
| .BR pipe (7). |
| .SH VERSIONS |
| .BR pipe2 () |
| was added to Linux in version 2.6.27; |
| glibc support is available starting with |
| version 2.9. |
| .SH CONFORMING TO |
| .BR pipe (): |
| POSIX.1-2001, POSIX.1-2008. |
| .PP |
| .BR pipe2 () |
| is Linux-specific. |
| .SH NOTES |
| .\" See http://math-atlas.sourceforge.net/devel/assembly/64.psabi.1.33.ps.Z |
| .\" for example, section 3.2.1 "Registers and the Stack Frame". |
| The System V ABI on some architectures allows the use of more than one register |
| for returning multiple values; several architectures |
| (namely, Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64) |
| (ab)use this feature in order to implement the |
| .BR pipe () |
| system call in a functional manner: |
| the call doesn't take any arguments and returns |
| a pair of file descriptors as the return value on success. |
| The glibc |
| .BR pipe () |
| wrapper function transparently deals with this. |
| See |
| .BR syscall (2) |
| for information regarding registers used for storing second file descriptor. |
| .SH EXAMPLES |
| .\" fork.2 refers to this example program. |
| The following program creates a pipe, and then |
| .BR fork (2)s |
| to create a child process; |
| the child inherits a duplicate set of file |
| descriptors that refer to the same pipe. |
| After the |
| .BR fork (2), |
| each process closes the file descriptors that it doesn't need for the pipe |
| (see |
| .BR pipe (7)). |
| The parent then writes the string contained in the program's |
| command-line argument to the pipe, |
| and the child reads this string a byte at a time from the pipe |
| and echoes it on standard output. |
| .SS Program source |
| .EX |
| #include <sys/types.h> |
| #include <sys/wait.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <unistd.h> |
| #include <string.h> |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| int pipefd[2]; |
| pid_t cpid; |
| char buf; |
| |
| if (argc != 2) { |
| fprintf(stderr, "Usage: %s <string>\en", argv[0]); |
| exit(EXIT_FAILURE); |
| } |
| |
| if (pipe(pipefd) == \-1) { |
| perror("pipe"); |
| exit(EXIT_FAILURE); |
| } |
| |
| cpid = fork(); |
| if (cpid == \-1) { |
| perror("fork"); |
| exit(EXIT_FAILURE); |
| } |
| |
| if (cpid == 0) { /* Child reads from pipe */ |
| close(pipefd[1]); /* Close unused write end */ |
| |
| while (read(pipefd[0], &buf, 1) > 0) |
| write(STDOUT_FILENO, &buf, 1); |
| |
| write(STDOUT_FILENO, "\en", 1); |
| close(pipefd[0]); |
| _exit(EXIT_SUCCESS); |
| |
| } else { /* Parent writes argv[1] to pipe */ |
| close(pipefd[0]); /* Close unused read end */ |
| write(pipefd[1], argv[1], strlen(argv[1])); |
| close(pipefd[1]); /* Reader will see EOF */ |
| wait(NULL); /* Wait for child */ |
| exit(EXIT_SUCCESS); |
| } |
| } |
| .EE |
| .SH SEE ALSO |
| .BR fork (2), |
| .BR read (2), |
| .BR socketpair (2), |
| .BR splice (2), |
| .BR tee (2), |
| .BR vmsplice (2), |
| .BR write (2), |
| .BR popen (3), |
| .BR pipe (7) |