Unified interface over streaming io. More...

Collaboration diagram for IO stream interface:

Modules
	io implementation details
	internal io implementation details

typedef typedefCT_BEGIN_API struct io_t	io_t

CT_IO_API os_error_t	io_free (STA_RELEASE io_t *io)
	destroy an IO object and free its memory More...

CT_IO_API os_error_t	io_close (INOUT_NOTNULL io_t *io)
	destroy an IO object More...

CT_NODISCARD CT_IO_API io_t *	io_file (const char path, os_access_t mode, arena_t arena)
	create an IO object from a file More...

CT_NODISCARD CT_IO_API io_t *	io_memory (const char name, const void data, size_t size, os_access_t flags, arena_t *arena)
	create an IO object from an initial view of memory More...

CT_NODISCARD CT_IO_API io_t *	io_blob (const char name, size_t size, os_access_t flags, arena_t arena)
	create an IO object in memory of a given size `size` specifies the initial internal buffer size, the file seek position starts at 0 More...

CT_NODISCARD CT_IO_API io_t *	io_view (const char name, const void data, size_t size, arena_t *arena)
	create a readonly IO object for a given view of memory More...

CT_NODISCARD CT_IO_API io_t *	io_string (const char name, const char string, arena_t *arena)
	create an IO view of a string create a readonly IO view of a string More...

CT_NODISCARD CT_IO_API io_t *	io_file_init (STA_WRITES(IO_FILE_SIZE) void buffer, const char path, os_access_t mode)
	create an io object from a file initializes an io object using a preallocated buffer. More...

CT_NODISCARD CT_IO_API io_t *	io_memory_init (STA_WRITES(IO_BUFFER_SIZE) void buffer, const char name, const void data, size_t size, os_access_t flags, arena_t arena)
	create an io object from a memory buffer initializes an io object using a preallocated buffer. More...

CT_NODISCARD CT_IO_API io_t *	io_blob_init (STA_WRITES(IO_BUFFER_SIZE) void buffer, const char name, size_t size, os_access_t flags, arena_t *arena)
	create an io object from a memory buffer initializes an io object using a preallocated buffer. More...

CT_NODISCARD CT_IO_API io_t *	io_view_init (STA_WRITES(IO_VIEW_SIZE) void buffer, const char name, const void *data, size_t size)
	create an io object from a memory buffer initializes an io object using a preallocated buffer. More...

CT_NODISCARD CT_IO_API io_t *	io_string_init (STA_WRITES(IO_VIEW_SIZE) void buffer, const char name, const char *string)
	create an io object from a memory buffer initializes an io object using a preallocated buffer. More...

CT_IO_API size_t	io_read (io_t io, STA_WRITES(size) void dst, size_t size)
	read from an io object More...

CT_IO_API size_t	io_write (io_t io, STA_READS(size) const void src, size_t size)
	write to an io object More...

CT_IO_API size_t	io_printf (io_t io, STA_FORMAT_STRING const char fmt,...)
	printf to an io object More...

CT_IO_API size_t	io_vprintf (io_t io, const char fmt, va_list args)
	vprintf to an io object More...

CT_NODISCARD CT_IO_API const char *	io_name (const io_t *io)
	get the name of an io object More...

CT_NODISCARD CT_IO_API size_t	io_size (io_t *io)
	get the total size of an io objects contents More...

CT_NODISCARD CT_IO_API size_t	io_seek (io_t *io, size_t offset)
	seek to an absolute offset in a file More...

CT_NODISCARD CT_IO_API void *	io_map (io_t *io, os_protect_t protect)
	map an io object into memory maps an io objects entire contents into memory. More...

CT_NODISCARD CT_IO_API os_error_t	io_error (const io_t *io)
	get the last error from the io object More...

CT_IO_API io_t *	io_stdout (void)
	get the global stdout IO object More...

CT_IO_API io_t *	io_stderr (void)
	get the global stderr IO object More...

Detailed Description

Unified interface over streaming io.

Typedef Documentation

◆ io_t

typedef typedefCT_BEGIN_API struct io_t io_t

Definition at line 22 of file io.h.

Function Documentation

◆ io_blob()

CT_NODISCARD CT_IO_API io_t* io_blob	(	const char *	name,
		size_t	size,
		os_access_t	flags,
		arena_t *	arena
	)

create an IO object in memory of a given size size specifies the initial internal buffer size, the file seek position starts at 0

Parameters

name	the name of the io object
size	the starting size of the buffer
flags	the access mode
arena	the arena to allocate from

Returns: the io object

Definition at line 126 of file buffer.c.

◆ io_blob_init()

