gtpc2mji | 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
write to a file device to put output data to an open special file. When
a process ends, any data remaining in file stream buffers is flushed to the
file as part of the process of closing the open files.
Format
typedef long TPF_FSDD_PUT(void *buffer, long data_size, long position,
int noblock, const TPF_FSDD_FILEDATA *filedata);
- buffer
- The address of the data buffer from which the output data will be
written. 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 written to file.
data_size ranges from 1 to
2 147 483 647 (2**31 - 1)
inclusive.
- position
- The logical position in the file to which the first byte of data will be
written. position ranges from 0 to
2 147 483 647 (2**31 - 1)
inclusive. The sum of data_size + position is
guaranteed to range from 1 to 2 147 483 648
(2**31) inclusive. If position is greater than the current
logical file size and the put operation is successful, the bytes between the
old end of data and the new data (logically) contain \0.
- noblock
- Nonblocking write 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 written.
- If noblockdoes not equal zero, the function does not block the
process. If some data can be written without blocking the process, the
function writes what it can and returns the number of bytes written.
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 written.
Normal Return
The number of bytes written from buffer, from 1 to
data_size inclusive.
- Note:
- When zero bytes of data are requested to be written, TPF file system C
functions return zero without calling this device driver function.
Error Return
-1 means there was an error during the write operation. The
device driver should also set errno to specify the type of
error.
Programming Considerations
- The TPF_FSDD_PUT-type device driver function is called only 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_PUT-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 written, 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 specifies
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 that could be written without
blocking for a nonblocking write request.
- Only part of the requested data was successfully written to file before an
error prevented the remaining data from being written. Here, the error
condition is reported on the next write (if it persists and prevents any data
from being written), at which time the device driver returns -1 and sets
errno.
- If no data can be immediately written to satisfy a nonblocking write
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.
- If the new data is written beyond the previous end of data in the file,
any intervening bytes should be (logically) written as \0.
Examples
The following example is the put device driver interface function for the
null file (/dev/null).
#include <c$spif.h> /* Device driver interface */
/**********************************************************************/
/* The null_put() function writes to a null file. It always */
/* succeeds. */
/**********************************************************************/
long null_put(void *data, long data_size, long position, int non_block,
const TPF_FSDD_FILEDATA *filedata)
{
return data_size;
}
Related Information