named_pipe
|
 |
Named pipes are often referred to
as FIFOs (first in, first out). Named pipes are less
restrictive than unnamed pipes and offer these advantages.
- Named pipes have a name that
exists in the file system.
- Named pipes can be used by
unrelated processes.
- Named pipes exist until
explicitly deleted.
To create and open a named pipe,
you must perform the following tasks during the construction sequence.
- Specify the pipe's name.
- Open control flags.
- Open I/O control flags.
- Open permissions.
To create a named pipe without
opening it, use the static os_named_pipe::create()
function.
Writing to an opened named pipe
adds data to the start of the FIFO queue and reads data from the end of the FIFO
queue.
When a process finishes with a
named pipe, the process closes the pipe. When an os_named_pipe
is destroyed, the pipe is automatically closed.
A named pipe remains in the file
system until the pipe is explicitly removed. To remove a named pipe, use os_file_system::remove()
.
The primary
behaviors of a named pipe are listed below.
- A named pipe must be open
for writing before another process can open a pipe in read-only mode. If the
named pipe is closed, the reader waits until a write process opens it.
However, if non-blocking I/O is selected, the open succeeds immediately.
- A named pipe must be open
for reading before another process can open a pipe in write-only mode. If
the named pipe is closed, the writer waits until a read process opens it.
However, if non-blocking I/O is selected, the open fails immediately.
- Named pipes do not work
across a network.
- If a named pipe is read when
it is empty, and not opened by any writers, the pipe's EOF flag is set.
- If a process writes to a
named pipe with a closed read end, the process is sent a
SIGPIPE
signal.
Conversions permit
interchangeable use of os_named_pipe
and os_desc_t (UNIX descriptor).
Library
Platform<ToolKit> for
UNIX
Declaration
#include <ospace/unix/npipe.h>
class os_named_pipe
Options
Legal open control: |
O_OPEN,
O_CREAT, O_EXCL
|
| Default open control: |
O_OPEN
|
|
Legal I/O control:
|
O_ASYNC,
O_CLOSE_ON_EXEC, O_NONBLOCK, O_RDONLY, O_RDWR, O_WRONLY
|
|
Default I/O control:
|
O_RDONLY
|
|
Default mode:
|
0660
(read/write by user and group)
|
Interface
Constructor
os_named_pipe(
os_desc_t descriptor )
Constructs a reference to
a pipe with descriptor descriptor (default OS_UNDEFINED
). By default, closes named pipe on destruction.
Constructor
os_named_pipe(
const string& name ,
os_open_t open ,
os_ioctl_t control ,
os_mode_t mode )
Constructs a reference to
a pipe with name name and mode mode
(default 0660 ), using open flags open
(default O_OPEN ) and control flags control
(default O_RDONLY ). By default, closes named
pipe on destruction.
Throws: os_unix_toolkit_error
Destructor
~os_named_pipe()
Destroys the named pipe,
closing the descriptor if necessary.
<
bool
operator<( const os_named_pipe& pipe
) const
Returns true
if object's descriptor is less than pipe .
==
bool
operator==( const os_named_pipe& pipe )
const
Returns true
if object's descriptor is the same as pipe .
(os_adapter)
operator
os_adapter() const
Returns an os_adapter
.
(os_desc_t)
operator
os_desc_t() const
Returns the object's
descriptor.
auto_close
bool
auto_close() const
Returns true
if named pipe closes the descriptor on destruction.
auto_close
void
auto_close( bool flag )
If flag
is true , closes the descriptor on destruction.
clear
void
clear()
Resets named pipe's state
to good.
close
void
close()
Closes object's
descriptor and sets the descriptor to OS_UNDEFINED
. If the descriptor is already closed, does nothing.
Throws: os_unix_toolkit_error
create
/*
static */ void create( const string& filepath
, os_mode_t mode
)
Creates, but does not
open, a named pipe in the file system with name filepath
and mode mode (default 0660
).
Throws: os_unix_toolkit_error
descriptor
os_desc_t
descriptor() const
Returns the object's
descriptor.
descriptor
void
descriptor( os_desc_t descriptor )
Sets the object's
descriptor to descriptor .
eof
bool
eof() const
Returns true
if the object is at the end of the input.
event_on_eof
void
event_on_eof( bool flag )
If flag
is true , the object generates an event on EOF.
event_on_eof
bool
event_on_eof() const
Returns true
if the object generates an event on EOF.
good
bool
good() const
Returns true
if the object has not failed and is not at EOF.
io_control
os_ioctl_t
io_control() const
Returns the object's I/O
control setting.
Throws: os_unix_toolkit_error
io_control
void
io_control( os_ioctl_t control )
Sets the object's I/O
control setting to control .
Throws: os_unix_toolkit_error
is_open
bool
is_open() const
Returns true
if the object is open.
ok
bool
ok() const
Returns true
if the object has not failed.
open
void
open( const string& filepath ,
os_open_t open ,
os_ioctl_t control ,
os_mode_t mode )
Opens a reference to a
pipe with name filepath and mode mode
(default 0660 ), using open control flags open
(default O_OPEN ) and I/O control flags control
(default O_RDONLY ). By default, closes the
object on destruction.
Throws: os_unix_toolkit_error
print
void
print( ostream& stream )
const
Prints descriptor to stream
.
read
ssize_t
read( void* buffer ,
size_t bytes )
Reads up to the specified
number of bytes of data into buffer
from the pipe. Returns the number of bytes actually read, or returns -1
on error.
Throws: os_unix_toolkit_error
status
os_io_status
status() const
Returns the object's I/O
status.
Throws: os_unix_toolkit_error
write
ssize_t
write( const void* buffer ,
size_t bytes )
Writes up to the specified
number of bytes of data from buffer
to the pipe. Returns the number of bytes actually written, or returns -1
on error.
Throws: os_unix_toolkit_error
Non-Member Functions
<<
ostream&
operator<<( ostream& stream ,
const os_named_pipe& pipe )
Prints pipe
to stream .
Copyright©1994-2026 Recursion
Software LLC
All Rights Reserved - For use by licensed users only. - For use by licensed
users only.