diff options
Diffstat (limited to 'man2/pipe.2')
| -rw-r--r-- | man2/pipe.2 | 304 |
1 files changed, 0 insertions, 304 deletions
diff --git a/man2/pipe.2 b/man2/pipe.2 deleted file mode 100644 index 3634a8c27..000000000 --- a/man2/pipe.2 +++ /dev/null @@ -1,304 +0,0 @@ -.\" 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>.) -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" 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 (date) "Linux man-pages (unreleased)" -.SH NAME -pipe, pipe2 \- create pipe -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <unistd.h> -.PP -.BI "int pipe(int " pipefd [2]); -.PP -.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" -.BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" -.B #include <unistd.h> -.PP -.BI "int pipe2(int " pipefd "[2], int " flags ); -.PP -/* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64, pipe() has the - following prototype; see NOTES */ -.PP -.B #include <unistd.h> -.PP -.B struct fd_pair { -.B " long fd[2];" -.B "};" -.B struct fd_pair pipe(void); -.fi -.SH DESCRIPTION -.BR pipe () -creates a pipe, a unidirectional data channel that -can be used for interprocess communication. -The array -.I pipefd -is used to return two file descriptors referring to the ends of the pipe. -.I pipefd[0] -refers to the read end of the pipe. -.I 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 -.I flags -is 0, then -.BR pipe2 () -is the same as -.BR pipe (). -The following values can be bitwise ORed in -.I 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 \[bu] 3 -Writes of greater than -.B PIPE_BUF -bytes (see -.BR pipe (7)) -will be split into multiple packets. -The constant -.B PIPE_BUF -is defined in -.IR <limits.h> . -.IP \[bu] -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 -.B PIPE_BUF -will be sufficient to read the largest possible packets -(see the previous point). -.IP \[bu] -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 -.B 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. -.TP -.B O_NOTIFICATION_PIPE -Since Linux 5.8, -.\" commit c73be61cede5882f9605a852414db559c0ebedfd -general notification mechanism is built on the top of the pipe where -kernel splices notification messages into pipes opened by user space. -The owner of the pipe has to tell the kernel which sources of events to watch -and filters can also be applied to select -which subevents should be placed into the pipe. -.SH RETURN VALUE -On success, zero is returned. -On error, \-1 is returned, -.I errno -is set to indicate the error, 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). -.TP -.B ENOPKG -.RB ( pipe2 ()) -.B O_NOTIFICATION_PIPE -was passed in -.I flags -and support for notifications -.RB ( CONFIG_WATCH_QUEUE ) -is not compiled into the kernel. -.SH VERSIONS -.\" 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 STANDARDS -.TP -.BR pipe () -POSIX.1-2008. -.TP -.BR pipe2 () -Linux. -.SH HISTORY -.TP -.BR pipe () -POSIX.1-2001. -.TP -.BR pipe2 () -Linux 2.6.27, -glibc 2.9. -.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 -.\" SRC BEGIN (pipe.c) -.EX -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <sys/wait.h> -#include <unistd.h> -\& -int -main(int argc, char *argv[]) -{ - int pipefd[2]; - char buf; - pid_t cpid; -\& - 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 -.\" SRC END -.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) |