Files

API for opening, reading and writing files.

Types

oc_file

typedef struct oc_file
{
    u64 h;
} oc_file;

An opaque handle identifying an opened file.

Fields

  • h Opaque file handle.

oc_file_open_flags

typedef u16 oc_file_open_flags;

The type of file open flags describing file open options.

oc_file_open_flags_enum

typedef enum oc_file_open_flags_enum
{
    OC_FILE_OPEN_NONE = 0,
    OC_FILE_OPEN_APPEND = 1,
    OC_FILE_OPEN_TRUNCATE = 2,
    OC_FILE_OPEN_CREATE = 4,
    OC_FILE_OPEN_SYMLINK = 8,
    OC_FILE_OPEN_NO_FOLLOW = 16,
    OC_FILE_OPEN_RESTRICT = 32
} oc_file_open_flags_enum;

Flags for the oc_file_open() function.

Enum Constants

  • OC_FILE_OPEN_NONE No options.
  • OC_FILE_OPEN_APPEND Open the file in 'append' mode. All writes append data at the end of the file.
  • OC_FILE_OPEN_TRUNCATE Truncate the file to 0 bytes when opening.
  • OC_FILE_OPEN_CREATE Create the file if it does not exist.
  • OC_FILE_OPEN_SYMLINK If the file is a symlink, open the symlink itself instead of following it.
  • OC_FILE_OPEN_NO_FOLLOW If the file is a symlink, the call to open will fail.
  • OC_FILE_OPEN_RESTRICT Reserved.

oc_file_access

typedef u16 oc_file_access;


oc_file_access_enum

typedef enum oc_file_access_enum
{
    OC_FILE_ACCESS_NONE = 0,
    OC_FILE_ACCESS_READ = 1,
    OC_FILE_ACCESS_WRITE = 2
} oc_file_access_enum;

This enum describes the access permissions of a file handle.

Enum Constants

  • OC_FILE_ACCESS_NONE The file handle has no access permissions.
  • OC_FILE_ACCESS_READ The file handle can be used for reading from the file.
  • OC_FILE_ACCESS_WRITE The file handle can be used for writing to the file.

oc_file_whence

typedef enum oc_file_whence
{
    OC_FILE_SEEK_SET = 0,
    OC_FILE_SEEK_END = 1,
    OC_FILE_SEEK_CURRENT = 2
} oc_file_whence;

This enum is used in oc_file_seek() to specify the starting point of the seek operation.

Enum Constants

  • OC_FILE_SEEK_SET Set the file position relative to the beginning of the file.
  • OC_FILE_SEEK_END Set the file position relative to the end of the file.
  • OC_FILE_SEEK_CURRENT Set the file position relative to the current position.

oc_io_req_id

typedef u64 oc_io_req_id;

A type used to identify I/O requests.

oc_io_op

typedef u32 oc_io_op;

A type used to identify I/O operations.

oc_io_op_enum

typedef enum oc_io_op_enum
{
    OC_IO_OPEN_AT = 0,
    OC_IO_CLOSE = 1,
    OC_IO_FSTAT = 2,
    OC_IO_SEEK = 3,
    OC_IO_READ = 4,
    OC_IO_WRITE = 5,
    OC_OC_IO_ERROR = 6
} oc_io_op_enum;

This enum declares all I/O operations.

Enum Constants

  • OC_IO_OPEN_AT Open a file at a path relative to a given root directory.

    • handle is the handle to the root directory. If it is nil, the application's default directory is used.
    • size is the size of the path, in bytes.
    • buffer points to an array containing the path of the file to open, relative to the directory identified by handle.
    • open contains the permissions and flags for the open operation.

  • OC_IO_CLOSE Close a file handle.

    • handle is the handle to close.

  • OC_IO_FSTAT Get status information for a file handle.

    • handle is the handle to stat.
    • size is the size of the result buffer. It should be at least sizeof(oc_file_status).
    • buffer is the result buffer.

  • OC_IO_SEEK Move the file position in a file.

    • handle is the handle of the file.
    • offset specifies the offset of the new position, relative to the base position specified by whence.
    • whence determines the base position for the seek operation.

  • OC_IO_READ Read data from a file.

    • handle is the handle of the file.
    • size is the number of bytes to read.
    • buffer is the result buffer. It should be big enough to hold size bytes.

  • OC_IO_WRITE Write data to a file.

    • handle is the handle of the file.
    • size is the number of bytes to write.
    • buffer contains the data to write to the file.

  • OC_OC_IO_ERROR Get the error attached to a file handle.

    • handle is the handle of the file.

oc_io_req

typedef struct oc_io_req
{
    oc_io_req_id id;
    oc_io_op op;
    oc_file handle;
    i64 offset;
    u64 size;
    union
    {
        char* buffer;
        u64 unused;
    };
    union
    {
        struct
        {
            oc_file_access rights;
            oc_file_open_flags flags;
        } open;
        oc_file_whence whence;
    };
} oc_io_req;

A structure describing an I/O request.

