File API

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 = 2,
    OC_FILE_OPEN_TRUNCATE = 4,
    OC_FILE_OPEN_CREATE = 8,
    OC_FILE_OPEN_SYMLINK = 16,
    OC_FILE_OPEN_NO_FOLLOW = 32,
    OC_FILE_OPEN_RESTRICT = 64
} 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 = 2,
    OC_FILE_ACCESS_WRITE = 4
} 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;

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);