xdf_write - Write samples to a xDF file

       The  library  makes  sure that data written to xDF files are safely stored on stable storage on a regular
       basis but because of double buffering, 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), atmost 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.

xdf_write()  writes  ns samples to the xDF file referenced by xdf. This file should have been opened with
       mode XDF_WRITE and xdf_prepare_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.

EINVALxdf 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

/*AssumexdfreferencesaxDFfileopenedforwritingwhosechannelssourcetheirdatain2arraysoffloatwhosestridesarethelengthofrespectively4and6floatvalues,i.e.16and24bytes(inmostplatforms)*/#defineNS3floatarray1[NS][4],array2[NS][6];unsignedintstrides={4*sizeof(float),6*sizeof(float)};unsignedinti;xdf_define_arrays(xdf,2,strides);if(xdf_prepare_transfer(xdf))return1;for(i=0;i<45;i+=NS){/*Updatethevaluescontainedinarray1andarray2*/.../*Writethevaluestothefile*/if(xdf_write(xdf,NS,array1,array2))return1;}xdf_close(xdf);

       xdf_write - Write samples to a xDF file

       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.

       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.

xdf_set_chconf(3), xdf_define_arrays(3), xdf_prepare_transfer(3)

EPFL                                                  2010                                          XDF_WRITE(3)

#include<xdfio.h>ssize_txdf_write(structxdf*xdf,size_tns,...);