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_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.

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 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),  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)