gtpc2mjc | C/C++ Language Support User's Guide |
This type of function is specified as part of the file system device driver
interface and is called by TPF file system C functions that require a physical
append to a file device to append output data to an open special file.
Format
typedef long TPF_FSDD_APPEND(void *buffer, long data_size, int noblock,
const TPF_FSDD_FILEDATA *filedata);
- buffer
- The address of the data buffer from which the output data will be
appended. The range of addresses buffer through
buffer + data_size - 1 is not verified to be
addressable.
- data_size
- The size of the output data to be appended to file.
data_size ranges from 1 to
2 147 483 647 (2**31 - 1)
inclusive.
- noblock
- Nonblocking append request indicator.
For files that support nonblocking writes and cannot accept data
immediately, you can write code to do the following:
- If noblock equals zero, the function blocks the process until
the data can be appended.
- If noblock does not equal zero, the function does not block the
process. If some data can be appended without blocking the process, the
function appends what it can and returns the number of bytes appended.
Otherwise, it sets errno to EAGAIN and returns the value
-1.
- filedata
- The address of the file data object returned by the
TPF_FSDD_OPEN-type device driver function for the special file
being appended.
Normal Return
The number of bytes appended from buffer, from 1 to
data_size inclusive.
- Note:
- When zero bytes of data are requested to be appended, TPF file system C
functions return zero without calling this device driver function.
Error Return
-1 means an error during the append operation. The device
driver should also set errno to indicate the type of error.
Programming Considerations
- The TPF_FSDD_APPEND-type device driver function is only called
for open instances of files that were successfully opened by the corresponding
FSDD_OPEN-type device driver function. More than one
instance of a single file can be open at the same time.
- The TPF_FSDD_APPEND-type device driver function is never called
for instances of files that are open with read-only access.
- If the capacity of the file is exceeded and no data is appended, the
device driver should return -1 and set errno to
EFBIG; the device driver should never return 0.
- A return value greater than 0 but less than data_size indicates
one of the following conditions:
- The capacity of the file was too small to contain all the requested
data.
- Less than data_size bytes of data could be appended to file
without blocking for a nonblocking append request.
- Only part of the requested data was successfully appended to file before
an error prevented the remaining data from being appended. Here, the
error is reported if it persists to the next append, preventing any data from
being appended to the special file, at which time this device driver function
returns -1 and sets errno.
- If no data can be immediately appended to satisfy a nonblocking append
request, the device driver should set errno to EAGAIN
and return -1.
- If there is an error in the source of data or the device driver that
prevents a write request from writing any valid data, the device driver should
set errno to indicate the type of error and return -1.
Examples
The following example is the append device driver interface function for
the null file (/dev/null).
#include <c$spif.h> /* Device driver interface */
/**********************************************************************/
/* The null_append() function appends to a null file. It always */
/* succeeds. */
/**********************************************************************/
long null_append(void *data, long data_size, int non_block,
const TPF_FSDD_FILEDATA *filedata)
{
return data_size;
}
Related Information