filesystem.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "rcutils/allocator.h"
#include "rcutils/macros.h"
#include "rcutils/visibility_control.h"

Include dependency graph for filesystem.h:

Go to the source code of this file.

Classes
struct	rcutils_dir_iter_t
	An iterator used for enumerating directory contents. More...

Typedefs
typedef struct rcutils_dir_iter_t	rcutils_dir_iter_t
	An iterator used for enumerating directory contents. More...

Functions
bool	rcutils_get_cwd (char *buffer, size_t max_length)
	Return current working directory. More...
bool	rcutils_is_directory (const char *abs_path)
	Check if the provided path points to a directory. More...
bool	rcutils_is_file (const char *abs_path)
	Check if the provided path points to a file. More...
bool	rcutils_exists (const char *abs_path)
	Check if the provided path points to an existing file/folder. More...
bool	rcutils_is_readable (const char *abs_path)
	Check if the provided path points to a file/folder readable by current user. More...
bool	rcutils_is_writable (const char *abs_path)
	Check if the provided path points to a file/folder writable by current user. More...
bool	rcutils_is_readable_and_writable (const char *abs_path)
	Check if the provided path points to a file/folder both readable and writable by current user. More...
char *	rcutils_join_path (const char *left_hand_path, const char *right_hand_path, rcutils_allocator_t allocator)
	Return newly allocated string with arguments separated by correct delimiter for the platform. More...
char *	rcutils_to_native_path (const char *path, rcutils_allocator_t allocator)
	Return newly allocated string with all argument's "/" replaced by platform specific separator. More...
char *	rcutils_expand_user (const char *path, rcutils_allocator_t allocator)
	Expand user directory in path. More...
bool	rcutils_mkdir (const char *abs_path)
	Create the specified directory. More...
rcutils_ret_t	rcutils_calculate_directory_size (const char *directory_path, uint64_t *size, rcutils_allocator_t allocator)
	Calculate the size of the specified directory. More...
rcutils_ret_t	rcutils_calculate_directory_size_with_recursion (const char *directory_path, const size_t max_depth, uint64_t *size, rcutils_allocator_t allocator)
	Calculate the size of the specified directory with recursion. More...
size_t	rcutils_get_file_size (const char *file_path)
	Calculate the size of the specifed file. More...
rcutils_dir_iter_t *	rcutils_dir_iter_start (const char *directory_path, const rcutils_allocator_t allocator)
	Begin iterating over the contents of the specified directory. More...
bool	rcutils_dir_iter_next (rcutils_dir_iter_t *iter)
	Continue iterating over the contents of a directory. More...
void	rcutils_dir_iter_end (rcutils_dir_iter_t *iter)
	Finish iterating over the contents of a directory. More...

Typedef Documentation

rcutils_dir_iter_t

typedef struct rcutils_dir_iter_t rcutils_dir_iter_t

An iterator used for enumerating directory contents.

Function Documentation

rcutils_get_cwd()

bool rcutils_get_cwd	(	char *	buffer,
		size_t	max_length
	)

Return current working directory.

Parameters

[in]	buffer	Allocated string to store current directory path to
[in]	max_length	maximum length to be stored in buffer

Returns

true if success, or

false if buffer is NULL, or

false on failure.

rcutils_is_directory()

bool rcutils_is_directory

(

const char *

abs_path

)

Check if the provided path points to a directory.

Parameters

[in]

abs_path

Absolute path to check.

Returns

true if provided path is a directory, or

false if abs_path is NULL, or

false on failure.

rcutils_is_file()

bool rcutils_is_file

(

const char *

abs_path

)

Check if the provided path points to a file.

Parameters

[in]

abs_path

Absolute path to check.

Returns

true if provided path is a file, or

false if abs_path is NULL, or

false on failure.

rcutils_exists()

bool rcutils_exists

(

const char *

abs_path

)

Check if the provided path points to an existing file/folder.

Parameters

[in]

abs_path

Absolute path to check.

Returns

true if the path exists, or

false if abs_path is NULL, or

false on failure.

rcutils_is_readable()

bool rcutils_is_readable

(

const char *

abs_path

)

Check if the provided path points to a file/folder readable by current user.

Parameters

[in]

abs_path

Absolute path to check.

Returns

true if the file is readable, or

false if abs_path is NULL, or

false on failure.

rcutils_is_writable()

bool rcutils_is_writable

(

const char *

abs_path

)

Check if the provided path points to a file/folder writable by current user.

Parameters

[in]

abs_path

Absolute path to check.

Returns

true if the file is writable, or

false if abs_path is NULL, or

false on failure.

rcutils_is_readable_and_writable()

bool rcutils_is_readable_and_writable

(

const char *

abs_path

)

Check if the provided path points to a file/folder both readable and writable by current user.

Parameters

[in]

abs_path

Absolute path to check.

Returns

true if the file is readable and writable, or

false if abs_path is NULL

false on failure.

rcutils_join_path()

char* rcutils_join_path	(	const char *	left_hand_path,
		const char *	right_hand_path,
		rcutils_allocator_t	allocator
	)

Return newly allocated string with arguments separated by correct delimiter for the platform.