CT_NODISCARD CT_IO_API io_t* io_blob_init	(	STA_WRITES(IO_BUFFER_SIZE) void *	buffer,
		const char *	name,
		size_t	size,
		os_access_t	flags,
		arena_t *	arena
	)

create an io object from a memory buffer initializes an io object using a preallocated buffer.

Note: the buffer must be available for the lifetime of the io object. ending the lifetime of the buffer before the io object will result in undefined behavior.

Precondition: buffer must be at least IO_MEMORY_SIZE bytes large; buffer must be aligned to alignof(io_t)

Parameters

buffer	the buffer to use for the io object
name	the name of the io object
size	the starting size of the buffer
flags	the access mode
arena	the arena to allocate from

Returns: the initialized io object

◆ io_close()

CT_IO_API os_error_t io_close ( INOUT_NOTNULL io_t * io )

destroy an IO object

Warning: this does not free the memory of the object itself This should only be used when the io object is allocated on the stack and initialized with an io_*_init function.

Parameters

io	the io object

Returns: an error code if the object could not be destroyed

◆ io_error()

CT_NODISCARD CT_IO_API os_error_t io_error ( const io_t * io )

get the last error from the io object

Parameters

io	the io object

Returns: the last set error

Definition at line 144 of file io.c.

◆ io_file()

CT_NODISCARD CT_IO_API io_t* io_file	(	const char *	path,
		os_access_t	mode,
		arena_t *	arena
	)

create an IO object from a file

Parameters

path	the path to the file
mode	the access mode of the file
arena	the arena to allocate from

Returns: the io object, or NULL on error

public allocating api

Definition at line 125 of file file.c.

◆ io_file_init()

CT_NODISCARD CT_IO_API io_t* io_file_init	(	STA_WRITES(IO_FILE_SIZE) void *	buffer,
		const char *	path,
		os_access_t	mode
	)

create an io object from a file initializes an io object using a preallocated buffer.

Note: the buffer must be available for the lifetime of the io object. ending the lifetime of the buffer before the io object will result in undefined behavior.

Precondition: buffer must be at least IO_FILE_SIZE bytes large; buffer must be aligned to alignof(io_t)

Parameters

buffer	the buffer to use for the io object
path	the path to the file
mode	the access mode of the file

Returns: the initialized io object

◆ io_free()

CT_IO_API os_error_t io_free ( STA_RELEASE io_t * io )

destroy an IO object and free its memory

Parameters

io	the io object

Returns: an error code if the io object could not be closed

◆ io_map()

CT_NODISCARD CT_IO_API void* io_map	(	io_t *	io,
		os_protect_t	protect
	)

map an io object into memory maps an io objects entire contents into memory.

Warning: while the return value is a mutable pointer, the writability of the memory is determined by protect as well as the access mode the io object was created with.

Parameters

io	the io object to map from
protect	the protection level of the memory

Returns: memory mapping to the contents

Definition at line 120 of file io.c.

◆ io_memory()

CT_NODISCARD CT_IO_API io_t* io_memory	(	const char *	name,
		const void *	data,
		size_t	size,
		os_access_t	flags,
		arena_t *	arena
	)

create an IO object from an initial view of memory

Note: this copies size bytes from data into a new buffer

Parameters

name	the name of the io block
data	the data to copy into the initial buffer
size	the size of the data
flags	the access mode of the file
arena	the arena to allocate from

Returns: the io object

public allocating api

Definition at line 119 of file buffer.c.

◆ io_memory_init()

CT_NODISCARD CT_IO_API io_t* io_memory_init	(	STA_WRITES(IO_BUFFER_SIZE) void *	buffer,
		const char *	name,
		const void *	data,
		size_t	size,
		os_access_t	flags,
		arena_t *	arena
	)

create an io object from a memory buffer initializes an io object using a preallocated buffer.

Note: the buffer must be available for the lifetime of the io object. ending the lifetime of the buffer before the io object will result in undefined behavior.

Precondition: buffer must be at least IO_MEMORY_SIZE bytes large; buffer must be aligned to alignof(io_t)

Parameters

buffer	the buffer to use for the io object
name	the name of the io block
data	the data to copy into the initial buffer
size	the size of the data
flags	the access mode of the file
arena	the arena to allocate from

Returns: the initialized io object

◆ io_name()

CT_NODISCARD CT_IO_API const char* io_name ( const io_t * io )

get the name of an io object

Parameters

io	the io object

Returns: the name of the object

Definition at line 112 of file io.c.

◆ io_printf()

CT_IO_API size_t io_printf	(	io_t *	io,
		STA_FORMAT_STRING const char *	fmt,
			...
	)

printf to an io object

Precondition: the io object must have been created with the eOsAccessWrite flag

Parameters

io	the io object
fmt	the format string
...	the format arguments

Returns: the number of bytes actually written

