xdf_write(3)

1XDF_WRITE(3)               xdffileio library manual               XDF_WRITE(3)
2
3
4

NAME

6       xdf_write - Write samples to a xDF file
7

SYNOPSIS

9       #include <xdfio.h>
10
11       ssize_t xdf_write(struct xdf* xdf, size_t ns, ...);
12

DESCRIPTION

14       xdf_write()  writes  ns samples to the xDF file referenced by xdf. This
15       file  should  have  been  opened  with  mode  XDF_WRITE  and   xdf_pre‐
16       pare_arrays(3) should have been successfully called on it.  xdf_write()
17       will fail otherwise).
18
19       The data to be added should be contained in arrays specified by  point‐
20       ers  provided  in  the variable list of arguments of the function.  The
21       function expects the same number of arrays  as  specified  by  previous
22       call  to xdf_define_arrays(3). The internal organisation of the data in
23       the  arrays  should  have  been  specified  previously  with  calls  to
24       xdf_set_chconf(3).
25
26       In  addition,  it  is  important to note that none of the arrays should
27       overlap.
28

RETURN VALUE

30       The function returns the number of the samples  successfully  added  to
31       the  xDF file in case of success. Otherwise -1 is returned and errno is
32       set appropriately.
33

ERRORS

35       EINVAL xdf is NULL
36
37       EPERM  No successfull call to xdf_prepare_transfer(3) have been done on
38              xdf or it has been opened using the mode XDF_READ.
39
40       EFBIG  An attempt was made to write a file that exceeds the implementa‐
41              tion-defined maximum file size or the process's file size limit,
42              or to write at a position past the maximum allowed offset.
43
44       EINTR  The  call  was interrupted by a signal before any data was writ‐
45              ten; see signal(7).
46
47       EIO    A low-level I/O error occurred while modifying the inode.
48
49       ENOSPC The device containing the xDF file has no room for the data.
50
51       ESTALE Stale file handle. This error can occur for NFS  and  for  other
52              file systems
53

PERFORMANCE CONSIDERATION

55       By  design of the library, a call to xdf_write() is "almost" ensured to
56       be executed in a linear time, i.e. given a fixed  configuration  of  an
57       xDF file, for the same number of samples to be passed, a call xdf_write
58       will almost take always the same time to complete. This time  increases
59       linearly  with  the  number  of samples. This insurance is particularly
60       useful for realtime processing of data, since  storing  the  data  will
61       impact the main loop in a predictible way.
62
63       This  is achieved by double buffering the data for writing. A front and
64       a back buffer are available: the front buffer is filled with the incom‐
65       ing data, and swapped with the back buffer when full. This swap signals
66       a background thread to convert, reorganise, scale and save to the  disk
67       the  data  contained  in the full buffer making it afterwards available
68       for the next swap.
69
70       This approach ensures a linear calltime of xdf_write()  providing  that
71       I/O  subsystem  is not saturated neither all processing units (cores or
72       processors), i.e. the application is neither I/O bound nor CPU bound.
73

DATA SAFETY

75       The library makes sure that data written to xDF files are safely stored
76       on  stable  storage on a regular basis but because of double buffering,
77       there is a risk to loose data in case of problem. However,  the  design
78       of  the  xdf_write()  ensures  that  if  a problem occurs (no more disk
79       space, power supply cut), at most two records of data plus the size  of
80       the chunks of data supplied to the function will be lost.
81
82       As an example, assuming you record a xDF file at 256Hz using records of
83       256 samples and you feed xdf_write() with chunks of 8 samples, you  are
84       ensured  to  receive  notification of failure after at most 520 samples
85       corresponding to a lose of at most a little more than  2s  of  data  in
86       case of problems.
87

EXAMPLE

89              /* Assume xdf references a xDF file opened for writing whose
90              channels source their data in 2 arrays of float whose strides
91              are the length of respectively 4 and 6 float values,
92              i.e. 16 and 24 bytes (in most platforms)*/
93              #define NS    3
94              float array1[NS][4], array2[NS][6];
95              unsigned int strides = {4*sizeof(float), 6*sizeof(float)};
96              unsigned int i;
97
98              xdf_define_arrays(xdf, 2, strides);
99              if (xdf_prepare_transfer(xdf))
100                   return 1;
101
102              for (i=0; i<45; i+=NS) {
103                   /* Update the values contained in array1 and array2*/
104                   ...
105
106                   /* Write the values to the file */
107                      if (xdf_write(xdf, NS, array1, array2))
108                        return 1;
109              }
110
111              xdf_close(xdf);
112
113