Fields

  • id An identifier for the request. You can set this to any value you want. It is passed back in the oc_io_cmp completion and can be used to match requests and completions.
  • op The requested operation.
  • handle A file handle used by some operations.
  • offset An offset used by some operations.
  • size A size indicating the capacity of the buffer pointed to by buffer, in bytes.

oc_io_error

typedef i32 oc_io_error;

A type identifying an I/O error.

oc_io_error_enum

typedef enum oc_io_error_enum
{
    OC_IO_OK = 0,
    OC_IO_ERR_UNKNOWN = 1,
    OC_IO_ERR_OP = 2,
    OC_IO_ERR_HANDLE = 3,
    OC_IO_ERR_PREV = 4,
    OC_IO_ERR_ARG = 5,
    OC_IO_ERR_PERM = 6,
    OC_IO_ERR_SPACE = 7,
    OC_IO_ERR_NO_ENTRY = 8,
    OC_IO_ERR_EXISTS = 9,
    OC_IO_ERR_NOT_DIR = 10,
    OC_IO_ERR_DIR = 11,
    OC_IO_ERR_MAX_FILES = 12,
    OC_IO_ERR_MAX_LINKS = 13,
    OC_IO_ERR_PATH_LENGTH = 14,
    OC_IO_ERR_FILE_SIZE = 15,
    OC_IO_ERR_OVERFLOW = 16,
    OC_IO_ERR_NOT_READY = 17,
    OC_IO_ERR_MEM = 18,
    OC_IO_ERR_INTERRUPT = 19,
    OC_IO_ERR_PHYSICAL = 20,
    OC_IO_ERR_NO_DEVICE = 21,
    OC_IO_ERR_WALKOUT = 22
} oc_io_error_enum;

This enum declares all I/O error values.

Enum Constants

  • OC_IO_OK No error.
  • OC_IO_ERR_UNKNOWN An unexpected error happened.
  • OC_IO_ERR_OP The request had an invalid operation.
  • OC_IO_ERR_HANDLE The request had an invalid handle.
  • OC_IO_ERR_PREV The operation was not carried out because the file handle has previous errors.
  • OC_IO_ERR_ARG The request contained wrong arguments.
  • OC_IO_ERR_PERM The operation requires permissions that the file handle doesn't have.
  • OC_IO_ERR_SPACE The operation couldn't complete due to a lack of space in the result buffer.
  • OC_IO_ERR_NO_ENTRY One of the directory in the path does not exist or couldn't be traversed.
  • OC_IO_ERR_EXISTS The file already exists.
  • OC_IO_ERR_NOT_DIR The file is not a directory.
  • OC_IO_ERR_DIR The file is a directory.
  • OC_IO_ERR_MAX_FILES There are too many opened files.
  • OC_IO_ERR_MAX_LINKS The path contains too many symbolic links (this may be indicative of a symlink loop).
  • OC_IO_ERR_PATH_LENGTH The path is too long.
  • OC_IO_ERR_FILE_SIZE The file is too large.
  • OC_IO_ERR_OVERFLOW The file is too large to be opened.
  • OC_IO_ERR_NOT_READY The file is locked or the device on which it is stored is not ready.
  • OC_IO_ERR_MEM The system is out of memory.
  • OC_IO_ERR_INTERRUPT The operation was interrupted by a signal.
  • OC_IO_ERR_PHYSICAL A physical error happened.
  • OC_IO_ERR_NO_DEVICE The device on which the file is stored was not found.
  • OC_IO_ERR_WALKOUT One element along the path is outside the root directory subtree.

oc_io_cmp

typedef struct oc_io_cmp
{
    oc_io_req_id id;
    oc_io_error error;
    union
    {
        i64 result;
        u64 size;
        i64 offset;
        oc_file handle;
    };
} oc_io_cmp;

A structure describing the completion of an I/O operation.

Fields

  • id The request ID as passed in the oc_io_req request that generated this completion.
  • error The error value for the operation.

oc_file_type

typedef enum oc_file_type
{
    OC_FILE_UNKNOWN = 0,
    OC_FILE_REGULAR = 1,
    OC_FILE_DIRECTORY = 2,
    OC_FILE_SYMLINK = 3,
    OC_FILE_BLOCK = 4,
    OC_FILE_CHARACTER = 5,
    OC_FILE_FIFO = 6,
    OC_FILE_SOCKET = 7
} oc_file_type;

An enum identifying the type of a file.

Enum Constants

  • OC_FILE_UNKNOWN The file is of unknown type.
  • OC_FILE_REGULAR The file is a regular file.
  • OC_FILE_DIRECTORY The file is a directory.
  • OC_FILE_SYMLINK The file is a symbolic link.
  • OC_FILE_BLOCK The file is a block device.
  • OC_FILE_CHARACTER The file is a character device.
  • OC_FILE_FIFO The file is a FIFO pipe.
  • OC_FILE_SOCKET The file is a socket.

oc_file_perm

typedef u16 oc_file_perm;

A type describing file permissions.

oc_file_perm_enum

