Pipe management services.
[Native RTAI API.]


Detailed Description

Pipe management services.


Files

file  pipe.c
 This file is part of the RTAI project.

Functions

int rt_pipe_open (RT_PIPE *pipe, int minor)
 Open a pipe.
int rt_pipe_close (RT_PIPE *pipe)
 Close a pipe.
ssize_t rt_pipe_read (RT_PIPE *pipe, RT_PIPE_MSG **msgp, RTIME timeout)
 Read a message from a pipe.
ssize_t rt_pipe_write (RT_PIPE *pipe, RT_PIPE_MSG *msg, size_t size, int flags)
 Write a message to a pipe.
ssize_t rt_pipe_stream (RT_PIPE *pipe, const void *buf, size_t size)
 Stream bytes to a pipe.
ssize_t rt_pipe_flush (RT_PIPE *pipe)
 Flush the pipe.
RT_PIPE_MSG * rt_pipe_alloc (size_t size)
 Allocate a message buffer.
int rt_pipe_free (RT_PIPE_MSG *msg)
 Free a message buffer.


Function Documentation

RT_PIPE_MSG * rt_pipe_alloc size_t  size  ) 
 

Allocate a message buffer.

This service allocates a message buffer from the system heap which can be subsequently filled then passed to rt_pipe_write() for sending. The beginning of the available data area of size contiguous bytes is accessible from RT_PIPE_MSGPTR(msg).

Parameters:
size The requested size in bytes of the buffer. This value should represent the size of the payload data.
Returns:
The address of the allocated message buffer upon success, or NULL if the allocation fails.
Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

int rt_pipe_close RT_PIPE *  pipe  ) 
 

Close a pipe.

This service closes a pipe previously opened by rt_pipe_open(). Data pending for transmission to user-space are lost.

Parameters:
pipe The descriptor address of the affected pipe.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if pipe is not a pipe descriptor.

  • -EIDRM is returned if pipe is a closed pipe descriptor.

  • -ENODEV or -EBADF can be returned if pipe is scrambled.

Context: This routine can be called on behalf of a task or from the initialization code.

int rt_pipe_flush RT_PIPE *  pipe  ) 
 

Flush the pipe.

This service flushes any pending data buffered by rt_pipe_stream(). The data will be immediately sent to the user-space side of the pipe.

Parameters:
pipe The descriptor address of the pipe to flush.
Returns:
The number of bytes flushed upon success. Otherwise:
  • -EINVAL is returned if pipe is not a pipe descriptor.

  • -EIO is returned if the user-space side of the pipe is not yet open.

  • -EIDRM is returned if pipe is a closed pipe descriptor.

  • -ENODEV or -EBADF are returned if pipe is scrambled.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

int rt_pipe_free RT_PIPE_MSG *  msg  ) 
 

Free a message buffer.

This service releases a message buffer returned by rt_pipe_read() to the system heap.

Parameters:
msg The address of the message buffer to free.
Returns:
0 is returned upon success, or -EINVAL if msg is not a valid message buffer previously allocated by the rt_pipe_alloc() service.
Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

int rt_pipe_open RT_PIPE *  pipe,
int  minor
 

Open a pipe.

This service opens a bi-directional communication channel allowing data exchange between real-time tasks and regular user-space processes. Pipes natively preserve message boundaries, but can also be used in byte stream mode from kernel to user space.

Parameters:
pipe The address of a pipe descriptor RTAI will use to store the pipe-related data. This descriptor must always be valid while the pipe is active therefore it must be allocated in permanent memory.
minor The minor number of the device associated with the pipe.
Returns:
0 is returned upon success. Otherwise:
  • -ENODEV is returned if minor is not a valid minor number of for pipe pseudo-devices.

  • -EBUSY is returned if minor is already open.

Context: This routine can be called on behalf of a task or from the initialization code.

int rt_pipe_read RT_PIPE *  pipe,
RT_PIPE_MSG **  msgp,
RTIME  timeout
 

Read a message from a pipe.

This service retrieves the next message sent from the user-space side of the pipe. rt_pipe_read() always preserves message boundaries, which means that all data sent through the same write(2) operation on the user-space side will be gathered in a single message by this service.

Unless otherwise specified, the caller is blocked for a given amount of time if no data is immediately available on entry.

