System IO header. More...

Collaboration diagram for System IO:

Detailed Description

System IO header.

The sys/io.h header handles interaction with PatchworkOS's file system, following the philosophy that everything is a file. This means interacting with physical devices, inter-process communication (like shared memory), and much more is handled via files.

Flags

Functions like open() do not have a specific argument for flags, instead the filepath itself contains the flags. This means that for example there is no need for a special "truncate" redirect in a shell (>>) instead you can just add the "trunc" flag to the filepath and use a normal redirect (>).

Here is an example filepath: /this/is/a/path:with:some:flags.

Check the 'src/kernel/fs/path.h' file for a list of available flags.

Data Structures
struct	pollfd_t
	Poll file descriptor structure. More...

struct	stat_t
	Stat type. More...

struct	dirent_t
	Directory entry struct. More...

struct	key_t
	Key type. More...

Macros
#define	STDIN_FILENO 0

#define	STDOUT_FILENO 1

#define	STDERR_FILENO 2

#define	PIPE_READ 0
	Pipe read end.

#define	PIPE_WRITE 1
	Pipe write end.

#define	F_MAX_SIZE 512
	Maximum buffer size for the `F()` macro.

#define	F(format, ...)
	Format string macro.

#define	POLL_SPECIAL (POLLERR \| POLLHUP \| POLLNVAL)
	Poll event values that will always be checked and included even if not specified.

#define	KEY_SIZE 16
	Size of keys in bytes.

Typedefs
typedef uint8_t	seek_origin_t
	Type for the `seek()` origin argument.

typedef uint64_t	inode_number_t
	Inode number enum.

Enumerations
enum	poll_events_t { POLLNONE = 0 , POLLIN = (1 << 0) , POLLOUT = (1 << 1) , POLLERR = (1 << 2) , POLLHUP = (1 << 3) , POLLNVAL = (1 << 4) }
	Poll events type. More...

enum	inode_type_t { INODE_FILE , INODE_DIR }
	Inode type enum. More...

enum	mount_flags_t { MOUNT_NONE = 0 , MOUNT_PROPAGATE_PARENT = 1 << 0 , MOUNT_PROPAGATE_CHILDREN = 1 << 1 , MOUNT_OVERWRITE = 1 << 2 }
	Mount flags type. More...

Functions
fd_t	open (const char *path)
	System call for opening files.

uint64_t	open2 (const char *path, fd_t fd[2])
	System call for opening 2 file descriptors from one file.

fd_t	openat (fd_t from, const char *path)
	System call for opening files relative to another file descriptor.

uint64_t	close (fd_t fd)
	System call for closing files.

uint64_t	read (fd_t fd, void *buffer, uint64_t count)
	System call for reading from files.

char *	sread (fd_t fd)
	Wrapper for reading a file directly into a null-terminated string.

uint64_t	write (fd_t fd, const void *buffer, uint64_t count)
	System call for writing to files.

uint64_t	swrite (fd_t fd, const char *string)
	Wrapper for writing a null-terminated string to a file.

uint64_t	readfile (const char path, void buffer, uint64_t count, uint64_t offset)
	Wrapper for reading a file directly using a path.

char *	sreadfile (const char *path)
	Wrapper for reading an entire file directly into a null-terminated string.

uint64_t	writefile (const char path, const void buffer, uint64_t count, uint64_t offset)
	Wrapper for writing to a file directly using a path.

uint64_t	swritefile (const char path, const char string)
	Wrapper for writing a null-terminated string directly to a file using a path.

uint64_t	seek (fd_t fd, int64_t offset, seek_origin_t origin)
	System call for changing the file offset.

uint64_t	chdir (const char *path)
	System call for changing the cwd.

uint64_t	poll (pollfd_t *fds, uint64_t amount, clock_t timeout)
	System call for polling files.

poll_events_t	poll1 (fd_t fd, poll_events_t events, clock_t timeout)
	Wrapper for polling one file.

uint64_t	stat (const char path, stat_t stat)
	System call for retrieving info about a file or directory.

uint64_t	ioctl (fd_t fd, uint64_t request, void *argp, uint64_t size)
	System call for extended driver behaviour.

