d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
b8b08befd0
freebsd-nq/lib/libc/sys/pipe.2

156 lines
4.2 KiB
Groff
Raw Normal View History

BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)pipe.2 8.1 (Berkeley) 6/4/93
$Id$ -> $FreeBSD$
1999-08-28 00:22:10 +00:00
.\" $FreeBSD$
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.\"
accept(2), pipe(2): Fix .Dd.
2013-05-01 22:47:47 +00:00
.Dd May 1, 2013
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Dt PIPE 2
mdoc(7) police: removed HISTORY info from the .Os call.
2001-07-10 13:41:46 +00:00
.Os
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh NAME
.Nm pipe
.Nd create descriptor pair for interprocess communication
Introduce ".Lb" macro to libc manpages. More libraries manpages updates following.
2000-04-21 09:42:15 +00:00
.Sh LIBRARY
.Lb libc
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh SYNOPSIS
mdoc(7) police: Use the new .In macro for #include statements.
2001-10-01 16:09:29 +00:00
.In unistd.h
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Ft int
Several cleanups related to pipe(2). - Use `fildes[2]' instead of `*fildes' to make more clear that pipe(2) fills an array with two descriptors. - Remove EFAULT from the manual page. Because of the current calling convention, pipe(2) raises a segmentation fault when an invalid address is passed. - Introduce kern_pipe() to make it easier for binary emulations to implement pipe(2). - Make Linux binary emulation use kern_pipe(), which means we don't have to recover td_retval after calling the FreeBSD system call. Approved by: rdivacky Discussed on: arch
2008-11-11 14:55:59 +00:00
.Fn pipe "int fildes[2]"
Add pipe2() system call. The pipe2() function is similar to pipe() but allows setting FD_CLOEXEC and O_NONBLOCK (on both sides) as part of the function. If p points to two writable ints, pipe2(p, 0) is equivalent to pipe(p). If the pointer is not valid, behaviour differs: pipe2() writes into the array from the kernel like socketpair() does, while pipe() writes into the array from an architecture-specific assembler wrapper. Reviewed by: kan, kib
2013-05-01 22:42:42 +00:00
.Ft int
.Fn pipe2 "int fildes[2]" "int flags"
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh DESCRIPTION
The
.Fn pipe
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
system call
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
creates a
.Em pipe ,
which is an object allowing
Document the change that I made to pipe(2)
1996-01-01 15:40:31 +00:00
bidirectional data flow,
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
and allocates a pair of file descriptors.
Document the change that I made to pipe(2)
1996-01-01 15:40:31 +00:00
.Pp
Add pipe2() system call. The pipe2() function is similar to pipe() but allows setting FD_CLOEXEC and O_NONBLOCK (on both sides) as part of the function. If p points to two writable ints, pipe2(p, 0) is equivalent to pipe(p). If the pointer is not valid, behaviour differs: pipe2() writes into the array from the kernel like socketpair() does, while pipe() writes into the array from an architecture-specific assembler wrapper. Reviewed by: kan, kib
2013-05-01 22:42:42 +00:00
The
.Fn pipe2
system call allows control over the attributes of the file descriptors
via the
.Fa flags
argument.
Values for
.Fa flags
are constructed by a bitwise-inclusive OR of flags from the following
list, defined in
.In fcntl.h :
.Bl -tag -width ".Dv O_NONBLOCK"
.It Dv O_CLOEXEC
Set the close-on-exec flag for the new file descriptors.
.It Dv O_NONBLOCK
Set the non-blocking flag for the ends of the pipe.
.El
.Pp
If the
.Fa flags
argument is 0, the behavior is identical to a call to
.Fn pipe .
.Pp
Document the change that I made to pipe(2)
1996-01-01 15:40:31 +00:00
By convention, the first descriptor is normally used as the
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Em read end
of the pipe,
Document the change that I made to pipe(2)
1996-01-01 15:40:31 +00:00
and the second is normally the
Eliminate double whitespace.
2004-07-03 22:30:10 +00:00
.Em write end ,
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
so that data written to
.Fa fildes[1]
appears on (i.e., can be read from)
.Fa fildes[0] .
This allows the output of one program to be
sent
to another program:
the source's standard output is set up to be
the write end of the pipe,
and the sink's standard input is set up to be
the read end of the pipe.
The pipe itself persists until all its associated descriptors are
closed.
.Pp
Document the change that I made to pipe(2)
1996-01-01 15:40:31 +00:00
A pipe that has had an end closed is considered
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Em widowed .
Writing on such a pipe causes the writing process to receive
a
.Dv SIGPIPE
signal.
Widowing a pipe is the only way to deliver end-of-file to a reader:
after the reader consumes any buffered data, reading a widowed pipe
returns a zero count.
.Pp
Document the change that I made to pipe(2)
1996-01-01 15:40:31 +00:00
The bidirectional nature of this implementation of pipes is not
Fix even more spelling errors in some more man pages.
1996-01-30 16:34:52 +00:00
portable to older systems, so it is recommended to use the convention
Document the change that I made to pipe(2)
1996-01-01 15:40:31 +00:00
for using the endpoints in the traditional manner when using a
pipe in one direction.
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh RETURN VALUES
Use the ``.Rv -std'' mdoc(7) macro in appropriate cases. Reviewed by: ru
2001-08-09 13:32:13 +00:00
.Rv -std pipe
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh ERRORS
The
.Fn pipe
Add pipe2() system call. The pipe2() function is similar to pipe() but allows setting FD_CLOEXEC and O_NONBLOCK (on both sides) as part of the function. If p points to two writable ints, pipe2(p, 0) is equivalent to pipe(p). If the pointer is not valid, behaviour differs: pipe2() writes into the array from the kernel like socketpair() does, while pipe() writes into the array from an architecture-specific assembler wrapper. Reviewed by: kan, kib
2013-05-01 22:42:42 +00:00
and
.Fn pipe2
system calls will fail if:
Use `Er' variable to define first column width in ERRORS section. It was initially suggested by mdoc(7) style, but was broken over the years
2000-05-04 13:09:25 +00:00
.Bl -tag -width Er
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.It Bq Er EMFILE
Too many descriptors are active.
.It Bq Er ENFILE
The system file table is full.
- In pipe() return the error returned by pipe_create(), rather then hardcoded ENFILES, which is incorrect. pipe_create() can fail due to ENOMEM. - Update manual page, describing ENOMEM return code. Reviewed by: arch
2006-01-30 08:25:04 +00:00
.It Bq Er ENOMEM
Not enough kernel memory to establish a pipe.
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.El
Add pipe2() system call. The pipe2() function is similar to pipe() but allows setting FD_CLOEXEC and O_NONBLOCK (on both sides) as part of the function. If p points to two writable ints, pipe2(p, 0) is equivalent to pipe(p). If the pointer is not valid, behaviour differs: pipe2() writes into the array from the kernel like socketpair() does, while pipe() writes into the array from an architecture-specific assembler wrapper. Reviewed by: kan, kib
2013-05-01 22:42:42 +00:00
.Pp
The
.Fn pipe2
system call will also fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The
.Fa flags
argument is invalid.
.El
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh SEE ALSO
.Xr sh 1 ,
.Xr fork 2 ,
Sort cross references.
1997-01-20 23:23:22 +00:00
.Xr read 2 ,
.Xr socketpair 2 ,
.Xr write 2
BSD 4.4 Lite Lib Sources
1994-05-27 05:00:24 +00:00
.Sh HISTORY
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
The
Correctly use .Fn instead of .Nm to reference function names in a bunch of man pages. Use the correct .Bx (BSD UNIX) or .At (AT&T UNIX) macros instead of explicitly specifying the version in the text in a bunch of man pages.
1996-08-22 23:31:07 +00:00
.Fn pipe
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe.
2002-12-18 09:22:32 +00:00
function appeared in
Use the .At macro when referencing versions of AT&T UNIX. Note: you need to install the current groff tmac macros for these man pages to format correctly. Specifically, rev 1.21 of contrib_groff/tmac/doc-syms in -current, or rev 1.17.24 for 3.2-stable
1999-07-30 12:45:20 +00:00
.At v3 .
Document the change that I made to pipe(2)
1996-01-01 15:40:31 +00:00
.Pp
Mdoc cleanup.
1999-07-30 07:45:40 +00:00
Bidirectional pipes were first used on
.At V.4 .
Add pipe2() system call. The pipe2() function is similar to pipe() but allows setting FD_CLOEXEC and O_NONBLOCK (on both sides) as part of the function. If p points to two writable ints, pipe2(p, 0) is equivalent to pipe(p). If the pointer is not valid, behaviour differs: pipe2() writes into the array from the kernel like socketpair() does, while pipe() writes into the array from an architecture-specific assembler wrapper. Reviewed by: kan, kib
2013-05-01 22:42:42 +00:00
.Pp
The
.Fn pipe2
function appeared in
.Fx 10.0 .
Reference in New Issue Copy Permalink