Xenomai API  2.6.5
xnvfile_regular_ops Struct Reference

Regular vfile operation descriptor. More...

Data Fields

int(* rewind )(struct xnvfile_regular_iterator *it)
 
void *(* begin )(struct xnvfile_regular_iterator *it)
 
void *(* next )(struct xnvfile_regular_iterator *it)
 
void(* end )(struct xnvfile_regular_iterator *it)
 
int(* show )(struct xnvfile_regular_iterator *it, void *data)
 
ssize_t(* store )(struct xnvfile_input *input)
 

Detailed Description

Regular vfile operation descriptor.

This structure describes the operations available with a regular vfile. It defines handlers for sending back formatted kernel data upon a user-space read request, and for obtaining user data upon a user-space write request.

Field Documentation

void*(* xnvfile_regular_ops::begin) (struct xnvfile_regular_iterator *it)

This handler should prepare for iterating over the records upon a read request, starting from the specified position.

Parameters
itA pointer to the current vfile iterator. On entry, it->pos is set to the (0-based) position of the first record to output. This handler may be called multiple times with different position requests.
Returns
A pointer to the first record to format and output, to be passed to the show() handler as its data parameter, if the call succeeds. Otherwise:
  • NULL in case no record is available, in which case the read operation will terminate immediately with no output.
  • VFILE_SEQ_START, a special value indicating that the show() handler should receive a NULL data pointer first, in order to output a header.
  • ERR_PTR(errno), where errno is a negative error code; upon error, the current operation will be aborted immediately.
Note
This handler is optional; if none is given in the operation descriptor (i.e. NULL value), the show() handler() will be called only once for a read operation, with a NULL data parameter. This particular setting is convenient for simple regular vfiles having a single, fixed record to output.
void(* xnvfile_regular_ops::end) (struct xnvfile_regular_iterator *it)

This handler is called after all records have been output.

Parameters
itA pointer to the current vfile iterator.
Note
This handler is optional and the pointer may be NULL.
void*(* xnvfile_regular_ops::next) (struct xnvfile_regular_iterator *it)

This handler should return the address of the next record to format and output by the show()handler".

Parameters
itA pointer to the current vfile iterator. On entry, it->pos is set to the (0-based) position of the next record to output.
Returns
A pointer to the next record to format and output, to be passed to the show() handler as its data parameter, if the call succeeds. Otherwise:
  • NULL in case no record is available, in which case the read operation will terminate immediately with no output.
  • ERR_PTR(errno), where errno is a negative error code; upon error, the current operation will be aborted immediately.
Note
This handler is optional; if none is given in the operation descriptor (i.e. NULL value), the read operation will stop after the first invocation of the show() handler.
int(* xnvfile_regular_ops::rewind) (struct xnvfile_regular_iterator *it)

This handler is called only once, when the virtual file is opened, before the begin() handler is invoked.

Parameters
itA pointer to the vfile iterator which will be used to read the file contents.
Returns
Zero should be returned upon success. Otherwise, a negative error code aborts the operation, and is passed back to the reader.
Note
This handler is optional. It should not be used to allocate resources but rather to perform consistency checks, since no closure call is issued in case the open sequence eventually fails.
int(* xnvfile_regular_ops::show) (struct xnvfile_regular_iterator *it, void *data)

This handler should format and output a record.

xnvfile_printf(), xnvfile_write(), xnvfile_puts() and xnvfile_putc() are available to format and/or emit the output. All routines take the iterator argument it as their first parameter.

Parameters
itA pointer to the current vfile iterator.
dataA pointer to the record to format then output. The first call to the handler may receive a NULL data pointer, depending on the presence and/or return of a hander; the show handler should test this special value to output any header that fits, prior to receiving more calls with actual records.
Returns
zero if the call succeeds, also indicating that the handler should be called for the next record if any. Otherwise:
  • A negative error code. This will abort the output phase, and return this status to the reader.
  • VFILE_SEQ_SKIP, a special value indicating that the current record should be skipped and will not be output.
ssize_t(* xnvfile_regular_ops::store) (struct xnvfile_input *input)

This handler receives data written to the vfile, likely for updating some kernel setting, or triggering any other action which fits. This is the only handler which deals with the write-side of a vfile. It is called when writing to the /proc entry of the vfile from a user-space process.

The input data is described by a descriptor passed to the handler, which may be subsequently passed to parsing helper routines. For instance, xnvfile_get_string() will accept the input descriptor for returning the written data as a null-terminated character string. On the other hand, xnvfile_get_integer() will attempt to return a long integer from the input data.

Parameters
inputA pointer to an input descriptor. It refers to an opaque data from the handler's standpoint.
Returns
the number of bytes read from the input descriptor if the call succeeds. Otherwise, a negative error code. Return values from parsing helper routines are commonly passed back to the caller by the store() handler.
Note
This handler is optional, and may be omitted for read-only vfiles.

The documentation for this struct was generated from the following file: