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

begin

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

it	A 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.

end

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

This handler is called after all records have been output.

Parameters

it	A pointer to the current vfile iterator.

Note

This handler is optional and the pointer may be NULL.

next

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

it	A 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.

rewind

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

it	A 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.

show

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

it	A pointer to the current vfile iterator.
data	A 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.

store

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

input

A 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:

• include/cobalt/kernel/vfile.h