XDF_SEEK(3) xdffileio library manual XDF_SEEK(3)NAME
xdf_seek - move the sample pointer of a xDF file
SYNOPSIS
#include <xdfio.h>
off_t xdf_seek(struct xdf* xdf, off_t offset, int whence);
DESCRIPTION
xdf_seek() repositions the current sample pointer according to the couple (offset,whence) where whence can be:
SEEK_SET
The offset is set to offset bytes.
SEEK_CUR
The offset is set to its current location plus offset bytes.
SEEK_END
The offset is set to the size of the file plus offset bytes.
The file referenced by xdf should have been opened with mode XDF_READ and xdf_prepare_arrays(3) should have been successfully called on it.
RETURN VALUE
Upon successful completion, xdf_seek() returns the resulting offset location as measured in number of samples from the beginning of the
recording. Otherwise, a value of -1 is returned and errno is set to indicate the error.
ERRORS
EINVAL xdf is NULL or whence is none of the allowed values.
EPERM No successfull call to xdf_prepare_transfer(3) have been done on xdf or it has been opened using the mode XDF_WRITE.
ERANGE The requested offset is out of the range of the recording.
EINTR The call was interrupted by a signal before any data was read; see signal(7).
EIO A low-level I/O error occurred while reading from the inode.
ESTALE Stale file handle. This error can occur for NFS and for other file systems
SEE ALSO xdf_define_arrays(3), xdf_prepare_transfer(3)EPFL 2010 XDF_SEEK(3)
Check Out this Related Man Page
XDF_WRITE(3) xdffileio library manual XDF_WRITE(3)NAME
xdf_write - Write samples to a xDF file
SYNOPSIS
#include <xdfio.h>
ssize_t xdf_write(struct xdf* xdf, size_t ns, ...);
DESCRIPTION
xdf_write() writes ns samples to the xDF file referenced by xdf. This file should have been opened with mode XDF_WRITE and xdf_pre-
pare_arrays(3) should have been successfully called on it. xdf_write() will fail otherwise).
The data to be added should be contained in arrays specified by pointers provided in the variable list of arguments of the function. The
function expects the same number of arrays as specified by previous call to xdf_define_arrays(3). The internal organisation of the data in
the arrays should have been specified previously with calls to xdf_set_chconf(3).
In addition, it is important to note that none of the arrays should overlap.
RETURN VALUE
The function returns the number of the samples successfully added to the xDF file in case of success. Otherwise -1 is returned and errno is
set appropriately.
ERRORS
EINVAL xdf is NULL
EPERM No successfull call to xdf_prepare_transfer(3) have been done on xdf or it has been opened using the mode XDF_READ.
EFBIG An attempt was made to write a file that exceeds the implementation-defined maximum file size or the process's file size limit, or
to write at a position past the maximum allowed offset.
EINTR The call was interrupted by a signal before any data was written; see signal(7).
EIO A low-level I/O error occurred while modifying the inode.
ENOSPC The device containing the xDF file has no room for the data.
ESTALE Stale file handle. This error can occur for NFS and for other file systems
PERFORMANCE CONSIDERATION
By design of the library, a call to xdf_write() is "almost" ensured to be executed in a linear time, i.e. given a fixed configuration of an
xDF file, for the same number of samples to be passed, a call xdf_write will almost take always the same time to complete. This time
increases linearly with the number of samples. This insurance is particularly useful for realtime processing of data, since storing the
data will impact the main loop in a predictible way.
This is achieved by double buffering the data for writing. A front and a back buffer are available: the front buffer is filled with the
incoming data, and swapped with the back buffer when full. This swap signals a background thread to convert, reorganise, scale and save to
the disk the data contained in the full buffer making it afterwards available for the next swap.
This approach ensures a linear calltime of xdf_write() providing that I/O subsystem is not saturated neither all processing units (cores or
processors), i.e. the application is neither I/O bound nor CPU bound.
DATA SAFETY
The library makes sure that data written to xDF files are safely stored on stable storage on a regular basis but because of double buffer-
ing, there is a risk to loose data in case of problem. However, the design of the xdf_write() ensures that if a problem occurs (no more
disk space, power supply cut), at most two records of data plus the size of the chunks of data supplied to the function will be lost.
As an example, assuming you record a xDF file at 256Hz using records of 256 samples and you feed xdf_write() with chunks of 8 samples, you
are ensured to receive notification of failure after at most 520 samples corresponding to a lose of at most a little more than 2s of data
in case of problems.
EXAMPLE
/* Assume xdf references a xDF file opened for writing whose
channels source their data in 2 arrays of float whose strides
are the length of respectively 4 and 6 float values,
i.e. 16 and 24 bytes (in most platforms)*/
#define NS 3
float array1[NS][4], array2[NS][6];
unsigned int strides = {4*sizeof(float), 6*sizeof(float)};
unsigned int i;
xdf_define_arrays(xdf, 2, strides);
if (xdf_prepare_transfer(xdf))
return 1;
for (i=0; i<45; i+=NS) {
/* Update the values contained in array1 and array2*/
...
/* Write the values to the file */
if (xdf_write(xdf, NS, array1, array2))
return 1;
}
xdf_close(xdf);
SEE ALSO xdf_set_chconf(3), xdf_define_arrays(3), xdf_prepare_transfer(3)EPFL 2010 XDF_WRITE(3)