Group PJ_FILE_IO

group PJ_FILE_IO

This file contains functionalities to perform file I/O. The file I/O can be implemented with various back-end, either using native file API or ANSI stream.

Enums

enum pj_file_access

These enumerations are used when opening file. Values PJ_O_RDONLY, PJ_O_WRONLY, and PJ_O_RDWR are mutually exclusive. Value PJ_O_APPEND can only be used when the file is opened for writing.

Values:

PJ_O_RDONLY = 0x1101

Open file for reading.

PJ_O_WRONLY = 0x1102

Open file for writing.

PJ_O_RDWR = 0x1103

Open file for reading and writing. File will be truncated.

PJ_O_APPEND = 0x1108

Append to existing file.

enum pj_file_seek_type

The seek directive when setting the file position with pj_file_setpos.

Values:

PJ_SEEK_SET = 0x1201

Offset from beginning of the file.

PJ_SEEK_CUR = 0x1202

Offset from current position.

PJ_SEEK_END = 0x1203

Size of the file plus offset.

Functions

pj_status_t pj_file_open(pj_pool_t *pool, const char *pathname, unsigned flags, pj_oshandle_t *fd)

Open the file as specified in pathname with the specified mode, and return the handle in fd. All files will be opened as binary.

Return

PJ_SUCCESS or the appropriate error code on error.

Parameters
  • pool: Pool to allocate memory for the new file descriptor.

  • pathname: The file name to open.

  • flags: Open flags, which is bitmask combination of pj_file_access enum. The flag must be either PJ_O_RDONLY, PJ_O_WRONLY, or PJ_O_RDWR. When file writing is specified, existing file will be truncated unless PJ_O_APPEND is specified.

  • fd: The returned descriptor.

pj_status_t pj_file_close(pj_oshandle_t fd)

Close an opened file descriptor.

Return

PJ_SUCCESS or the appropriate error code on error.

Parameters
  • fd: The file descriptor.

pj_status_t pj_file_write(pj_oshandle_t fd, const void *data, pj_ssize_t *size)

Write data with the specified size to an opened file.

Return

PJ_SUCCESS or the appropriate error code on error.

Parameters
  • fd: The file descriptor.

  • data: Data to be written to the file.

  • size: On input, specifies the size of data to be written. On return, it contains the number of data actually written to the file.

pj_status_t pj_file_read(pj_oshandle_t fd, void *data, pj_ssize_t *size)

Read data from the specified file. When end-of-file condition is set, this function will return PJ_SUCCESS but the size will contain zero.

Return

PJ_SUCCESS or the appropriate error code on error. When EOF occurs, the return is PJ_SUCCESS but size will report zero.

Parameters
  • fd: The file descriptor.

  • data: Pointer to buffer to receive the data.

  • size: On input, specifies the maximum number of data to read from the file. On output, it contains the size of data actually read from the file. It will contain zero when EOF occurs.

pj_status_t pj_file_setpos(pj_oshandle_t fd, pj_off_t offset, enum pj_file_seek_type whence)

Set file position to new offset according to directive whence.

Return

PJ_SUCCESS or the appropriate error code on error.

Parameters
  • fd: The file descriptor.

  • offset: The new file position to set.

  • whence: The directive.

pj_status_t pj_file_getpos(pj_oshandle_t fd, pj_off_t *pos)

Get current file position.

Return

PJ_SUCCESS or the appropriate error code on error.

Parameters
  • fd: The file descriptor.

  • pos: On return contains the file position as measured from the beginning of the file.

pj_status_t pj_file_flush(pj_oshandle_t fd)

Flush file buffers.

Return

PJ_SUCCESS or the appropriate error code on error.

Parameters
  • fd: The file descriptor.