ipc.h File Reference

Utility functions for working with the general IPC mechanism in JUNOS. More...


Data Structures

struct  ipc_pipe_direction_
struct  ipc_pipe_

Defines

#define FALSE   0
#define TRUE   1
#define IPC_PIPE_MTU_BYTES   1500

Typedefs

typedef ipc_pipe_ ipc_pipe_t
typedef ipc_pipe_direction_ ipc_pipe_direction_t

Functions

ipc_pipe_t * ipc_pipe_create (ipc_length_t mtu)
 Allocates and initializes an ipc_pipe_t structure.
void ipc_pipe_destroy (ipc_pipe_t *pipe_)
 Deletes an ipc_pipe_t structure.
int ipc_pipe_attach_socket (ipc_pipe_t *pipe_, int socket_)
 Attaches a socket to an ipc_pipe_t structure.
void ipc_pipe_detach_socket (ipc_pipe_t *pipe_, int socket_)
 Detaches a socket from the ipc_pipe_t structure.
int ipc_pipe_write (ipc_pipe_t *pipe_, struct sockaddr *addr)
 Writes all of the IPC messages in the write buffer to the socket attached to the pipe.
int ipc_pipe_read (ipc_pipe_t *pipe_)
 Reads the next IPC message from the socket attached to the pipe.
void ipc_pipe_read_clean (ipc_pipe_t *pipe_)
 Resets the pipe's read buffer.
void ipc_pipe_write_clean (ipc_pipe_t *pipe_)
 Resets the pipe's write buffer.
ipc_msg_t * ipc_msg_read (ipc_pipe_t *pipe_)
 Reads an ipc_msg_t message from the pipe's read buffer.
int ipc_msg_write_error (ipc_pipe_t *pipe_, ipc_msg_t *msg, ipc_error_t error)
 Writes an error message into the pipe.
int ipc_msg_write (ipc_pipe_t *pipe_, ipc_msg_t *msg, void *data)
 Writes an @ ipc_msg_t message into the write buffer.
int ipc_msg_writev (ipc_pipe_t *pipe_, ipc_msg_t *msg, struct iovec *iov, u_int iovcnt)
 Writes an ipc_msg_t message into the write buffer.
void ipc_msg_copy (ipc_msg_t *src, ipc_msg_t *dst, ipc_length_t length)
 Copies an ipc_msg_t message from src to dst.


Detailed Description

Utility functions for working with the general IPC mechanism in JUNOS.

These functions are used to pass messages of type ipc_msg_t through a socket-based IPC mechanism.

Applications can write multiple messages into an ipc_pipe, thereby sending messages to an IPC peer through a socket.

Applications are responsible for creating the socket and then attaching it to the ipc_pipe_t object.

The supported socket types are SOCK_DGRAM, SOCK_STREAM, and SOCK_SEQPACKET.


Function Documentation

void ipc_msg_copy ipc_msg_t *  src,
ipc_msg_t *  dst,
ipc_length_t  length
 

Copies an ipc_msg_t message from src to dst.

Parameters:
[in] src A pointer to source ipc_msg_t message.
[in] dst A pointer to destination ipc_msg_t message.
[in] length The length of data in the source message.

ipc_msg_t* ipc_msg_read ipc_pipe_t *  pipe_  ) 
 

Reads an ipc_msg_t message from the pipe's read buffer.

This function returns a pointer to the next ipc_msg_t message in the pipe's read buffer. A single IPC message may contain several ipc_msg_t messages.

This function is called after calling ipc_pipe_read(), to pull individual ipc_msg_t messages from the pipe.

Note:
Call ipc_pipe_read_clean() after all messages have been read from the pipe.
Parameters:
[in] pipe_ A pointer to the ipc_pipe_t structure.
Returns:
A pointer to the next ipc_msg_t message in the read buffer, or NULL if there are no more ipc_msg_t messages in read buffer.
See also:
ipc_pipe_read_clean()

int ipc_msg_write ipc_pipe_t *  pipe_,
ipc_msg_t *  msg,
void *  data
 

Writes an @ ipc_msg_t message into the write buffer.

Call this function repeatedly to fill the pipe with ipc_msg_t messages.

After writing all individual messages, call the function ipc_pipe_write() to send all messages to the peer at once.

Parameters:
[in] pipe_ A pointer to the ipc_pipe_t structure.
[in] msg A pointer to the ipc_msg_t structure.
[in] data A pointer to the data buffer. The length of data is in the length field of the ipc_msg_t structure pointed to by msg.
Returns:
0 on success; -1 on failure On failure, errno will contain the error code.

int ipc_msg_write_error ipc_pipe_t *  pipe_,
ipc_msg_t *  msg,
ipc_error_t  error
 

Writes an error message into the pipe.

This function writes an error message into the pipe when processing the ipc_msg_t message from the peer, if IPC_MSG_NOTIFY_ERROR is set in the message's opcode.

The error message will contain the original ipc_msg_t message, with the error code set in message's error field.

Parameters:
[in] pipe_ A pointer to the ipc_pipe_t structure.
[in] msg A pointer to the ipc_msg_t message which caused the error.
[in] error The error code.
Returns:
0 on success; -1 on failure. On failure, errno will contain the error code.

