XDF_READ(3)

🌸 XDF_READ(3) — the xdffileio library manual, but make it make sense 🌸

okay bestie, pull up a chair, we're reading samples out of an xDF file and it's gonna be so slay. this one lives in the xdffileio library manual btw, so that's the vibe of the whole family, iykyk 💅

✨ NAME ✨

xdf_read — Read samples from a xDF file 🫶

✨ SYNOPSIS ✨

#include <xdfio.h>

int xdf_read(struct xdf* xdf, unsigned int ns, ...);

✨ DESCRIPTION ✨

so xdf_read() literally just reads ns samples out of the xDF file that xdf points at. no cap. but — and this is the part where everyone gets humbled — that file has to have been opened with mode XDF_READ, and xdf_prepare_arrays(3) has to have been called on it successfully first. if not? xdf_read() will fail. periodt 😭

where does the data go, you ask? into arrays, and you point at them with pointers you drop into the variable list of arguments of the function. it expects the same number of arrays as whatever you declared in your earlier call to xdf_define_arrays(3). and the internal organisation of the data inside those arrays? that's something you already set up with calls to xdf_set_chconf(3). it's giving "you already told me the plan, i'm just executing it" 💅

also, super important, like genuinely do not skip this: none of the arrays should overlap. not even a little. none of them. that's not a suggestion, bestie 🙈

✨ RETURN VALUE ✨

on success it hands you back the number of samples it successfully read from the xDF file. heads up though: that number can be smaller than the ns you asked for, if you hit the end of the file. that's not a bug, that's just the file running out of lore 🦋

if something goes wrong? -1 is returned and errno gets set appropriately. classic.

✨ ERRORS ✨

• EINVAL — xdf is NULL. bestie. the pointer. it's null. 💀
• EPERM — either nobody ever made a successful call to xdf_prepare_transfer(3) on xdf, or xdf was opened using mode XDF_WRITE. wrong door, wrong room, wrong vibe 🚪
• EINTR — the call got interrupted by a signal before any data was written; go peek at signal(7).
• EIO — a low-level I/O error happened while reading from the inode. ouch.
• ESTALE — stale file handle. this one can pop up on NFS and on other file systems too. NFS girlies stay strong 🌈

✨ EXAMPLE ✨

okay here's the whole thing, copied exactly, no notes:

              /* Assume xdf references a xDF file opened for reading 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) {
                   /* Write the values to the file */
                      if (xdf_write(xdf, NS, array1, array2))
                        return 1;

                   /* Use the values contained in array1 and array2*/
                   ...

              }

              xdf_close(xdf);

yes, the comment says "Write the values to the file" and the call is xdf_write — that is exactly what the original page says, so i am leaving it alone, don't look at me 🙈

✨ SEE ALSO ✨

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

and that's the whole page, bestie 🎀 this one's brought to you by EPFL, dated 2010, and it's the XDF_READ(3) entry in the xdffileio library manual. go read some samples, stay hydrated, and don't let your arrays overlap 💖✨🦋