fd_t	dup (fd_t oldFd)
	System call for duplicating file descriptors.

fd_t	dup2 (fd_t oldFd, fd_t newFd)
	System call for duplicating file descriptors, with a destination.

uint64_t	getdents (fd_t fd, dirent_t *buffer, uint64_t count)
	System call for reading directory entires.

uint64_t	mkdir (const char *path)
	Wrapper for creating a directory.

uint64_t	rmdir (const char *path)
	Wrapper for removing a directory.

uint64_t	link (const char oldPath, const char newPath)
	System call for creating a hardlink.

uint64_t	unlink (const char *path)
	Wrapper for removing a file.

uint64_t	share (key_t *key, fd_t fd, clock_t timeout)
	System call for sharing a file descriptor with another process.

fd_t	claim (key_t *key)
	System call for claiming a shared file descriptor.

uint64_t	bind (fd_t source, const char *mountpoint, mount_flags_t flags)
	System call for binding a file descriptor to a mountpoint.

Macro Definition Documentation

◆ STDIN_FILENO

#define STDIN_FILENO 0

Definition at line 46 of file io.h.

◆ STDOUT_FILENO

#define STDOUT_FILENO 1

Definition at line 47 of file io.h.

◆ STDERR_FILENO

#define STDERR_FILENO 2

Definition at line 48 of file io.h.

◆ PIPE_READ

#define PIPE_READ 0

Pipe read end.

The PIPE_READ constant defines which file descriptor in fd from a open2 call on the /dev/pipe file will be the read end of the pipe.

Definition at line 57 of file io.h.

◆ PIPE_WRITE

#define PIPE_WRITE 1

Pipe write end.

The PIPE_WRITE constant defines which file descriptor in fd from a open2 call on the /dev/pipe file will be the write end of the pipe.

Definition at line 65 of file io.h.

◆ F_MAX_SIZE

#define F_MAX_SIZE 512

Maximum buffer size for the F() macro.

Definition at line 70 of file io.h.

◆ F

#define F	(	format,
		...
	)

Value:

    ({ \
        char* _buffer = alloca(F_MAX_SIZE); \
        int _len = snprintf(_buffer, F_MAX_SIZE, format, __VA_ARGS__); \
        assert(_len >= 0 && "F() formatting error"); \
        _buffer; \
    })

Format string macro.

This macro is a helper to create formatted strings on the stack. Very useful for functions like open().

Note: This could be reimplemented using thread local storage to avoid using alloca(), but we then end up needing to set a maximum limit for how many F() strings can be used simultaneously. Using alloca() means we can use as many as we want, as long as we have enough stack space, even if it is more dangerous.

Warning: Will truncate the string if it exceeds F_MAX_SIZE.

Definition at line 83 of file io.h.

◆ POLL_SPECIAL

#define POLL_SPECIAL (POLLERR | POLLHUP | POLLNVAL)

Poll event values that will always be checked and included even if not specified.

Definition at line 269 of file io.h.

◆ KEY_SIZE

#define KEY_SIZE 16

Size of keys in bytes.

Definition at line 446 of file io.h.

Typedef Documentation

◆ seek_origin_t

typedef uint8_t seek_origin_t

Type for the seek() origin argument.

Definition at line 231 of file io.h.

◆ inode_number_t

typedef uint64_t inode_number_t

Inode number enum.

Definition at line 322 of file io.h.

Enumeration Type Documentation

◆ poll_events_t

enum poll_events_t

Poll events type.

Enumerator
POLLNONE	None.
POLLIN	File descriptor is ready to read.
POLLOUT	File descriptor is ready to write.
POLLERR	File descriptor caused an error.
POLLHUP	Stream socket peer closed connection, or shut down writing of connection.
POLLNVAL	Invalid file descriptor.

Definition at line 256 of file io.h.

◆ inode_type_t

enum inode_type_t

Inode type enum.

Enumerator
INODE_FILE	Is a file.
INODE_DIR	Is a directory.

Definition at line 312 of file io.h.

◆ mount_flags_t