int ipc_msg_writev ipc_pipe_t *  pipe_,
ipc_msg_t *  msg,
struct iovec *  iov,
u_int  iovcnt
 

Writes an ipc_msg_t message into the write buffer.

This is an alternate form of ipc_msg_write(); in this function, the data buffers are scattered in an iovec array.

Parameters:
[in] pipe_ A pointer to the ipc_pipe_t structure.
[in] msg A pointer to the ipc_msg_t structure.
[in] iov A pointer to the iovec array.
[in] iovcnt The number of elements in the iovec array
Returns:
0 on success; -1 on failure. On failure, errno will contain the error code.
See also:
ipc_msg_write()

int ipc_pipe_attach_socket ipc_pipe_t *  pipe_,
int  socket_
 

Attaches a socket to an ipc_pipe_t structure.

The socket will be used to send and receive IPC messages.

Parameters:
[in] pipe_ A pointer to the ipc_pipe_t structure.
[in] socket_ The socket descriptor to attach to the ipc_pipe_t structure. The following socket types are supported:
          SOCK_DGRAM
          SOCK_STREAM
          SOCK_SEQPACKET
   
Returns:
0 on success; -1 on failure. If the socket is not one of the supported types, the function will fail, setting errno to EINVAL.

ipc_pipe_t* ipc_pipe_create ipc_length_t  mtu  ) 
 

Allocates and initializes an ipc_pipe_t structure.

Parameters:
[in] mtu Maximum length of the pipe's read and write buffers. Passing a size of 0 will result in read/write buffers of size IPC_PIPE_MTU_BYTES.
Returns:
A pointer to the created ipc_pipe_t structure, or NULL on failure. On failure, errno will be set to ENOMEM on memory allocation failure.

void ipc_pipe_destroy ipc_pipe_t *  pipe_  ) 
 

Deletes an ipc_pipe_t structure.

Parameters:
[in] pipe_ A pointer to the ipc_pipe_t structure to destroy.

void ipc_pipe_detach_socket ipc_pipe_t *  pipe_,
int  socket_
 

Detaches a socket from the ipc_pipe_t structure.

This function does not close the socket attached to the pipe, and no data are flushed from the pipe before detaching the socket.

Parameters:
[in] pipe_ A pointer to the ipc_pipe_t structure.
[in] socket_ Socket descriptor to detach. The function has no effect if the socket_ parameter does not match the socket previously attached to the pipe.

int ipc_pipe_read ipc_pipe_t *  pipe_  ) 
 

Reads the next IPC message from the socket attached to the pipe.

The ipc_pipe_read() function blocks until the next IPC messsage is read from the socket.

After the message is read, it is saved to the pipe's read buffer.

This function will block until a message becomes available, unless the socket is in nonblocking mode. If the socket is in nonblocking mode, errno will hold the value EAGAIN.

If the socket is in blocking mode and this function reads fewer bytes than indicated in the message length, errno will hold a value of EAGAIN. In this case, you may call this function repeatedly until a value of zero is returned.

Parameters:
[in] pipe_ A pointer to the ipc_pipe_t structure.
Returns:
0 on success; -1 on failure. On failure, errno will contain the error code. A return code of -1, with errno set to zero, indicates that ipc_pipe_read() received zero bytes during the read operation. This could indicate the remote peer has performed an orderly shutdown of the socket while ipc_pipe_read() was blocking.

void ipc_pipe_read_clean ipc_pipe_t *  pipe_  ) 
 

Resets the pipe's read buffer.

After you have completed reading a sequence of messages with ipc_msg_read(), you must call this function to reset the pipe's read buffer.

Parameters:
[in] pipe_ A pointer to an ipc_pipe_t structure.
See also:
ipc_pipe_msg_read()

int ipc_pipe_write ipc_pipe_t *  pipe_,
struct sockaddr *  addr
 

Writes all of the IPC messages in the write buffer to the socket attached to the pipe.

Note:
Call ipc_pipe_write_clean() after writing all messages to the pipe.
Parameters:
[in] pipe_ A pointer to an ipc_pipe_t structure.
[in] addr The destination socket address. Pass NULL in this parameter to cause the function to use the addr field of the pipe_ parameter.
Returns:
0 on success; -1 on failure. On failure, errno will contain the error code, and an error will be written to the system log.
See also:
ipc_pipe_write_clean()

void ipc_pipe_write_clean ipc_pipe_t *  pipe_  ) 
 

Resets the pipe's write buffer.

Note that no messages are written to the socket. This function only sets the pipe's length and offset fields to zero.

You must call this function after writing messages to the pipe with ipc_pipe_write().

Parameters:
[in] pipe_ A pointer to the ipc_pipe_t structure.
See also:
ipc_pipe_write()


2007-2009 Juniper Networks, Inc. All rights reserved. The information contained herein is confidential information of Juniper Networks, Inc., and may not be used, disclosed, distributed, modified, or copied without the prior written consent of Juniper Networks, Inc. in an express license. This information is subject to change by Juniper Networks, Inc. Juniper Networks, the Juniper Networks logo, and JUNOS are registered trademarks of Juniper Networks, Inc. in the United States and other countries. All other trademarks, service marks, registered trademarks, or registered service marks are the property of their respective owners.
Generated on Sun May 30 20:24:22 2010 for libjipc by Doxygen 1.4.5