gtpc2mje | 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
read from a file device to get input data from an open special file.
Format
typedef long TPF_FSDD_GET(void *buffer, long buffer_size, long position,
int noblock, const TPF_FSDD_FILEDATA *filedata);
- buffer
- The address of the data buffer into which the input data will be
read. buffer is not a null pointer, but the range of
addresses buffer through buffer + buffer_size
- 1 is not verified to be either addressable or writable.
- buffer_size
- The size of the input data buffer for the file.
buffer_size ranges from 1 to
2 147 483 647 (2**31 - 1)
inclusive.
- position
- The logical position in the file from which the first byte of data will be
read. position ranges from 0 to
2 147 483 647 (2**31 - 1)
inclusive. The sum of buffer_size + position is
guaranteed to range from 1 to 2 147 483 648
(2**31) inclusive.
- noblock
- Nonblocking read request indicator.
For files that support nonblocking reads 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 read.
- If noblock does not equal zero, the function does not block the
process. If some data can be read without blocking the process, the
function reads what it can and returns the number of bytes read.
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 read.
Normal Return
The number of bytes read into buffer, from 0 to
buffer_size inclusive.
Error Return
-1 means there was an error during the read operation. The
device driver should also set errno to specify the type of
error. The contents of buffer cannot be predicted.
Programming Considerations
- The TPF_FSDD_GET-type device driver function is called only for
open files that were successfully opened by the corresponding
TPF_FSDD_OPEN-type device driver function. More than one
instance of a single file can be open at the same time.
- The TPF_FSDD_GET-type device driver function is never called
when a file is opened with write-only access.
- A return value of 0 means that the end of the file was reached.
- Note:
- The Portable Operating System Interface for Computing Environments (POSIX)
does not consider an end-of-file condition to be an error condition.
The POSIX read function returns 0 bytes if an attempt is made to
read at a position beyond the end of the file, and does not set any error
flag. The standard C stream input/output (I/O) functions (in
stdio.h) interpret zero bytes read as the EOF
condition.
- A return value greater than 0 but less than buffer_size
specifies one of the following conditions:
- There were less than buffer_size bytes of data between
position and the logical end of data.
- There were less than buffer_size bytes of data immediately
available for a nonblocking read request.
- Only part of the requested data was successfully read into
buffer before an error prevented the remaining data from being
read. Here, the error condition would be raised only if it persisted to
the next read, preventing any bytes of data from being returned, at which time
the device driver should return -1 and set errno.
- If there is no data immediately available to satisfy a nonblocking read
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 read request from returning any valid data, the device driver
should set errno to specify the type of error and return
-1.
Examples
The following example is the get device driver interface function for the
null file (/dev/null).
#include <c$spif.h> /* Device driver interface */
/**********************************************************************/
/* The null_get() always returns 0 (signifying, EOF). */
/**********************************************************************/
long null_get(void *buffer, long buffer_size, long position,
int non_block, const TPF_FSDD_FILEDATA *filedata)
{
return 0;
}
Related Information