VxWorks Reference Manual : Libraries
zbufLib - zbuf interface library
zbufCreate( ) - create an empty zbuf
zbufDelete( ) - delete a zbuf
zbufInsert( ) - insert a zbuf into another zbuf
zbufInsertBuf( ) - create a zbuf segment from a buffer and insert into a zbuf
zbufInsertCopy( ) - copy buffer data into a zbuf
zbufExtractCopy( ) - copy data from a zbuf to a buffer
zbufCut( ) - delete bytes from a zbuf
zbufSplit( ) - split a zbuf into two separate zbufs
zbufDup( ) - duplicate a zbuf
zbufLength( ) - determine the length in bytes of a zbuf
zbufSegFind( ) - find the zbuf segment containing a specified byte location
zbufSegNext( ) - get the next segment in a zbuf
zbufSegPrev( ) - get the previous segment in a zbuf
zbufSegData( ) - determine the location of data in a zbuf segment
zbufSegLength( ) - determine the length of a zbuf segment
This library contains routines to create, build, manipulate, and delete zbufs. Zbufs, also known as "zero copy buffers," are a data abstraction designed to allow software modules to share buffers without unnecessarily copying data.
To support the data abstraction, the subroutines in this library hide the implementation details of zbufs. This also maintains the library's independence from any particular implementation mechanism, permitting the zbuf interface to be used with other buffering schemes eventually.
Zbufs have three essential properties. First, a zbuf holds a sequence of bytes. Second, these bytes are organized into one or more segments of contiguous data, although the successive segments themselves are not usually contiguous. Third, the data within a segment may be shared with other segments; that is, the data may be in use by more than one zbuf at a time.
The following data types are used in managing zbufs:
- ZBUF_ID
- An arbitrary (but unique) integer that identifies a particular zbuf.
- ZBUF_SEG
- An arbitrary (but unique within a single zbuf) integer that identifies a segment within a zbuf.
The bytes in a zbuf are addressed by the combination zbufSeg, offset. The offset may be positive or negative, and is simply the number of bytes from the beginning of the segment zbufSeg.
A zbufSeg can be specified as NULL, to identify the segment at the beginning of a zbuf. If zbufseg is NULL, offset is the absolute offset to any byte in the zbuf. However, it is more efficient to identify a zbuf byte location relative to the zbufSeg that contains it; see zbufSegFind( ) to convert any zbufSeg, offset pair to the most efficient equivalent.
Negative offset values always refer to bytes before the corresponding zbufSeg, and are usually not the most efficient address formulation in themselves (though using them may save your program other work in some cases).
The following special offset values, defined as constants, allow you to specify the very beginning or the very end of an entire zbuf, regardless of the zbufSeg value:
- ZBUF_BEGIN
- The beginning of the entire zbuf.
- ZBUF_END
- The end of the entire zbuf (useful for appending to a zbuf; see below).
An offset is not valid if it points outside the zbuf. Thus, to address data currently within an N-byte zbuf, the valid offsets relative to the first segment are 0 through N-1.
Insertion routines are a special case: they obey the usual convention, but they use offset to specify where the new data begins after the insertion is complete. With regard to the original zbuf data, therefore, data is always inserted just before the byte location addressed by the offset value. The value of this convention is that it permits inserting (or concatenating) data either before or after the existing data. To insert before all the data currently in a zbuf segment, use 0 as offset. To insert after all the data in an N-byte segment, use N as offset. An offset of N-1 inserts the data just before the last byte in an N-byte segment.
An offset of 0 is always a valid insertion point; for an empty zbuf, 0 is the only valid offset (and NULL the only valid zbufSeg).
The routines in this library avoid copying segment data whenever possible. Thus, by passing and manipulating ZBUF_IDs rather than copying data, multiple programs can communicate with greater efficiency. However, each program must be aware of data sharing: changes to the data in a zbuf segment are visible to all zbuf segments that reference the data.
To alter your own program's view of zbuf data without affecting other programs, first use zbufDup( ) to make a new zbuf; then you can use an insertion or deletion routine, such as zbufInsertBuf( ), to add a segment that only your program sees (until you pass a zbuf containing it to another program). It is safest to do all direct data manipulation in a private buffer, before enrolling it in a zbuf: in principle, you should regard all zbuf segment data as shared.
Once a data buffer is enrolled in a zbuf segment, the zbuf library is responsible for noticing when the buffer is no longer in use by any program, and freeing it. To support this, zbufInsertBuf( ) requires that you specify a callback to a free routine each time you build a zbuf segment around an existing buffer. You can use this callback to notify your application when a data buffer is no longer in use.
zbufLib, zbufSockLib, VxWorks Programmer's Guide: Network
zbufCreate( ) - create an empty zbuf
ZBUF_ID zbufCreate (void)
This routine creates a zbuf, which remains empty (that is, it contains no data) until segments are added by the zbuf insertion routines. Operations performed on zbufs require a zbuf ID, which is returned by this routine.
A zbuf ID, or NULL if a zbuf cannot be created.
zbufLib, zbufDelete( )
zbufDelete( ) - delete a zbuf
STATUS zbufDelete ( ZBUF_ID zbufId /* zbuf to be deleted */ )
This routine deletes any zbuf segments in the specified zbuf, then deletes the zbuf ID itself. zbufId must not be used after this routine executes successfully.
For any data buffers that were not in use by any other zbuf, zbufDelete( ) calls the associated free routine (callback).
OK, or ERROR if the zbuf cannot be deleted.
zbufLib, zbufCreate( ), zbufInsertBuf( )
zbufInsert( ) - insert a zbuf into another zbuf
ZBUF_SEG zbufInsert ( ZBUF_ID zbufId1, /* zbuf to insert zbufId2 into */ ZBUF_SEG zbufSeg, /* zbuf segment base for offset */ int offset, /* relative byte offset */ ZBUF_ID zbufId2 /* zbuf to insert into zbufId1 */ )
This routine inserts all zbufId2 zbuf segments into zbufId1 at the specified byte location.
The location of insertion is specified by zbufSeg and offset. See the zbufLib manual page for more information on specifying a byte location within a zbuf. In particular, insertion within a zbuf occurs before the byte location specified by zbufSeg and offset. Additionally, zbufSeg and offset must be NULL and 0, respectively, when inserting into an empty zbuf.
After all the zbufId2 segments are inserted into zbufId1, the zbuf ID zbufId2 is deleted. zbufId2 must not be used after this routine executes successfully.
The zbuf segment ID for the first inserted segment, or NULL if the operation fails.
zbufInsertBuf( ) - create a zbuf segment from a buffer and insert into a zbuf
ZBUF_SEG zbufInsertBuf ( ZBUF_ID zbufId, /* zbuf in which buffer is inserted */ ZBUF_SEG zbufSeg, /* zbuf segment base for offset */ int offset, /* relative byte offset */ caddr_t buf, /* application buffer for segment */ int len, /* number of bytes to insert */ VOIDFUNCPTR freeRtn, /* free-routine callback */ int freeArg /* argument to free routine */ )
This routine creates a zbuf segment from the application buffer buf and inserts it at the specified byte location in zbufId.
The location of insertion is specified by zbufSeg and offset. See the zbufLib manual page for more information on specifying a byte location within a zbuf. In particular, insertion within a zbuf occurs before the byte location specified by zbufSeg and offset. Additionally, zbufSeg and offset must be NULL and 0, respectively, when inserting into an empty zbuf.
The parameter freeRtn specifies a free-routine callback that runs when the data buffer buf is no longer referenced by any zbuf segments. If freeRtn is NULL, the zbuf functions normally, except that the application is not notified when no more zbufs segments reference buf. The free-routine callback runs from the context of the task that last deletes reference to the buffer. Declare the freeRtn callback as follows (using whatever routine name suits your application):
void freeCallback ( caddr_t buf, /* pointer to application buffer */ int freeArg /* argument to free routine */ )
The zbuf segment ID of the inserted segment, or NULL if the operation fails.
zbufInsertCopy( ) - copy buffer data into a zbuf
ZBUF_SEG zbufInsertCopy ( ZBUF_ID zbufId, /* zbuf into which data is copied */ ZBUF_SEG zbufSeg, /* zbuf segment base for offset */ int offset, /* relative byte offset */ caddr_t buf, /* buffer from which data is copied */ int len /* number of bytes to copy */ )
This routine copies len bytes of data from the application buffer buf and inserts it at the specified byte location in zbufId. The application buffer is in no way tied to the zbuf after this operation; a separate copy of the data is made.
The location of insertion is specified by zbufSeg and offset. See the zbufLib manual page for more information on specifying a byte location within a zbuf. In particular, insertion within a zbuf occurs before the byte location specified by zbufSeg and offset. Additionally, zbufSeg and offset must be NULL and 0, respectively, when inserting into an empty zbuf.
The zbuf segment ID of the first inserted segment, or NULL if the operation fails.
zbufExtractCopy( ) - copy data from a zbuf to a buffer
int zbufExtractCopy ( ZBUF_ID zbufId, /* zbuf from which data is copied */ ZBUF_SEG zbufSeg, /* zbuf segment base for offset */ int offset, /* relative byte offset */ caddr_t buf, /* buffer into which data is copied */ int len /* number of bytes to copy */ )
This routine copies len bytes of data from zbufId to the application buffer buf.
The starting location of the copy is specified by zbufSeg and offset. See the zbufLib manual page for more information on specifying a byte location within a zbuf. In particular, the first byte copied is the exact byte specified by zbufSeg and offset.
The number of bytes to copy is given by len. If this parameter is negative, or is larger than the number of bytes in the zbuf after the specified byte location, the rest of the zbuf is copied. The bytes copied may span more than one segment.
The number of bytes copied from the zbuf to the buffer, or ERROR if the operation fails.
zbufCut( ) - delete bytes from a zbuf
ZBUF_SEG zbufCut ( ZBUF_ID zbufId, /* zbuf from which bytes are cut */ ZBUF_SEG zbufSeg, /* zbuf segment base for offset */ int offset, /* relative byte offset */ int len /* number of bytes to cut */ )
This routine deletes len bytes from zbufId starting at the specified byte location.
The starting location of deletion is specified by zbufSeg and offset. See the zbufLib manual page for more information on specifying a byte location within a zbuf. In particular, the first byte deleted is the exact byte specified by zbufSeg and offset.
The number of bytes to delete is given by len. If this parameter is negative, or is larger than the number of bytes in the zbuf after the specified byte location, the rest of the zbuf is deleted. The bytes deleted may span more than one segment.
If all the bytes in any one segment are deleted, then the segment is deleted, and the data buffer that it referenced will be freed if no other zbuf segments reference it. No segment may survive with zero bytes referenced.
Deleting bytes out of the middle of a segment splits the segment into two. The first segment contains the portion of the data buffer before the deleted bytes, while the other segment contains the end portion that remains after deleting len bytes.
This routine returns the zbuf segment ID of the segment just after the deleted bytes. In the case where bytes are cut off the end of a zbuf, a value of ZBUF_NONE is returned.
The zbuf segment ID of the segment following the deleted bytes, or NULL if the operation fails.
zbufSplit( ) - split a zbuf into two separate zbufs
ZBUF_ID zbufSplit ( ZBUF_ID zbufId, /* zbuf to split into two */ ZBUF_SEG zbufSeg, /* zbuf segment base for offset */ int offset /* relative byte offset */ )
This routine splits zbufId into two separate zbufs at the specified byte location. The first portion remains in zbufId, while the end portion is returned in a newly created zbuf.
The location of the split is specified by zbufSeg and offset. See the zbufLib manual page for more information on specifying a byte location within a zbuf. In particular, after the split operation, the first byte of the returned zbuf is the exact byte specified by zbufSeg and offset.
The zbuf ID of a newly created zbuf containing the end portion of zbufId, or NULL if the operation fails.
zbufDup( ) - duplicate a zbuf
ZBUF_ID zbufDup ( ZBUF_ID zbufId, /* zbuf to duplicate */ ZBUF_SEG zbufSeg, /* zbuf segment base for offset */ int offset, /* relative byte offset */ int len /* number of bytes to duplicate */ )
This routine duplicates len bytes of zbufId starting at the specified byte location, and returns the zbuf ID of the newly created duplicate zbuf.
The starting location of duplication is specified by zbufSeg and offset. See the zbufLib manual page for more information on specifying a byte location within a zbuf. In particular, the first byte duplicated is the exact byte specified by zbufSeg and offset.
The number of bytes to duplicate is given by len. If this parameter is negative, or is larger than the number of bytes in the zbuf after the specified byte location, the rest of the zbuf is duplicated.
Duplication of zbuf data does not usually involve copying of the data. Instead, the zbuf segment pointer information is duplicated, while the data is not, which means that the data is shared among all zbuf segments that reference the data. See the zbufLib manual page for more information on copying and sharing zbuf data.
The zbuf ID of a newly created duplicate zbuf, or NULL if the operation fails.
zbufLength( ) - determine the length in bytes of a zbuf
int zbufLength ( ZBUF_ID zbufId /* zbuf to determine length */ )
This routine returns the number of bytes in the zbuf zbufId.
The number of bytes in the zbuf, or ERROR if the operation fails.
zbufSegFind( ) - find the zbuf segment containing a specified byte location
ZBUF_SEG zbufSegFind ( ZBUF_ID zbufId, /* zbuf to examine */ ZBUF_SEG zbufSeg, /* zbuf segment base for pOffset */ int * pOffset /* relative byte offset */ )
This routine translates an address within a zbuf to its most local formulation. zbufSegFind( ) locates the zbuf segment in zbufId that contains the byte location specified by zbufSeg and *pOffset, then returns that zbuf segment, and writes in *pOffset the new offset relative to the returned segment.
If the zbufSeg, *pOffset pair specify a byte location past the end of the zbuf, or before the first byte in the zbuf, zbufSegFind( ) returns NULL.
See the zbufLib manual page for a full discussion of addressing zbufs by segment and offset.
The zbuf segment ID of the segment containing the specified byte, or NULL if the operation fails.
zbufSegNext( ) - get the next segment in a zbuf
ZBUF_SEG zbufSegNext ( ZBUF_ID zbufId, /* zbuf to examine */ ZBUF_SEG zbufSeg /* segment to get next segment */ )
This routine finds the zbuf segment in zbufId that is just after the zbuf segment zbufSeg. If zbufSeg is NULL, the segment after the first segment in zbufId is returned. If zbufSeg is the last segment in zbufId, NULL is returned.
The zbuf segment ID of the segment after zbufSeg, or NULL if the operation fails.
zbufSegPrev( ) - get the previous segment in a zbuf
ZBUF_SEG zbufSegPrev ( ZBUF_ID zbufId, /* zbuf to examine */ ZBUF_SEG zbufSeg /* segment to get previous segment */ )
This routine finds the zbuf segment in zbufId that is just previous to the zbuf segment zbufSeg. If zbufSeg is NULL, or is the first segment in zbufId, NULL is returned.
The zbuf segment ID of the segment previous to zbufSeg, or NULL if the operation fails.
zbufSegData( ) - determine the location of data in a zbuf segment
caddr_t zbufSegData ( ZBUF_ID zbufId, /* zbuf to examine */ ZBUF_SEG zbufSeg /* segment to get pointer to data */ )
This routine returns the location of the first byte of data in the zbuf segment zbufSeg. If zbufSeg is NULL, the location of data in the first segment in zbufId is returned.
A pointer to the first byte of data in the specified zbuf segment, or NULL if the operation fails.
zbufSegLength( ) - determine the length of a zbuf segment
int zbufSegLength ( ZBUF_ID zbufId, /* zbuf to examine */ ZBUF_SEG zbufSeg /* segment to determine length of */ )
This routine returns the number of bytes in the zbuf segment zbufSeg. If zbufSeg is NULL, the length of the first segment in zbufId is returned.
The number of bytes in the specified zbuf segment, or ERROR if the operation fails.