Contains helpers to deal with files. More...

Macros
#define	SOL_UTIL_MAX_READ_ATTEMPTS 10
	Max number of read attempts. More...

Typedefs
typedef struct sol_file_reader	sol_file_reader
	Opaque handler for a file reader. More...

Enumerations
enum	sol_util_iterate_dir_reason { SOL_UTIL_ITERATE_DIR_STOP = 0, SOL_UTIL_ITERATE_DIR_CONTINUE = 1 }
	Return values (for non-error paths) expected from sol_util_iterate_dir() callbacks. More...

Functions
void	sol_file_reader_close (struct sol_file_reader *fr)
	Closes a file reader, releasing its memory. More...

struct sol_file_reader *	sol_file_reader_from_fd (int fd)
	Create a file reader from a file descriptor. More...

struct sol_str_slice	sol_file_reader_get_all (const struct sol_file_reader *fr)
	Get the content of the file as a sol_str_slice. More...

const struct stat *	sol_file_reader_get_stat (const struct sol_file_reader *fr)
	Retrieve stat information from a file. More...

struct sol_file_reader *	sol_file_reader_open (const char *filename)
	Open a file using its filename. More...

struct sol_blob *	sol_file_reader_to_blob (struct sol_file_reader *fr)
	convert an open file reader to a blob. More...

bool	sol_util_busy_wait_file (const char *path, uint64_t nanoseconds)
	Wait for some file to become available. More...

int	sol_util_create_recursive_dirs (const struct sol_str_slice path, mode_t mode)
	Create directories recursively. More...

int	sol_util_fd_set_flag (int fd, int flag)
	Set a flag into a file descriptor. More...

int	sol_util_file_encode_filename (struct sol_buffer *buf, const struct sol_str_slice value)
	Encode string to be used as a file name. More...

struct sol_str_slice	sol_util_file_get_basename (struct sol_str_slice path)
	Get the basename of a path. More...

ssize_t	sol_util_fill_buffer (int fd, struct sol_buffer *buffer, size_t size)
	Fills buffer with data read from file fd. More...

static int	sol_util_fill_buffer_exactly (int fd, struct sol_buffer *buffer, size_t size)
	Fills buffer with data read from file fd with an exact amount of bytes. More...

int	sol_util_get_rootdir (char *out, size_t size)
	Gets the root directory. More...

int	sol_util_get_user_config_dir (struct sol_buffer *buffer)
	Get the user context config directory for current app. More...

int	sol_util_iterate_dir (const char path, enum sol_util_iterate_dir_reason(iterate_dir_cb)(void data, const char dir_path, struct dirent ent), const void data)
	Iterate over a directory. More...

int	sol_util_load_file_buffer (const char filename, struct sol_buffer buf)
	Reads the contents of a file and append to a buffer. More...

int	sol_util_load_file_fd_buffer (int fd, struct sol_buffer *buf)
	Reads the contents of a file and append to a buffer. More...

int int struct sol_buffer *	sol_util_load_file_fd_raw (int fd)
	Reads the contents of a file. More...

char *	sol_util_load_file_fd_string (int fd, size_t *size)
	Reads the contents of a file. More...

char *	sol_util_load_file_string (const char filename, size_t size)
	Reads the contents of a file. More...

int	sol_util_move_file (const char old_path, const char new_path, mode_t mode)
	Moves file on filesystem. More...