Parameters:
pipe The descriptor address of the pipe to read from.
msgp A pointer to a memory location which will be written upon success with the address of the received message. Once consumed, the message space should be freed using rt_pipe_free(). The application code can retrieve the actual data and size carried by the message by respectively using the RT_PIPE_MSGPTR() and RT_PIPE_MSGSIZE() macros.
timeout The number of clock ticks to wait for some message to arrive (see note). Passing RT_TIME_INFINITE causes the caller to block indefinitely until some data is eventually available. Passing RT_TIME_NONBLOCK causes the service to return immediately without waiting if no data is available on entry.
Returns:
The number of read bytes available from the received message is returned upon success; this value will be equal to RT_PIPE_MSGSIZE(*msgp). Otherwise:
  • -EINVAL is returned if pipe is not a pipe descriptor.

  • -EIDRM is returned if pipe is a closed pipe descriptor.

  • -ENODEV or -EBADF are returned if pipe is scrambled.

  • -ETIMEDOUT is returned if timeout is different from RT_TIME_NONBLOCK and no data is available within the specified amount of time.

  • -EWOULDBLOCK is returned if timeout is equal to RT_TIME_NONBLOCK and no data is immediately available on entry.

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before any data was available.

Side-effect: This routine calls the rescheduling procedure if no data is available on entry and timeout is different from RT_TIME_NONBLOCK.

Context: This routine can be called on behalf of a task. It can also be called on behalf of an interrupt context or from the initialization code provided timeout is equal to RT_TIME_NONBLOCK.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are expressed as periodic jiffies. In oneshot mode, clock ticks are expressed in nanoseconds.

int rt_pipe_stream RT_PIPE *  pipe,
const void *  buf,
size_t  size
 

Stream bytes to a pipe.

This service writes a sequence of bytes to be received by the user-space side of the pipe. Unlike rt_pipe_write(), this service does not preserve message boundaries. Instead, an internal buffer is filled on the fly with the data. The actual sending may be delayed until the internal buffer is full, or the Linux kernel is re-entered after the real-time kernel enters a quiescent state.

Data buffers sent by the rt_pipe_stream() service are always transmitted in FIFO order (i.e. RT_PIPE_NORMAL mode).

Parameters:
pipe The descriptor address of the pipe to write to.
buf The address of the first data byte to send. The data will be copied to an internal buffer before emission.
size The size in bytes of the buffer. Zero is a valid value, in which case the service returns immediately without buffering any data.
Returns:
The number of sent bytes upon success; this value will be equal to size. Otherwise:
  • -EINVAL is returned if pipe is not a pipe descriptor.

  • -EIO is returned if the user-space side of the pipe is not yet open.

  • -EIDRM is returned if pipe is a closed pipe descriptor.

  • -ENODEV or -EBADF are returned if pipe is scrambled.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

int rt_pipe_write RT_PIPE *  pipe,
RT_PIPE_MSG *  msg,
size_t  size,
int  flags
 

Write a message to a pipe.

This service writes a complete message to be received by the user-space side of the pipe. rt_pipe_write() always preserves message boundaries, which means that all data sent through a single call of this service will be gathered in a single read(2) operation on the user-space side.

Parameters:
pipe The descriptor address of the pipe to write to.
msg The address of the message to be sent. The message space must have been allocated using the rt_pipe_alloc() service. Once passed to rt_pipe_write(), the memory pointed to by msg is no more under the control of the application code and thus should not be referenced by it anymore; deallocation of this memory will be automatically handled as needed.
size The size in bytes of the message (payload data only). Zero is a valid value, in which case the service returns immediately without sending any message.
flags A set of flags affecting the operation:
  • RT_PIPE_URGENT causes the message to be prepended to the output queue, ensuring a LIFO ordering.

  • RT_PIPE_NORMAL causes the message to be appended to the output queue, ensuring a FIFO ordering.

Returns:
Upon success, this service returns size if the latter is non-zero, or the number of bytes flushed otherwise. Upon error, one of the following error codes is returned:
  • -EINVAL is returned if pipe is not a pipe descriptor.

  • -EIO is returned if the user-space side of the pipe is not yet open.

  • -EIDRM is returned if pipe is a closed pipe descriptor.

  • -ENODEV or -EBADF are returned if pipe is scrambled.

Side-effect: rt_pipe_write() causes any data buffered by rt_pipe_stream() to be flushed prior to sending the message. For this reason, rt_pipe_write() can return a non-zero byte count to the caller if some pending data has been flushed, even if size was zero on entry.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.


Generated on Mon Aug 30 13:58:39 2004 for RTAI API by doxygen 1.3.8