◆ io_read()

CT_IO_API size_t io_read	(	io_t *	io,
		STA_WRITES(size) void *	dst,
		size_t	size
	)

read from an io object

Precondition: the io object must have been created with the eOsAccessRead flag

Parameters

io	the io object
dst	the dst buffer to read into
size	the number of bytes to read

Returns: the number of bytes actually read

◆ io_seek()

CT_NODISCARD CT_IO_API size_t io_seek	(	io_t *	io,
		size_t	offset
	)

seek to an absolute offset in a file

Parameters

io	the io object
offset	the offset to seek to

Returns: the offset after seeking

Definition at line 103 of file io.c.

◆ io_size()

CT_NODISCARD CT_IO_API size_t io_size ( io_t * io )

get the total size of an io objects contents

Parameters

io	the io object

Returns: the total size in bytes of its contents

Definition at line 94 of file io.c.

◆ io_stderr()

CT_IO_API io_t* io_stderr ( void )

get the global stderr IO object

Returns: the global stderr IO object

Definition at line 65 of file console.c.

◆ io_stdout()

CT_IO_API io_t* io_stdout ( void )

get the global stdout IO object

Returns: the global stdout IO object

Definition at line 60 of file console.c.

◆ io_string()

CT_NODISCARD CT_IO_API io_t* io_string	(	const char *	name,
		const char *	string,
		arena_t *	arena
	)

create an IO view of a string create a readonly IO view of a string

Parameters

name	the name of the IO view
string	the backing string view
arena	the arena to allocate from

Returns: the io object

Definition at line 90 of file view.c.

◆ io_string_init()

CT_NODISCARD CT_IO_API io_t* io_string_init	(	STA_WRITES(IO_VIEW_SIZE) void *	buffer,
		const char *	name,
		const char *	string
	)

create an io object from a memory buffer initializes an io object using a preallocated buffer.

Note: the buffer must be available for the lifetime of the io object. ending the lifetime of the buffer before the io object will result in undefined behavior.

Precondition: buffer must be at least IO_VIEW_SIZE bytes large; buffer must be aligned to alignof(io_t)

Parameters

buffer	the buffer to use for the io object
name	the name of the IO view
string	the backing string view

Returns: the initialized io object

◆ io_view()

CT_NODISCARD CT_IO_API io_t* io_view	(	const char *	name,
		const void *	data,
		size_t	size,
		arena_t *	arena
	)

create a readonly IO object for a given view of memory

Precondition: data must point to a valid memory region of size bytes

Parameters

name	the name of the IO view
data	the data to provide in the view
size	the size of the data
arena	the arena to allocate from

Returns: the IO view

public allocating api

Definition at line 83 of file view.c.

◆ io_view_init()

CT_NODISCARD CT_IO_API io_t* io_view_init	(	STA_WRITES(IO_VIEW_SIZE) void *	buffer,
		const char *	name,
		const void *	data,
		size_t	size
	)

create an io object from a memory buffer initializes an io object using a preallocated buffer.

Note: the buffer must be available for the lifetime of the io object. ending the lifetime of the buffer before the io object will result in undefined behavior.

Precondition: buffer must be at least IO_VIEW_SIZE bytes large; buffer must be aligned to alignof(io_t)

Parameters

buffer	the buffer to use for the io object
name	the name of the IO view
data	the data to provide in the view
size	the size of the data

Returns: the initialized io object

◆ io_vprintf()

CT_IO_API size_t io_vprintf	(	io_t *	io,
		const char *	fmt,
		va_list	args
	)

vprintf to an io object

Precondition: the io object must have been created with the eOsAccessWrite flag

Parameters

io	the io object
fmt	the format string
args	the format arguments

Returns: the number of bytes actually written

Definition at line 79 of file io.c.

◆ io_write()

CT_IO_API size_t io_write	(	io_t *	io,
		STA_READS(size) const void *	src,
		size_t	size
	)

write to an io object

Precondition: the io object must have been created with the eOsAccessWrite flag

Parameters

io	the io object
src	the source buffer to copy from
size	the number of bytes to copy into the file

Returns: the number of bytes actually written

Modules

Detailed Description

Typedef Documentation

◆ io_t

Function Documentation

◆ io_blob()

◆ io_blob_init()

◆ io_close()

◆ io_error()

◆ io_file()

◆ io_file_init()

◆ io_free()

◆ io_map()

◆ io_memory()

◆ io_memory_init()

◆ io_name()

◆ io_printf()

◆ io_read()

◆ io_seek()

◆ io_size()

◆ io_stderr()

◆ io_stdout()

◆ io_string()

◆ io_string_init()

◆ io_view()

◆ io_view_init()

◆ io_vprintf()

◆ io_write()