typedef enum oc_file_perm_enum
{
    OC_FILE_OTHER_EXEC = 1,
    OC_FILE_OTHER_WRITE = 2,
    OC_FILE_OTHER_READ = 4,
    OC_FILE_GROUP_EXEC = 8,
    OC_FILE_GROUP_WRITE = 16,
    OC_FILE_GROUP_READ = 32,
    OC_FILE_OWNER_EXEC = 64,
    OC_FILE_OWNER_WRITE = 128,
    OC_FILE_OWNER_READ = 256,
    OC_FILE_STICKY_BIT = 512,
    OC_FILE_SET_GID = 1024,
    OC_FILE_SET_UID = 2048
} oc_file_perm_enum;

Enum Constants

  • OC_FILE_OTHER_EXEC
  • OC_FILE_OTHER_WRITE
  • OC_FILE_OTHER_READ
  • OC_FILE_GROUP_EXEC
  • OC_FILE_GROUP_WRITE
  • OC_FILE_GROUP_READ
  • OC_FILE_OWNER_EXEC
  • OC_FILE_OWNER_WRITE
  • OC_FILE_OWNER_READ
  • OC_FILE_STICKY_BIT
  • OC_FILE_SET_GID
  • OC_FILE_SET_UID 

oc_datestamp

typedef struct oc_datestamp
{
    i64 seconds;
    u64 fraction;
} oc_datestamp;


oc_file_status

typedef struct oc_file_status
{
    u64 uid;
    oc_file_type type;
    oc_file_perm perm;
    u64 size;
    oc_datestamp creationDate;
    oc_datestamp accessDate;
    oc_datestamp modificationDate;
} oc_file_status;


oc_file_list

typedef struct oc_file_list
{
    oc_list list;
    u64 eltCount;
} oc_file_list;

An type describing a list of enumerated files in a given directory.

oc_file_listdir_elt

typedef struct oc_file_listdir_elt
{
    oc_list_elt listElt;
    oc_str8 basename;
    oc_file_type type;
} oc_file_listdir_elt;

Functions

oc_io_wait_single_req

oc_io_cmp oc_io_wait_single_req(oc_io_req* req);

Send a single I/O request and wait for its completion.

Parameters

  • req The I/O request to send.

Return

The result of the operation.

oc_file_nil

oc_file oc_file_nil();

Returns a nil file handle

oc_file_is_nil

bool oc_file_is_nil(oc_file handle);

Test if a file handle is nil.

Parameters

  • handle The handle to test.

Return

true if the handle is nil, and false otherwise.

oc_file_open

oc_file oc_file_open(oc_str8 path, oc_file_access rights, oc_file_open_flags flags);

Open a file in the applications' default directory subtree.

Parameters

  • path The path of the file, relative to the applications' default directory.
  • rights The request access rights for the file.
  • flags Flags controlling various options for the open operation. See oc_file_open_flags.

Return

A handle to the opened file.

oc_file_open_at

oc_file oc_file_open_at(oc_file dir, oc_str8 path, oc_file_access rights, oc_file_open_flags flags);

Open a file in a given directory's subtree.

Parameters

  • dir A directory handle identifying the root of the open operation.
  • path The path of the file to open, relative to dir.
  • rights The request access rights for the file.
  • flags Flags controlling various options for the open operation. See oc_file_open_flags.

Return

A handle to the opened file.

oc_file_close

void oc_file_close(oc_file file);

Close a file.

Parameters

  • file The file handle to close.

oc_file_pos

i64 oc_file_pos(oc_file file);

Get the current position in a file.

Parameters

  • file A handle to the file.

Return

The current position in the file.

oc_file_seek

i64 oc_file_seek(oc_file file, i64 offset, oc_file_whence whence);

Set the current position in a file.

Parameters

  • file A handle to the file.
  • offset The offset at which to move the file position, relative to the base position indicated by whence.
  • whence The base position for the seek operation.

Return

The new position in the file, or -1 if an error occurred.

oc_file_write

u64 oc_file_write(oc_file file, u64 size, char* buffer);

Write data to a file.

Parameters

  • file A handle to the file.
  • size The number of bytes to write.
  • buffer The buffer containing the data to write. It must be at least size long.

Return

The number of bytes written. A short count indicates an error.

oc_file_read

u64 oc_file_read(oc_file file, u64 size, char* buffer);

Read from a file.

Parameters

  • file A handle to the file.
  • size The number of bytes to read.
  • buffer The buffer where to store the read data. It must be capable of holding at least size bytes.

Return

The number of bytes read. A short count indicates an error.

oc_file_last_error

oc_io_error oc_file_last_error(oc_file handle);

Get the last error on a file handle.

Parameters

  • handle A handle to a file.

Return

The last error stored on the file handle.

oc_file_get_status

oc_file_status oc_file_get_status(oc_file file);


oc_file_size

u64 oc_file_size(oc_file file);


oc_file_open_with_request

oc_file oc_file_open_with_request(oc_str8 path, oc_file_access rights, oc_file_open_flags flags);


oc_file_listdir

oc_file_list oc_file_listdir(oc_arena* arena, oc_str8 directory);