enum mount_flags_t

Mount flags type.

The propagation flags apply recursively, such that specifying both MOUNT_PROPAGATE_PARENT and MOUNT_PROPAGATE_CHILDREN will propagate the mount to every namespace in the hierarchy.

Enumerator
MOUNT_NONE	No special mount flags.
MOUNT_PROPAGATE_PARENT	Propagate the mount to parent namespaces.
MOUNT_PROPAGATE_CHILDREN	Propagate the mount to child namespaces.
MOUNT_OVERWRITE	Overwrite any existing mount at the mountpoint.

Definition at line 487 of file io.h.

Function Documentation

◆ open()

fd_t open ( const char * path )

System call for opening files.

The open() function opens a file located at a given path.

Parameters

path	The path to the desired file.

Returns: On success, the file descriptor, on failure returns ERR and errno is set.

Definition at line 9 of file open.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ open2()

uint64_t open2	(	const char *	path,
		fd_t	fd[2]
	)

System call for opening 2 file descriptors from one file.

This is intended as a more generic implementation of system calls like pipe() in for example Linux. One example use case of this system call is pipes, if open2 is called on /dev/pipe then fd[0] will store the read end of the pipe and fd[1] will store the write end of the pipe. But if open() is called on /dev/pipe then the returned file descriptor would be both ends.

Parameters

path	The path to the desired file.
fd	An array of two `fd_t` where the new file descriptors will be stored.

Returns: On success, 0, on failure returns ERR and errno is set.

Definition at line 9 of file open2.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ openat()

fd_t openat	(	fd_t	from,
		const char *	path
	)

System call for opening files relative to another file descriptor.

Parameters

from	The file descriptor to open the file relative to, or `FD_NONE` to open from the current working directory.
path	The path to the desired file.

Returns: On success, the file descriptor, on failure returns ERR and errno is set.

◆ close()

uint64_t close ( fd_t fd )

System call for closing files.

Parameters

fd	The file descriptor to close.

Returns: On success, 0, on failure returns ERR and errno is set.

Definition at line 9 of file close.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ read()

uint64_t read	(	fd_t	fd,
		void *	buffer,
		uint64_t	count
	)

System call for reading from files.

Parameters

fd	The file descriptor to read from.
buffer	A pointer to the buffer where the data will be stored.
count	The maximum number of bytes to read.

Returns: On success, the number of bytes read. On end-of-file, 0. On failure, ERR and errno is set.

Definition at line 9 of file read.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sread()

char * sread ( fd_t fd )

Wrapper for reading a file directly into a null-terminated string.

The sread() function reads the entire contents of a file into a newly allocated null-terminated string. The caller is responsible for freeing the returned string.

Parameters

fd	The file descriptor to read from.

Returns: On success, a pointer to the null-terminated string. On failure, NULL and errno is set.

Definition at line 5 of file sread.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ write()

uint64_t write	(	fd_t	fd,
		const void *	buffer,
		uint64_t	count
	)

System call for writing to files.

Parameters

fd	The file descriptor to write to.
buffer	A pointer to the buffer containing the data to write.
count	The number of bytes to write.

Returns: On success, the number of bytes written. On failure, ERR and errno is set.

Definition at line 9 of file write.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swrite()

uint64_t swrite	(	fd_t	fd,
		const char *	string
	)

Wrapper for writing a null-terminated string to a file.

Parameters

fd	The file descriptor to write to.
string	The null-terminated string to write.

Returns: On success, the number of bytes written. On failure, ERR and errno is set.

Definition at line 4 of file swrite.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readfile()

uint64_t readfile	(	const char *	path,
		void *	buffer,
		uint64_t	count,
		uint64_t	offset
	)

Wrapper for reading a file directly using a path.

Equivalent to calling open(), seek(), read(), and close() in sequence.

Parameters

path	The path to the file.
buffer	A pointer to the buffer where the data will be stored.
count	The maximum number of bytes to read.
offset	The offset in the file to start reading from.

Returns: On success, the number of bytes read. On end-of-file, 0. On failure, ERR and errno is set.

Definition at line 3 of file readfile.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sreadfile()

