VxWorks Reference Manual : Libraries
zbufSockLib - zbuf socket interface library
zbufSockLibInit( ) - initialize the zbuf socket interface library
zbufSockSend( ) - send zbuf data to a TCP socket
zbufSockSendto( ) - send a zbuf message to a UDP socket
zbufSockBufSend( ) - create a zbuf from user data and send it to a TCP socket
zbufSockBufSendto( ) - create a zbuf from a user message and send it to a UDP socket
zbufSockRecv( ) - receive data in a zbuf from a TCP socket
zbufSockRecvfrom( ) - receive a message in a zbuf from a UDP socket
This library contains routines that communicate over BSD sockets using the zbuf interface described in the zbufLib manual page. These zbuf socket calls communicate over BSD sockets in a similar manner to the socket routines in sockLib, but they avoid copying data unnecessarily between application buffers and network buffers.
zbufSockLib, zbufLib, sockLib, VxWorks Programmer's Guide: Network
zbufSockLibInit( ) - initialize the zbuf socket interface library
STATUS zbufSockLibInit (void)
This routine initializes the zbuf socket interface library. It must be called before any zbuf socket routines are used. It is called automatically when the configuration macro INCLUDE_ZBUF_SOCK is defined.
OK, or ERROR if the zbuf socket interface could not be initialized.
zbufSockSend( ) - send zbuf data to a TCP socket
int zbufSockSend ( int s, /* socket to send to */ ZBUF_ID zbufId, /* zbuf to transmit */ int zbufLen, /* length of entire zbuf */ int flags /* flags to underlying protocols */ )
This routine transmits all of the data in zbufId to a previously established connection-based (stream) socket.
The zbufLen parameter is used only for determining the amount of space needed from the socket write buffer. zbufLen has no effect on how many bytes are sent; the entire zbuf is always transmitted. If the length of zbufId is not known, the caller must first determine it by calling zbufLength( ).
This routine transfers ownership of the zbuf from the user application to the VxWorks network stack. The zbuf ID zbufId is deleted by this routine, and should not be used after the routine is called, even if an ERROR status is returned. (Exceptions: when the routine fails because the zbuf socket interface library was not initialized or an invalid zbuf ID was passed in, in which case there is no zbuf to delete. Moreover, if the call fails during a non-blocking I/O socket write with an errno of EWOULDBLOCK, then zbufId is not deleted; thus the caller may send it again at a later time.)
You may OR the following values into the flags parameter with this operation:
- MSG_OOB (0x1)
- Out-of-band data.
- MSG_DONTROUTE (0x4)
- Send without using routing tables.
The number of bytes sent, or ERROR if the call fails.
zbufSockLib, zbufLength( ), zbufSockBufSend( ), send( )
zbufSockSendto( ) - send a zbuf message to a UDP socket
int zbufSockSendto ( int s, /* socket to send to */ ZBUF_ID zbufId, /* zbuf to transmit */ int zbufLen, /* length of entire zbuf */ int flags, /* flags to underlying protocols */ struct sockaddr * to, /* recipient's address */ int tolen /* length of to socket addr */ )
This routine sends the entire message in zbufId to the datagram socket named by to. The socket s is the sending socket.
The zbufLen parameter is used only for determining the amount of space needed from the socket write buffer. zbufLen has no effect on how many bytes are sent; the entire zbuf is always transmitted. If the length of zbufId is not known, the caller must first determine it by calling zbufLength( ).
This routine transfers ownership of the zbuf from the user application to the VxWorks network stack. The zbuf ID zbufId is deleted by this routine, and should not be used after the routine is called, even if an ERROR status is returned. (Exceptions: when the routine fails because the zbuf socket interface library was not initialized or an invalid zbuf ID was passed in, in which case there is no zbuf to delete. Moreover, if the call fails during a non-blocking I/O socket write with an errno of EWOULDBLOCK, then zbufId is not deleted; thus the caller may send it again at a later time.)
You may OR the following values into the flags parameter with this operation:
- MSG_OOB (0x1)
- Out-of-band data.
- MSG_DONTROUTE (0x4)
- Send without using routing tables.
The number of bytes sent, or ERROR if the call fails.
zbufSockLib, zbufLength( ), zbufSockBufSendto( ), sendto( )
zbufSockBufSend( ) - create a zbuf from user data and send it to a TCP socket
int zbufSockBufSend ( int s, /* socket to send to */ char * buf, /* pointer to data buffer */ int bufLen, /* number of bytes to send */ VOIDFUNCPTR freeRtn, /* free routine callback */ int freeArg, /* argument to free routine */ int flags /* flags to underlying protocols */ )
This routine creates a zbuf from the user buffer buf, and transmits it to a previously established connection-based (stream) socket.
The user-provided free routine callback at freeRtn is called when buf is no longer in use by the TCP/IP network stack. Applications can exploit this callback to receive notification that buf is free. If freeRtn is NULL, the routine functions normally, except that the application has no way of being notified when buf is released by the network stack. The free routine runs in the context of the task that last references the buffer. This is typically either the context of tNetTask, or the context of the caller's task. Declare freeRtn as follows (using whatever name is convenient):
void freeCallback ( caddr_t buf, /* pointer to user buffer */ int freeArg /* user-provided argument to free routine */ )You may OR the following values into the flags parameter with this operation:
- MSG_OOB (0x1)
- Out-of-band data.
- MSG_DONTROUTE (0x4)
- Send without using routing tables.
The number of bytes sent, or ERROR if the call fails.
zbufSockLib, zbufSockSend( ), send( )
zbufSockBufSendto( ) - create a zbuf from a user message and send it to a UDP socket
int zbufSockBufSendto ( int s, /* socket to send to */ char * buf, /* pointer to data buffer */ int bufLen, /* number of bytes to send */ VOIDFUNCPTR freeRtn, /* free routine callback */ int freeArg, /* argument to free routine */ int flags, /* flags to underlying protocols */ struct sockaddr * to, /* recipient's address */ int tolen /* length of to socket addr */ )
This routine creates a zbuf from the user buffer buf, and sends it to the datagram socket named by to. The socket s is the sending socket.
The user-provided free routine callback at freeRtn is called when buf is no longer in use by the UDP/IP network stack. Applications can exploit this callback to receive notification that buf is free. If freeRtn is NULL, the routine functions normally, except that the application has no way of being notified when buf is released by the network stack. The free routine runs in the context of the task that last references the buffer. This is typically either tNetTask context, or the caller's task context. Declare freeRtn as follows (using whatever name is convenient):
void freeCallback ( caddr_t buf, /* pointer to user buffer */ int freeArg /* user-provided argument to free routine */ )You may OR the following values into the flags parameter with this operation:
- MSG_OOB (0x1)
- Out-of-band data.
- MSG_DONTROUTE (0x4)
- Send without using routing tables.
The number of bytes sent, or ERROR if the call fails.
zbufSockLib, zbufSockSendto( ), sendto( )
zbufSockRecv( ) - receive data in a zbuf from a TCP socket
ZBUF_ID zbufSockRecv ( int s, /* socket to receive data from */ int flags, /* flags to underlying protocols */ int * pLen /* number of bytes requested/returned */ )
This routine receives data from a connection-based (stream) socket, and returns the data to the user in a newly created zbuf.
The pLen parameter indicates the number of bytes requested by the caller. If the operation is successful, the number of bytes received is copied to pLen.
You may OR the following values into the flags parameter with this operation:
- MSG_OOB (0x1)
- Out-of-band data.
- MSG_PEEK (0x2)
- Return data without removing it from socket.
Once the user application is finished with the zbuf, zbufDelete( ) should be called to return the zbuf memory buffer to the VxWorks network stack.
The zbuf ID of a newly created zbuf containing the received data, or NULL if the operation fails.
zbufSockLib, recv( )
zbufSockRecvfrom( ) - receive a message in a zbuf from a UDP socket
ZBUF_ID zbufSockRecvfrom ( int s, /* socket to receive from */ int flags, /* flags to underlying protocols */ int * pLen, /* number of bytes requested/returned */ struct sockaddr * from, /* where to copy sender's addr */ int * pFromLen /* value/result length of from */ )
This routine receives a message from a datagram socket, and returns the message to the user in a newly created zbuf.
The message is received regardless of whether the socket is connected. If from is nonzero, the address of the sender's socket is copied to it. Initialize the value-result parameter pFromLen to the size of the from buffer. On return, pFromLen contains the actual size of the address stored in from.
The pLen parameter indicates the number of bytes requested by the caller. If the operation is successful, the number of bytes received is copied to pLen.
You may OR the following values into the flags parameter with this operation:
- MSG_OOB (0x1)
- Out-of-band data.
- MSG_PEEK (0x2)
- Return data without removing it from socket.
Once the user application is finished with the zbuf, zbufDelete( ) should be called to return the zbuf memory buffer to the VxWorks network stack.
The zbuf ID of a newly created zbuf containing the received message, or NULL if the operation fails.