int	sol_util_read_file (const char path, const char fmt,...) SOL_ATTR_SCANF(2
	Reads from a file the contents according with the formatted string. More...

int int	sol_util_vread_file (const char path, const char fmt, va_list args) SOL_ATTR_SCANF(2
	Reads from a file the contents according with the formatted string. More...

int int	sol_util_vwrite_file (const char path, const char fmt, va_list args) SOL_ATTR_PRINTF(2
	Write the formatted string in the file pointed by path. More...

int	sol_util_write_file (const char path, const char fmt,...) SOL_ATTR_PRINTF(2
	Write the formatted string in the file pointed by path. More...

int int ssize_t	sol_util_write_file_slice (const char *path, struct sol_str_slice slice)
	Write the slice content the file pointed by path. More...

Detailed Description

Contains helpers to deal with files.

Macro Definition Documentation

#define SOL_UTIL_MAX_READ_ATTEMPTS 10

Max number of read attempts.

It's used when a read operation returns EAGAIN or EINTR.

Typedef Documentation

sol_file_reader

Opaque handler for a file reader.

Enumeration Type Documentation

enum sol_util_iterate_dir_reason

Return values (for non-error paths) expected from sol_util_iterate_dir() callbacks.

They flag that function whether to continue or to stop looping on directory entries.

Enumerator
SOL_UTIL_ITERATE_DIR_STOP	The directory iteration should stop.
SOL_UTIL_ITERATE_DIR_CONTINUE	The directory iteration should continue.

Function Documentation

void sol_file_reader_close ( struct sol_file_reader * fr )

Closes a file reader, releasing its memory.

Parameters

fr	A pointer to the file reader to be closed.

struct sol_file_reader* sol_file_reader_from_fd ( int fd )

Create a file reader from a file descriptor.

Parameters

fd	The file descriptor.

Returns: A file reader to read contents from fd on success or NULL on errors.

struct sol_str_slice sol_file_reader_get_all ( const struct sol_file_reader * fr )

Get the content of the file as a sol_str_slice.

Parameters

fr	The file reader object.

Returns: a sol_str_slice containing all contents of the file. Slice will be empty if file reader is NULL or invalid.

const struct stat* sol_file_reader_get_stat ( const struct sol_file_reader * fr )

Retrieve stat information from a file.

Parameters

fr	The file reader object.

Returns: A pointer to the stat structure containing stat information on success or NULL on errors.

struct sol_file_reader* sol_file_reader_open ( const char * filename )

Open a file using its filename.

Parameters

filename The file name of the file to open.

Returns: The file reader associated with the file on success or NULL on errors.

Examples:: /src/samples/crypto/message-digest.c, and /src/samples/crypto/sha256sum.c.

Referenced by hash_file(), and startup().

struct sol_blob* sol_file_reader_to_blob ( struct sol_file_reader * fr )

convert an open file reader to a blob.

This will convert a valid and opened file reader to a blob, thus no further explicit calls to sol_file_reader_close() should be done as the blob will automatically close once its last reference is gone.

Parameters

fr	valid opened file reader.

Returns: NULL on error (and fr is closed) or new blob instance that should be sol_blob_unref() once it's not needed.

Examples:: /src/samples/crypto/message-digest.c, and /src/samples/crypto/sha256sum.c.

Referenced by hash_file(), and startup().

bool sol_util_busy_wait_file	(	const char *	path,
		uint64_t	nanoseconds
	)

Wait for some file to become available.

When dealing with sysfs, it's really common to perform an action that will create new files on sysfs. This function helps those who need to wait for some of these files.

Parameters

path	where to look for the file
nanoseconds	how much time to wait

Returns: true if file come to existence before nanoseconds. false if wait ended after timeout

Note: This function blocks current thread on a busy wait. Use with caution.

int sol_util_create_recursive_dirs	(	const struct sol_str_slice	path,
		mode_t	mode
	)

Create directories recursively.

Parameters

path	The path of the directory to be created.
mode	The mode of the directory as specified by stat function.

Returns: 0 on success or a negative error code on errors.

int sol_util_fd_set_flag	(	int	fd,
		int	flag
	)

Set a flag into a file descriptor.

Parameters

fd	A valid file descriptor.
flag	The desired flag.

Returns: 0 on success, otherwise a negative value with the error.

Examples:: /src/samples/http/server-sse.c, and /src/samples/http/server.c.

Referenced by startup_server().

int sol_util_file_encode_filename	(	struct sol_buffer *	buf,
		const struct sol_str_slice	value
	)

Encode string to be used as a file name.

Encode all non alphanumerical character to '\xXX', where XX is the character hexcode.

Parameters

buf	An initialized buffer to append the encoded filename.
value	The string to be encoded.

Returns: 0 on success or a negative error code on errors.

struct sol_str_slice sol_util_file_get_basename ( struct sol_str_slice path )

Get the basename of a path.

Get basename of file. It doesn't modify content of the string.

Parameters

path	A path to get the basename.

Returns: A pointer to a portion of the original string containing the basename of the path. Return will be an empty string if path is empty.

ssize_t sol_util_fill_buffer	(	int	fd,
		struct sol_buffer *	buffer,
		size_t	size
	)

Fills buffer with data read from file fd.

Data read will be appended to the end of used buffer (i.e. buffer->used). If one wants data to be inserted at beginning of buffer, then one must call sol_buffer_reset() on buffer before calling sol_util_fill_buffer().

By using this function to fill the buffer, one doesn't need to care about EAGAIN or EINTR being returned by read() raw call.

Parameters

fd	A valid file descriptor.
buffer	The buffer that will hold the file's content.
size	Read up to this amount of bytes.

Returns: The size of bytes filled in success, otherwise a negative error indicating what failure happened. Note that the amount of bytes may be smaller than the requested.

See Also: sol_util_fill_buffer_exactly()

Referenced by sol_util_fill_buffer_exactly().

static int sol_util_fill_buffer_exactly	(	int	fd,
		struct sol_buffer *	buffer,
		size_t	size
	)

inlinestatic

Fills buffer with data read from file fd with an exact amount of bytes.

Data read will be appended to the end of used buffer (i.e. buffer->used). If one wants data to be inserted at beginning of buffer, then one must call sol_buffer_reset() on buffer before calling sol_util_fill_buffer_exactly()

By using this function to fill the buffer, one doesn't need to care about EAGAIN or EINTR being returned by read() raw call.

This is a convenience function that calls sol_util_fill_buffer() and check if the read amount is exactly the given size, otherwise considers a failure.

Parameters

fd	A valid file descriptor.
buffer	The buffer that will hold the file's content.
size	Read exactly this amount of bytes.

Returns: 0 on success, -EIO if the number of bytes read is smaller than size or -errno on errrors.

See Also: sol_util_fill_buffer()

References sol_util_fill_buffer().

int sol_util_get_rootdir	(	char *	out,
		size_t	size
	)

Gets the root directory.

Parameters

out	A variable to hold the root directory.
size	The out's size

Returns: 0 on success, otherwise a negative value with the error.

Examples:: /src/samples/flow/c-api/find-type.c.

Referenced by show_module_types().

int sol_util_get_user_config_dir ( struct sol_buffer * buffer )

Get the user context config directory for current app.

Parameters

buffer The buffer where the user config dir will be written.

Returns: 0 on success or a negative error code on errors.

int sol_util_iterate_dir	(	const char *	path,
		enum sol_util_iterate_dir_reason()(void data, const char dir_path, struct dirent ent)	iterate_dir_cb,
		const void *	data
	)

Iterate over a directory.

Parameters

path	A valid path.
iterate_dir_cb	The callback issued for each directory entry found. Return a negative error to stop the iteration with an error, SOL_UTIL_ITERATE_DIR_CONTINUE to continue the iteration or SOL_UTIL_ITERATE_DIR_STOP to stop it.
data	The user data to be passed in the callback.

Returns: 0 on success or negative error, otherwise.

Note: "." and ".." will be excluded from the iteration.

See Also: SOL_UTIL_ITERATE_DIR_CONTINUE; SOL_UTIL_ITERATE_DIR_STOP

int sol_util_load_file_buffer	(	const char *	filename,
		struct sol_buffer *	buf
	)

Reads the contents of a file and append to a buffer.

Parameters

filename	THe file path to be read.
buf	A buffer to append the file contents - It must be initialized.

Returns: 0 on success, negative errno otherwise.

int sol_util_load_file_fd_buffer	(	int	fd,
		struct sol_buffer *	buf
	)

Reads the contents of a file and append to a buffer.

Parameters

fd	A valid file descriptor.
buf	A buffer to append the file contents - It must be initialized.

Returns: 0 on success, negative errno otherwise.

Examples:: /src/samples/http/server-sse.c, and /src/samples/http/server.c.

Referenced by on_stdin().

int int struct sol_buffer* sol_util_load_file_fd_raw ( int fd )

Reads the contents of a file.

The data read is put not formatted in a buffer.

Note: It's the caller responsibility to release the buffer's memory.

Parameters

fd	A valid file descriptor.

Returns: A buffer with the data read in success, otherwise NULL.

See Also: sol_util_load_file_string

char* sol_util_load_file_fd_string	(	int	fd,
		size_t *	size
	)

Reads the contents of a file.

Note: It's the caller responsibility to release the memory.

Parameters

fd	A valid file descriptor.
size	A variable to hold the amount of read data.

Returns: A string with the file's content on success, otherwise NULL.

See Also: sol_util_load_file_string

char* sol_util_load_file_string	(	const char *	filename,
		size_t *	size
	)

Reads the contents of a file.

Note: It's the caller responsibility to release the memory.

Parameters

filename	A file's path.
size	A variable to hold the amount of read data.

Returns: A string with the file's content on success, otherwise NULL.

See Also: sol_util_load_file_fd_string

int sol_util_move_file	(	const char *	old_path,
		const char *	new_path,
		mode_t	mode
	)

Moves file on filesystem.

This function shall move file from old_path to new_path, and it only returns success if ensures that file was written to storage, using fsync(3)

Parameters

old_path	path of file to be moved
new_path	to where move file
mode	mode that should be applied to new_file

Returns: On success 0. On failure, a negative error indicating what failure happened.

Note: This function may take time to complete its task, thus blocking the mainloop. You may want to use a thread or idler to call it.

int sol_util_read_file	(	const char *	path,
		const char *	fmt,
			...
	)

Reads from a file the contents according with the formatted string.

Parameters

path	The path to a valid file.
fmt	The string format.

Returns: The number of read characters, if an error is encountered a negative value with the error.

See Also: sol_util_vread_file

Examples:: /src/samples/common/linux-micro-init.c.

Referenced by parse_kcmdline_pin().

int int sol_util_vread_file	(	const char *	path,
		const char *	fmt,
		va_list	args
	)

Reads from a file the contents according with the formatted string.

It is equivalent to sol_util_read_file except it receives va_list instead of a variable number of arguments.

Parameters

path	The path to a valid file.
fmt	The string format.
args	The format arguments.

Returns: The number of read characters, if an error is encountered a negative value with the error.

See Also: sol_util_vread_file

int int sol_util_vwrite_file	(	const char *	path,
		const char *	fmt,
		va_list	args
	)

Write the formatted string in the file pointed by path.

It is equivalent to sol_util_write_file() except it receives va_list instead of a variable number of arguments.

Parameters

path	The path to a valid file.
fmt	The string format
args	The format arguments.

Returns: The number of written characters, if an error is encountered a negative value with the error.

See Also: sol_util_write_file

int sol_util_write_file	(	const char *	path,
		const char *	fmt,
			...
	)

Write the formatted string in the file pointed by path.

Parameters

path	The path to a valid file.
fmt	The string format.

Returns: The number of written characters, if an error is encountered a negative value with the error.

See Also: sol_util_vwrite_file

int int ssize_t sol_util_write_file_slice	(	const char *	path,
		struct sol_str_slice	slice
	)

Write the slice content the file pointed by path.

Parameters

path	The path to a valid file.
slice	The slice to be written.

Returns: The number of written characters, if an error is encountered a negative value with the error code.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation