Cthulhu  0.2.10
Cthulhu compiler collection
io.h
Go to the documentation of this file.
1 // SPDX-License-Identifier: LGPL-3.0-only
2 
3 #pragma once
4 
5 #include <ctu_io_api.h>
6 
7 #include "core/analyze.h"
8 
9 #include "os/core.h"
10 
11 // include the implementation headers when doing analysis
12 // for the size macros
13 #if STA_PRESENT
14 # include "io/impl/buffer.h"
15 # include "io/impl/file.h"
16 # include "io/impl/view.h"
17 #endif
18 
19 #include <stddef.h>
20 #include <stdarg.h>
21 
22 CT_BEGIN_API
23 
26 
27 typedef struct io_t io_t;
28 
34 CT_IO_API os_error_t io_free(STA_RELEASE io_t *io);
35 
44 CT_IO_API os_error_t io_close(INOUT_NOTNULL io_t *io);
45 
53 CT_NODISCARD CT_ALLOC(io_free)
54 CT_IO_API io_t *io_file(IN_STRING const char *path, os_access_t mode, IN_NOTNULL arena_t *arena);
55 
66 CT_NODISCARD CT_ALLOC(io_free)
67 CT_IO_API io_t *io_memory(IN_STRING const char *name, const void *data, size_t size, os_access_t flags, IN_NOTNULL arena_t *arena);
68 
78 CT_NODISCARD CT_ALLOC(io_free)
79 CT_IO_API io_t *io_blob(IN_STRING const char *name, size_t size, os_access_t flags, IN_NOTNULL arena_t *arena);
80 
90 CT_NODISCARD CT_ALLOC(io_free)
91 CT_IO_API io_t *io_view(IN_STRING const char *name, IN_NOTNULL const void *data, size_t size, IN_NOTNULL arena_t *arena);
92 
101 CT_NODISCARD CT_ALLOC(io_free)
102 CT_IO_API io_t *io_string(IN_STRING const char *name, IN_STRING const char *string, IN_NOTNULL arena_t *arena);
103 
117 CT_NODISCARD CT_ALLOC(io_close)
118 CT_IO_API io_t *io_file_init(STA_WRITES(IO_FILE_SIZE) void *buffer, IN_STRING const char *path, os_access_t mode);
119 
136 CT_NODISCARD CT_ALLOC(io_close)
137 CT_IO_API io_t *io_memory_init(STA_WRITES(IO_BUFFER_SIZE) void *buffer, IN_STRING const char *name, const void *data, size_t size, os_access_t flags, IN_NOTNULL arena_t *arena);
138 
154 CT_NODISCARD CT_ALLOC(io_close)
155 CT_IO_API io_t *io_blob_init(STA_WRITES(IO_BUFFER_SIZE) void *buffer, IN_STRING const char *name, size_t size, os_access_t flags, IN_NOTNULL arena_t *arena);
156 
171 CT_NODISCARD CT_ALLOC(io_close)
172 CT_IO_API io_t *io_view_init(STA_WRITES(IO_VIEW_SIZE) void *buffer, IN_STRING const char *name, IN_NOTNULL const void *data, size_t size);
173 
187 CT_NODISCARD CT_ALLOC(io_close)
188 CT_IO_API io_t *io_string_init(STA_WRITES(IO_VIEW_SIZE) void *buffer, IN_STRING const char *name, IN_STRING const char *string);
189 
198 CT_IO_API size_t io_read(IN_NOTNULL io_t *io, STA_WRITES(size) void *dst, size_t size);
199 
208 CT_IO_API size_t io_write(IN_NOTNULL io_t *io, STA_READS(size) const void *src, size_t size);
209 
218 STA_PRINTF(2, 3)
219 CT_IO_API size_t io_printf(IN_NOTNULL io_t *io, STA_FORMAT_STRING const char *fmt, ...);
220 
229 CT_IO_API size_t io_vprintf(IN_NOTNULL io_t *io, IN_STRING const char *fmt, va_list args);
230 
236 CT_NODISCARD
237 CT_IO_API const char *io_name(IN_NOTNULL const io_t *io);
238 
244 CT_NODISCARD
245 CT_IO_API size_t io_size(IN_NOTNULL io_t *io);
246 
253 CT_NODISCARD
254 CT_IO_API size_t io_seek(IN_NOTNULL io_t *io, size_t offset);
255 
267 CT_NODISCARD
268 CT_IO_API void *io_map(IN_NOTNULL io_t *io, os_protect_t protect);
269 
275 CT_NODISCARD RET_INSPECT
276 CT_IO_API os_error_t io_error(IN_NOTNULL const io_t *io);
277 
279 
280 CT_END_API
IO_BUFFER_SIZE
#define IO_BUFFER_SIZE
Definition: buffer.h:29
STA_WRITES
CT_NODISCARD STA_WRITES(size) void *dst
size
CT_NODISCARD size_t size
Definition: scan.h:128
os_protect_t
os_protect_t
file mapping memory protection
Definition: core.h:47
os_access_t
os_access_t
file access mode
Definition: core.h:38
IO_FILE_SIZE
#define IO_FILE_SIZE
Definition: file.h:25
CT_ALLOC
#define CT_ALLOC(...)
mark a function as allocating memory
Definition: analyze.h:244
STA_RELEASE
#define STA_RELEASE
annotate a pointer as invalid after the function returns
CT_NODISCARD
#define CT_NODISCARD
mark a function as returning a value that must be used
STA_PRINTF
#define STA_PRINTF(a, b)
mark a function as a printf style function
Definition: analyze.h:165
IN_NOTNULL
#define IN_NOTNULL
annotate a parameter as not being null
STA_FORMAT_STRING
#define STA_FORMAT_STRING
mark a function parameter as a printf format string
STA_READS
#define STA_READS(size)
annotate a parameter as reading expr elements
RET_INSPECT
#define RET_INSPECT
annotate the return value as needing to be inspected this is the same as CT_NODISCARD but implies tha...
INOUT_NOTNULL
#define INOUT_NOTNULL
Definition: analyze.h:101
IN_STRING
#define IN_STRING
annotate a parameter as being a null terminated string
CT_BEGIN_API
#define CT_BEGIN_API
Definition: compiler.h:129
CT_END_API
#define CT_END_API
Definition: compiler.h:130
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.
io_free
CT_IO_API os_error_t io_free(STA_RELEASE io_t *io)
destroy an IO object and free its memory
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
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.
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
Definition: file.c:125
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.
io_error
CT_NODISCARD CT_IO_API os_error_t io_error(const io_t *io)
get the last error from the io object
Definition: io.c:144
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
Definition: io.c:103
io_vprintf
CT_IO_API size_t io_vprintf(io_t *io, const char *fmt, va_list args)
vprintf to an io object
Definition: io.c:79
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
Definition: view.c:83
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,...
Definition: buffer.c:126
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.
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
Definition: view.c:90
io_close
CT_IO_API os_error_t io_close(INOUT_NOTNULL io_t *io)
destroy an IO object
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
Definition: buffer.c:119
io_size
CT_NODISCARD CT_IO_API size_t io_size(io_t *io)
get the total size of an io objects contents
Definition: io.c:94
io_printf
CT_IO_API size_t io_printf(io_t *io, STA_FORMAT_STRING const char *fmt,...)
printf to an io object
io_name
CT_NODISCARD CT_IO_API const char * io_name(const io_t *io)
get the name of an io object
Definition: io.c:112
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
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.
Definition: io.c:120
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.
fmt
CT_NODISCARD STA_FORMAT_STRING const char * fmt
Definition: str.h:68
arena_t
an allocator object
Definition: arena.h:86
io_t
io object implementation
Definition: impl.h:122
io_t::data
char data[]
user data region
Definition: impl.h:139
io_t::arena
arena_t * arena
the arena this object was allocated from
Definition: impl.h:133
io_t::name
const char * name
the name of this object
Definition: impl.h:136
io_t::flags
os_access_t flags
the access flags for this object
Definition: impl.h:130
IO_VIEW_SIZE
#define IO_VIEW_SIZE
Definition: view.h:26