4.10.18 nxo_file
Keywords: onyx

Next: 4.10.19 nxo_fino Up: 4.10 Classes Previous: 4.10.17 nxo_dict Contents Index
Subsections

- 4.10.18.1 API

##
4.10.18 nxo_file

The nxo_file class is a subclass of the nxo class.

### 4.10.18.1 API

int32_t cw_nxo_file_read_t(void *a_arg, cw_nxo_t *a_file, uint32_t a_len, char *r_str):

  Input(s):
    a_arg:
      Opaque data pointer.
    a_file:
      Pointer to a file nxo.
    a_len:
      Length of r_str.
    r_str:
      Pointer to space to put read data.
  Output(s):
    retval:
      -1:
        Read error.
      >= 0:
        Number of bytes stored in r_str.
    r_str:
      If retval is non-negative, retval bytes of read data, otherwise undefined.
  Exception(s):
    Application specific.
  Description:
    Read up to a_len bytes of data from a_file and store the result in r_str.

bool cw_nxo_file_write_t(void *a_arg, cw_nxo_t *a_file, const char *a_str, uint32_t a_len):

  Input(s):
    a_arg:
      Opaque data pointer.
    a_file:
      Pointer to a file nxo.
    a_str:
      Pointer to data to write.
    a_len:
      Length of a_str.
  Output(s):
    retval:
      false:
        Success.
      true:
        Write error.
  Exception(s):
    Application specific.
  Description:
    Write a_len bytes of data from a_str to a_file.

cw_nxoe_t * cw_nxo_file_ref_iter_t(void *a_arg, bool a_reset):

  Input(s):
    a_arg:
      Opaque data pointer.
    a_reset:
      false:
        At least one iteration has already occurred.
      true:
        First iteration.
  Output(s):
    retval:
      non-NULL:
        Pointer to an nxoe.
      NULL:
        No more references.
  Exception(s):
    None.
  Description:
    Reference iterator function typedef.

void cw_nxo_file_delete_t(void *a_arg):

  Input(s):
    a_arg:
      Opaque data pointer.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Destructor function typedef.

void nxo_file_new(cw_nxo_t *a_nxo, bool a_locking):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_locking:
      Implicit locking mode.
  Output(s):
    None.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Constructor.

void nxo_file_fd_wrap(cw_nxo_t *a_nxo, uint32_t a_fd, bool a_close):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_fd:
      File descriptor number.
    a_close:
      If true, close a_fd when a_nxo is finalized by the garbage collector, otherwise, do not automatically close a_fd. This should typically be set to true.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Wrap file descriptor a_fd so that operations on a_nxo will be backed by the file descriptor.

void nxo_file_synthetic(cw_nxo_t *a_nxo, cw_nxo_file_read_t *a_read, cw_nxo_file_write_t *a_write, cw_nxo_file_ref_iter_t *a_ref_iter, cw_nxo_file_delet_t *a_delete, void *a_arg):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_read:
      Pointer to a read function.
    a_write:
      Pointer to a write function.
    a_ref_iter:
      Pointer to a reference iterator function.
    a_delete:
      Pointer to a destructor function.
    a_arg:
      Opaque pointer to be passed to the read and write functions.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Set up a_nxo to call the specified read and write functions to satisfy file operations.

cw_nxn_t nxo_file_open(cw_nxo_t *a_nxo, const char *a_filename, uint32_t a_nlen, const char *a_flags, uint32_t a_flen):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_filename:
      Pointer to a string (not required to be '\0' terminated) that represents a filename.
    a_nlen:
      Length in bytes of a_filename.
    a_flags:
      Pointer to a string (not required to be '\0' terminated) that represents a file mode:
      ``r'':
        Read only.
      ``r+'':
        Read/write, starting at offset 0.
      ``w'':
        Write only. Create file if necessary. Truncate file if non-zero length.
      ``w+'':
        Read/write, starting at offset 0. Create file if necessary.
      ``a'':
        Write only, starting at end of file.
      ``a+'':
        Read/write, starting at end of file.
    a_flen:
      Length in bytes of a_flags.
  Output(s):
    retval:
      NXN_ZERO.
      NXN_ioerror.
      NXN_invalidfileaccess.
      NXN_limitcheck.
  Exception(s):
    None.
  Description:
    Open a file.

cw_nxn_t nxo_file_close(cw_nxo_t *a_nxo):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
  Output(s):
    retval:
      NXN_ZERO.
      NXN_ioerror.
  Exception(s):
    None.
  Description:
    Close a file.

void nxo_file_origin_get(cw_nxo_t *a_nxo, const char **r_origin, uint32_t *r_olen):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    r_origin:
      Pointer to a string pointer.
    r_olen:
      Pointer to an unsigned integer.
  Output(s):
    *r_origin:
      A pointer to a string that represents the origin of a_nxo.
    *r_olen:
      The length of the string pointed to by *r_origin.
  Exception(s):
    None.
  Description:
    Get the origin of a_nxo.