This function allocates memory and returns it to the caller. It is up to the caller to release the memory once it is done with it by calling deallocate on the same allocator passed here.

Parameters

[in]	left_hand_path
[in]	right_hand_path
[in]	allocator

Returns

concatenated path on success

NULL on invalid arguments

NULL on failure

rcutils_to_native_path()

char* rcutils_to_native_path	(	const char *	path,
		rcutils_allocator_t	allocator
	)

Return newly allocated string with all argument's "/" replaced by platform specific separator.

This function allocates memory and returns it to the caller. It is up to the caller to release the memory once it is done with it by calling deallocate on the same allocator passed here.

Parameters

[in]	path
[in]	allocator

Returns

path using platform specific delimiters on success

NULL on invalid arguments

NULL on failure

rcutils_expand_user()

char* rcutils_expand_user	(	const char *	path,
		rcutils_allocator_t	allocator
	)

Expand user directory in path.

This function expands an initial '~' to the current user's home directory. The home directory is fetched using rcutils_get_home_dir(). This function returns a newly allocated string on success. It is up to the caller to release the memory once it is done with it by calling deallocate on the same allocator passed here.

Parameters

[in]	path	A null-terminated C string representing a path.
[in]	allocator

Returns

path with expanded home directory on success, or

NULL on invalid arguments, or

NULL on failure.

rcutils_mkdir()

bool rcutils_mkdir

(

const char *

abs_path

)

Create the specified directory.

This function creates an absolutely-specified directory. If any of the intermediate directories do not exist, this function will return False. If the abs_path already exists, and is a directory, this function will return true.

This function is not thread-safe due to mkdir races as described in the openat(2) documentation.

Parameters

[in]

abs_path

Returns

true if making the directory was successful, or

false if path is NULL, or

false if path is empty, or

false if path is not absolute, or

false if any intermediate directories don't exist.

rcutils_calculate_directory_size()

rcutils_ret_t rcutils_calculate_directory_size	(	const char *	directory_path,
		uint64_t *	size,
		rcutils_allocator_t	allocator
	)

Calculate the size of the specified directory.

Calculates the size of a directory by summarizing the file size of all files.

Note

This operation is not recursive.

Parameters

[in]	directory_path	The directory path to calculate the size of.
[out]	size	The size of the directory in bytes on success.
[in]	allocator	Allocator being used for internal file path composition.

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or

RCUTILS_RET_BAD_ALLOC if memory allocation fails

RCUTILS_RET_ERROR if other error occurs

rcutils_calculate_directory_size_with_recursion()

rcutils_ret_t rcutils_calculate_directory_size_with_recursion	(	const char *	directory_path,
		const size_t	max_depth,
		uint64_t *	size,
		rcutils_allocator_t	allocator
	)

Calculate the size of the specified directory with recursion.

Calculates the size of a directory and subdirectory by summarizing the file size of all files. If necessary, you can specify the maximum directory depth to recurse into. Depth definition as below.

directory_path  <= depth 1
   |- subdirectory <= depth 2
           |- subdirectory <= depth 3
                   ...

Note

This API does not follow symlinks to files or directories.

Parameters

[in]	directory_path	The directory path to calculate the size of.
[in]	max_depth	The maximum depth of subdirectory. 0 means no limitation.
[out]	size	The size of the directory in bytes on success.
[in]	allocator	Allocator being used for internal file path composition.

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_INVALID_ARGUMENT for invalid arguments, or

RCUTILS_RET_BAD_ALLOC if memory allocation fails

RCUTILS_RET_ERROR if other error occurs

rcutils_get_file_size()

size_t rcutils_get_file_size

(

const char *

file_path

)

Calculate the size of the specifed file.

Parameters

[in]

file_path

The path of the file to obtain its size of.

Returns

The size of the file in bytes.

rcutils_dir_iter_start()

rcutils_dir_iter_t* rcutils_dir_iter_start	(	const char *	directory_path,
		const rcutils_allocator_t	allocator
	)

Begin iterating over the contents of the specified directory.

This function is used to list the files and directories that are contained in a specified directory. The structure returned by it must be deallocated using rcutils_dir_iter_end when the iteration is completed. The name of the enumerated entry is stored in the entry_name member of the returned object, and the first entry is already populated upon completion of this function. To populate the entry with the name of the next entry, use the rcutils_dir_iter_next function. Note that the "." and ".." entries are typically among the entries enumerated.

Parameters

[in]	directory_path	The directory path to iterate over the contents of.
[in]	allocator	Allocator used to create the returned structure.

Returns

An iterator object used to continue iterating directory contents

NULL if an error occurred

rcutils_dir_iter_next()

bool rcutils_dir_iter_next

(

rcutils_dir_iter_t *

iter

)

Continue iterating over the contents of a directory.

Parameters

[in]

iter

An iterator created by rcutils_dir_iter_start.

Returns

true if another entry was found, or

false if there are no more entries in the directory.

rcutils_dir_iter_end()

void rcutils_dir_iter_end

(

rcutils_dir_iter_t *

iter

)

Finish iterating over the contents of a directory.

Parameters

[in]

iter

An iterator created by rcutils_dir_iter_start.