char * sreadfile ( const char * path )

Wrapper for reading an entire file directly into a null-terminated string.

The sreadfile() function reads the entire contents of a file into a newly allocated null-terminated string. The caller is responsible for freeing the returned string.

Equivalent to calling open(), sread(), and close() in sequence.

Parameters

path	The path to the file.

Returns: On success, a pointer to the null-terminated string. On failure, NULL and errno is set.

Definition at line 3 of file sreadfile.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ writefile()

uint64_t writefile	(	const char *	path,
		const void *	buffer,
		uint64_t	count,
		uint64_t	offset
	)

Wrapper for writing to a file directly using a path.

Equivalent to calling open(), seek(), write(), and close() in sequence.

Parameters

path	The path to the file.
buffer	A pointer to the buffer containing the data to write.
count	The number of bytes to write.
offset	The offset in the file to start writing to.

Returns: On success, the number of bytes written. On failure, ERR and errno is set.

Definition at line 3 of file writefile.c.

Here is the call graph for this function:

◆ swritefile()

uint64_t swritefile	(	const char *	path,
		const char *	string
	)

Wrapper for writing a null-terminated string directly to a file using a path.

Equivalent to calling open(), swrite(), and close() in sequence.

Parameters

path	The path to the file.
string	The null-terminated string to write.

Returns: On success, the number of bytes written. On failure, ERR and errno is set.

Definition at line 4 of file swritefile.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ seek()

uint64_t seek	(	fd_t	fd,
		int64_t	offset,
		seek_origin_t	origin
	)

System call for changing the file offset.

Parameters

fd	The file descriptor.
offset	The offset to move the file pointer.
origin	The origin that the offset is relative to (e.g., `SEEK_SET`, `SEEK_CUR`, `SEEK_END`).

Returns: On success, the new offset from the beginning of the file. On failure, ERR and errno is set.

Definition at line 9 of file seek.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ chdir()

uint64_t chdir ( const char * path )

System call for changing the cwd.

Parameters

path	The path to the new directory.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 9 of file chdir.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ poll()

uint64_t poll	(	pollfd_t *	fds,
		uint64_t	amount,
		clock_t	timeout
	)

System call for polling files.

Parameters

fds	An array of `pollfd_t` structures, each specifying a file descriptor to poll in pollfd_t::fd and the events to wait for in pollfd_t::events.
amount	The number of `pollfd_t` structures in the `fds` array.
timeout	The maximum time (in clock ticks) to wait for an event. If `CLOCKS_NEVER`, it waits forever.

Returns: On success, the number of file descriptors for which the events occurred. On timeout, 0. On failure, ERR and errno is set.

Definition at line 9 of file poll.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ poll1()

poll_events_t poll1	(	fd_t	fd,
		poll_events_t	events,
		clock_t	timeout
	)

Wrapper for polling one file.

The poll1() function waits for events on a single file descriptor. Otherwise it is identical to poll() and exists simply for convenience.

Parameters

fd	The file descriptor to poll.
events	The events to wait for (e.g., `POLLIN`, `POLLOUT`).
timeout	The maximum time (in clock ticks) to wait for an event. If `CLOCKS_NEVER`, it waits forever.

Returns: On success, the events that occurred. On timeout, 0. On failure, the POLLERR event bit is set and errno is set.

Definition at line 9 of file poll1.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ stat()

uint64_t stat	(	const char *	path,
		stat_t *	stat
	)

System call for retrieving info about a file or directory.

Parameters

path	The path to the file or directory.
stat	A pointer to a `stat_t` structure where the file information will be stored.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 9 of file stat.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ioctl()

uint64_t ioctl	(	fd_t	fd,
		uint64_t	request,
		void *	argp,
		uint64_t	size
	)

System call for extended driver behaviour.

The ioctl() function allows drivers to implement unusual behaviour that would be impossible or impractical with a normal file-based API.

Parameters

fd	The file descriptor of the file.
request	The driver-dependent request code.
argp	A pointer to an argument that depends on the request, can be `NULL` if size is 0.
size	The size of the argument pointed to by `argp`.

