next up previous contents index
Next: 4.10.19 nxo_fino Up: 4.10 Classes Previous: 4.10.17 nxo_dict   Contents   Index

Subsections


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 up previous contents index
Next: 4.10.19 nxo_fino Up: 4.10 Classes Previous: 4.10.17 nxo_dict   Contents   Index
Jason Evans 2005-03-16