Snapshot vfile operation descriptor. More...

Data Fields
int(*	rewind )(struct xnvfile_snapshot_iterator *it)

void (	begin )(struct xnvfile_snapshot_iterator *it)

void(*	end )(struct xnvfile_snapshot_iterator it, void buf)

int(*	next )(struct xnvfile_snapshot_iterator it, void data)

int(*	show )(struct xnvfile_snapshot_iterator it, void data)

ssize_t(*	store )(struct xnvfile_input *input)

Detailed Description

Snapshot vfile operation descriptor.

This structure describes the operations available with a snapshot-driven vfile. It defines handlers for returning a printable snapshot of some Xenomai object contents upon a user-space read request, and for updating this object upon a user-space write request.

Field Documentation

void*(* xnvfile_snapshot_ops::begin) (struct xnvfile_snapshot_iterator *it)

This handler should allocate the snapshot buffer to hold records during the data collection phase. When specified, all records collected via the next()handler" will be written to a cell from the memory area returned by begin().

Parameters

it	A pointer to the current snapshot iterator.

Returns: A pointer to the record buffer, if the call succeeds. Otherwise:

NULL in case of allocation error. This will abort the data collection, and return -ENOMEM to the reader.
VFILE_SEQ_EMPTY, a special value indicating that no record will be output. In such a case, the next() handler will not be called, and the data collection will stop immediately. However, the show() handler will still be called once, with a NULL data pointer (i.e. header display request).

Note: This handler is optional; if none is given, an internal allocation depending on the value returned by the rewind() handler can be obtained.

void(* xnvfile_snapshot_ops::end) (struct xnvfile_snapshot_iterator *it, void *buf)

This handler releases the memory buffer previously obtained from begin(). It is usually called after the snapshot data has been output by show(), but it may also be called before rewinding the vfile after a revision change, to release the dropped buffer.

Parameters

it	A pointer to the current snapshot iterator.
buf	A pointer to the buffer to release.

Note: This routine is optional and the pointer may be NULL. It is not needed upon internal buffer allocation; see the description of the rewind()handler".

int(* xnvfile_snapshot_ops::next) (struct xnvfile_snapshot_iterator *it, void *data)

This handler fetches the next record, as part of the snapshot data to be sent back to the reader via the show().

Parameters

it	A pointer to the current snapshot iterator.
data	A pointer to the record to fill in.

Returns: a strictly positive value, if the call succeeds and leaves a valid record into data, which should be passed to the show() handler() during the formatting and output phase. Otherwise:

A negative error code. This will abort the data collection, and return this status to the reader.
VFILE_SEQ_SKIP, a special value indicating that the current record should be skipped. In such a case, the data pointer is not advanced to the next position before the next() handler is called anew.

Note: This handler is called with the vfile lock held. Before each invocation of this handler, the vfile core checks whether the revision tag has been touched, in which case the data collection is restarted from scratch. A data collection phase succeeds whenever all records can be fetched via the next() handler, while the revision tag remains unchanged, which indicates that a consistent snapshot of the object state was taken.

int(* xnvfile_snapshot_ops::rewind) (struct xnvfile_snapshot_iterator *it)

This handler (re-)initializes the data collection, moving the seek pointer at the first record. When the file revision tag is touched while collecting data, the current reading is aborted, all collected data dropped, and the vfile is eventually rewound.

Parameters

it	A pointer to the current snapshot iterator. Two useful information can be retrieved from this iterator in this context:

it->vfile is a pointer to the descriptor of the virtual file being rewound.
xnvfile_iterator_priv(it) returns a pointer to the private data area, available from the descriptor, which size is vfile->privsz. If the latter size is zero, the returned pointer is meaningless and should not be used.

Returns: A negative error code aborts the data collection, and is passed back to the reader. Otherwise:

a strictly positive value is interpreted as the total number of records which will be returned by the next() handler during the data collection phase. If no begin() handler is provided in the operation descriptor, this value is used to allocate the snapshot buffer internally. The size of this buffer would then be vfile->datasz * value.
zero leaves the allocation to the begin() handler if present, or indicates that no record is to be output in case such handler is not given.

Note: This handler is optional; a NULL value indicates that nothing needs to be done for rewinding the vfile. It is called with the vfile lock held.

int(* xnvfile_snapshot_ops::show) (struct xnvfile_snapshot_iterator *it, void *data)

This handler should format and output a record from the collected data.

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 snapshot iterator.
data	A pointer to the record to format then output. The first call to the handler is always passed a NULL data pointer; 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_snapshot_ops::store) (struct xnvfile_input *input)

This handler receives data written to the vfile, likely for updating the associated Xenomai object's state, 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.

Referenced by xnvfile_init_snapshot().

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

include/nucleus/vfile.h

Data Fields

Detailed Description

Field Documentation