Returns: On success, the return value depends on the driver but is usually 0. On failure, ERR and errno is set.

Definition at line 9 of file ioctl.c.

Here is the call graph for this function:

◆ dup()

fd_t dup ( fd_t oldFd )

System call for duplicating file descriptors.

Parameters

oldFd The open file descriptor to duplicate.

Returns: On success, the new file descriptor. On failure, ERR and errno is set.

Definition at line 9 of file dup.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dup2()

fd_t dup2	(	fd_t	oldFd,
		fd_t	newFd
	)

System call for duplicating file descriptors, with a destination.

Parameters

oldFd	The open file descriptor to duplicate.
newFd	The desired new file descriptor.

Returns: On success, the new file descriptor. On failure, ERR and errno is set.

Definition at line 9 of file dup2.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getdents()

uint64_t getdents	(	fd_t	fd,
		dirent_t *	buffer,
		uint64_t	count
	)

System call for reading directory entires.

Parameters

fd	The file descriptor of the directory to read.
buffer	The destination buffer.
count	The size of the buffer in bytes.

Returns: On success, the total number of bytes written to the buffer. On failure, returns ERR and errno is set.

Definition at line 9 of file getdents.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mkdir()

uint64_t mkdir ( const char * path )

Wrapper for creating a directory.

Parameters

path	The path of the directory to create.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 10 of file mkdir.c.

Here is the call graph for this function:

◆ rmdir()

uint64_t rmdir ( const char * path )

Wrapper for removing a directory.

Parameters

path	The path of the directory to remove.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 6 of file rmdir.c.

Here is the call graph for this function:

◆ link()

uint64_t link	(	const char *	oldPath,
		const char *	newPath
	)

System call for creating a hardlink.

Parameters

oldPath
newPath

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 9 of file link.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ unlink()

uint64_t unlink ( const char * path )

Wrapper for removing a file.

Parameters

path	The path of the file to remove.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 5 of file unlink.c.

Here is the call graph for this function:

◆ share()

uint64_t share	(	key_t *	key,
		fd_t	fd,
		clock_t	timeout
	)

System call for sharing a file descriptor with another process.

Note that the file descriptor itself is not whats sent but the underlying file object.

Parameters

key	Output pointer to store the generated key.
fd	The file descriptor to share.
timeout	The time until the shared file descriptor expires. If `CLOCKS_NEVER`, it never expires.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 6 of file share.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ claim()

fd_t claim ( key_t * key )

System call for claiming a shared file descriptor.

After claiming a shared file descriptor, the key is no longer valid and cannot be used again.

Parameters

key	Pointer to the key identifying the shared file descriptor.

Returns: On success, the claimed file descriptor. On failure, ERR and errno is set.

Definition at line 6 of file claim.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ bind()

uint64_t bind	(	fd_t	source,
		const char *	mountpoint,
		mount_flags_t	flags
	)

System call for binding a file descriptor to a mountpoint.

Parameters

source	The file descriptor to bind, must represent a directory.
mountpoint	The mountpoint path.
flags	The mount flags.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 5 of file bind.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Detailed Description

Flags

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ STDIN_FILENO

◆ STDOUT_FILENO

◆ STDERR_FILENO

◆ PIPE_READ

◆ PIPE_WRITE

◆ F_MAX_SIZE

◆ F

◆ POLL_SPECIAL

◆ KEY_SIZE

Typedef Documentation

◆ seek_origin_t

◆ inode_number_t

Enumeration Type Documentation

◆ poll_events_t

◆ inode_type_t

◆ mount_flags_t

Function Documentation

◆ open()

◆ open2()

◆ openat()

◆ close()

◆ read()

◆ sread()

◆ write()

◆ swrite()

◆ readfile()

◆ sreadfile()

◆ writefile()

◆ swritefile()

◆ seek()

◆ chdir()

◆ poll()

◆ poll1()

◆ stat()

◆ ioctl()

◆ dup()

◆ dup2()

◆ getdents()

◆ mkdir()

◆ rmdir()

◆ link()

◆ unlink()

◆ share()

◆ claim()

◆ bind()