bool nxo_file_origin_set(cw_nxo_t *a_nxo, const char *a_origin, uint32_t a_olen):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_origin:
      Pointer to a string that represents the origin of a_nxo.
    a_olen:
      The length of the string pointed to bya_origin.
  Output(s):
    None.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Set the origin of a_nxo. A copy of a_origin is made and managed internally.

int32_t nxo_file_fd_get(const cw_nxo_t *a_nxo):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
  Output(s):
    retval:
      -1:
        Invalid or synthetic file.
      >= 0:
        File descriptor number.
  Exception(s):
    None.
  Description:
    Return the file descriptor associated with a_nxo.

bool nxo_file_nonblocking_get(const cw_nxo_t *a_nxo):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
  Output(s):
    retval:
      false:
        Blocking file.
      true:
        Non-blocking file.
  Exception(s):
    None.
  Description:
    Return the non-blocking mode for a_nxo.

bool nxo_file_nonblocking_set(cw_nxo_t *a_nxo, bool a_nonblocking):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_nonblocking:
      Non-blocking mode to set nxo to.
  Output(s):
    retval:
      false:
        Success.
      true:
        I/O error or non-POSIX file.
  Exception(s):
    None.
  Description:
    Set the non-blocking mode for a_nxo to a_nonblocking.

int32_t nxo_file_read(cw_nxo_t *a_nxo, uint32_t a_len, char *r_str):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_len:
      Length in bytes of r_str.
    r_str:
      Pointer to a string to store read data into.
  Output(s):
    retval:
      -1:
        NXN_ioerror.
      >= 0:
        Number of bytes of data read into r_str.
    r_str:
      If retval is non-negative, retval bytes of read data.
  Exception(s):
    None.
  Description:
    Read data.

cw_nxn_t nxo_file_readline(cw_nxo_t *a_nxo, cw_nx_t *a_nx, bool a_locking, cw_nxo_t *r_string, bool *r_eof):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_nx:
      Pointer to an nx.
    a_locking:
      Implicit locking mode.
    r_string:
      Pointer to an nxo.
    r_eof:
      Pointer to a bool.
  Output(s):
    retval:
      NXN_ZERO.
      NXN_ioerror.
    r_string:
      If retval is NXN_ZERO, a string object, otherwise unmodified.
    *r_eof:
      false:
        End of file not reached.
      true:
        End of file reached.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Read a line, terminated by ``\r'', ``\r\n'', or EOF.

cw_nxn_t nxo_file_write(cw_nxo_t *a_nxo, const char *a_str, uint32_t a_len, uint32_t *r_count):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_str:
      Pointer to data to write.
    a_len:
      Length of a_str.
    r_count:
      Pointer to a location to store the number of bytes written, or NULL.
  Output(s):
    retval:
      NXN_ZERO.
      NXN_ioerror.
    *r_count:
      If r_count is non-NULL, and retval is NXN_ZERO, number of bytes written, otherwise undefined.
  Exception(s):
    None.
  Description:
    Write the a_len bytes of data pointed to a_str. If the file is in non-blocking mode, it is possible for *r_count to be as small as 0 for a successful write.

cw_nxn_t nxo_file_truncate(cw_nxo_t *a_nxo, off_t a_length):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_length:
      Length to set file to.
  Output(s):
    retval:
      NXN_ZERO.
      NXN_ioerror.
  Exception(s):
    None.
  Description:
    Truncate or extend the file associated with a_nxo so that it is a_length bytes long.

cw_nxoi_t nxo_file_position_get(cw_nxo_t *a_nxo):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
  Output(s):
    retval:
      -1:
        NXN_ioerror.
      >= 0:
        Current file position.
  Exception(s):
    None.
  Description:
    Get the current file position.

cw_nxn_t nxo_file_position_set(cw_nxo_t *a_nxo, cw_nxoi_t a_position):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_position:
      File position.
  Output(s):
    retval:
      NXN_ZERO.
      NXN_ioerror.
  Exception(s):
    None.
  Description:
    Move the current file position to a_position.

uint32_t nxo_file_buffer_size_get(const cw_nxo_t *a_nxo):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
  Output(s):
    retval:
      Size in bytes of the internal data buffer.
  Exception(s):
    None.
  Description:
    Return the size of the internal data buffer.

void nxo_file_buffer_size_set(cw_nxo_t *a_nxo, uint32_t a_size):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_size:
      Size in bytes of internal buffer to use.
  Output(s):
    None.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Use an internal buffer of a_size bytes.

cw_nxoi_t nxo_file_buffer_count(const cw_nxo_t *a_nxo):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
  Output(s):
    retval:
      Current number of buffered bytes available for reading.
  Exception(s):
    None.
  Description:
    Return the current number of buffered bytes available for reading.

cw_nxn_t nxo_file_buffer_flush(cw_nxo_t *a_nxo):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
  Output(s):
    retval:
      NXN_ZERO.
      NXN_ioerror.
  Exception(s):
    None.
  Description:
    Flush any buffered write data to disk, and discard any buffered read data.

Next: 4.10.19 nxo_fino Up: 4.10 Classes Previous: 4.10.17 nxo_dict Contents Index