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

- 4.10.16.1 API

##
4.10.16 nxo_file

The nxo_file class is a subclass of the nxo class.

### 4.10.16.1 API

cw_sint32_t cw_nxo_file_read_t(void *a_arg, cw_nxo_t *a_file, cw_uint32_t a_len, cw_uint8_t *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.

cw_bool_t cw_nxo_file_write_t(void *a_arg, cw_nxo_t *a_file, const cw_uint8_t *a_str, cw_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, cw_bool_t 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, cw_nx_t *a_nx):

  Input(s):
    a_arg:
      Opaque data pointer.
    a_nx:
      Pointer to an nx.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Destructor function typedef.

void nxo_file_new(cw_nxo_t *a_nxo, cw_nx_t *a_nx, cw_bool_t a_locking):

  Input(s):
    a_nxo:
      Pointer to a file nxo.
    a_nx:
      Pointer to an nx.
    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, cw_uint32_t a_fd, cw_bool_t 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 cw_uint8_t *a_filename, cw_uint32_t a_nlen, const cw_uint8_t *a_flags, cw_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.

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

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

cw_bool_t nxo_file_nonblocking_set(cw_nxo_t *a_nxo, cw_bool_t 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.

cw_sint32_t nxo_file_read(cw_nxo_t *a_nxo, cw_uint32_t a_len, cw_uint8_t *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, cw_bool_t a_locking, cw_nxo_t *r_string, cw_bool_t *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 cw_bool_t .
  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 cw_uint8_t *a_str, cw_uint32_t a_len, cw_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.

cw_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, cw_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.17 nxo_fino Up: 4.10 Classes Previous: 4.10.15 nxo_dict Contents Index