This section contains abstracted file system and I/O utilities. More...

Macros
#define	RU_WALK_FOLDER_FIRST 0x1

#define	RU_WALK_FOLDER_LAST 0x2

#define	RU_WALK_NO_RECURSE 0x4

#define	RU_WALK_NO_SELF 0x8

#define	RU_WALK_UNIX_SLASHES 0x10

Typedefs
typedef struct stat	ruStat_t

typedef bool(*	entryFilter) (trans_chars folderPath, trans_chars fileName, bool isFolder, ptr ctx)
	A function that is called with each entry of a ruFolderWalk to decide whether that entry should be processed or not. More...

typedef int32_t(*	entryMgr) (trans_chars fullPath, bool isFolder, ptr ctx)
	A function that is called with each entry of a ruFolderWalk. More...

Functions
RUAPI bool	ruFileExists (trans_chars filename)

RUAPI bool	ruIsFile (trans_chars filename)

RUAPI bool	ruIsDir (trans_chars filename)

RUAPI bool	ruIsExecutable (trans_chars filename)

RUAPI bool	ruIsSymlink (trans_chars filename)

RUAPI int32_t	ruDiskFree (trans_chars path, uint64_t total, uint64_t avail)

RUAPI int32_t	ruStat (trans_chars filepath, ruStat_t *dest)

RUAPI rusize	ruFileSize (trans_chars filePath, int32_t *code)
	Return the size of the given file if it exists. More...

RUAPI sec_t	ruFileUtcTime (trans_chars filePath, int32_t *code)
	Return the UTC modification date of the given file if it exists. More...

RUAPI int32_t	ruFileSetUtcTime (trans_chars filePath, sec_t date)
	Set UTC access and mod time of given filePath to given date. More...

RUAPI int	ruOpen (trans_chars filepath, int flags, int mode, int32_t *code)

RUAPI FILE *	ruFOpen (trans_chars filepath, trans_chars mode, int32_t *code)

RUAPI int	ruOpenTmp (char pathTemplate, int flags, int mode, int32_t code)

RUAPI rusize_s	ruWrite (int oh, trans_ptr contents, rusize length)

RUAPI int32_t	ruFileSetContents (trans_chars filename, trans_chars contents, rusize length)

RUAPI int	ruFileGetContents (trans_chars filename, alloc_chars contents, rusize length)

RUAPI int	ruFileCopy (trans_chars srcpath, trans_chars destpath)
	Copies srcpath to destpath. More...

RUAPI int	ruFileRename (trans_chars oldName, trans_chars newName)

RUAPI int	ruFileTryRename (trans_chars oldName, trans_chars newName)
	Renames a given file like ruFileRename, but fails when newName already exists instead of overwriting it. More...

RUAPI int	ruFileRemove (trans_chars filename)

RUAPI int32_t	ruFilteredFolderWalk (trans_chars folder, uint32_t flags, entryFilter filter, entryMgr actor, ptr ctx)
	Like ruFolderWalk with additional filtering capability. Folder entries . and .. are not passed to filter. More...

RUAPI int32_t	ruFolderWalk (trans_chars folder, uint32_t flags, entryMgr actor, ptr ctx)
	Decends into given folder depth first and calls actor on each entry. Folder entries . and .. are not passed to actor. More...

RUAPI ru_int	ruFolderEntries (trans_chars folder)
	Returns the number of folder entries including itself. More...

RUAPI int32_t	ruFolderRemove (trans_chars folder)
	Recursively delete given folder and all it's sub contents. If given path is a file or symlink, it will also be removed. More...

RUAPI int32_t	ruMkdir (trans_chars pathname, int mode, bool deep)

RUAPI alloc_chars	ruDirName (trans_chars filePath)
	Returns the dirname part of a full path without the trailing slash. More...

RUAPI perm_chars	ruBaseName (perm_chars filePath)
	Returns the filename of a path with the preceding path removed. More...

RUAPI perm_chars	ruFileExtension (perm_chars filePath)
	Returns the extension part of the given file name if there is one. More...

RUAPI alloc_chars	ruFullPath (trans_chars filePath)
	Returns an absolute filepath leading to the given relative path. More...

RUAPI alloc_chars	ruPathJoinNative (trans_chars base, trans_chars file)
	Returns base and file joined with the filesystem slash in a new string. More...

RUAPI alloc_chars	ruPathJoin (trans_chars base, trans_chars file)
	Returns base and file joined with the a unix filesystem slash in a new string. More...

RUAPI alloc_chars	ruPathMultiJoin (int parts,...)
	Return a path by concatenating the given parts number of parameters using a unix style directory slash. More...

RUAPI alloc_chars	ruPathMultiJoinNative (int parts,...)
	Return a path by concatenating the given parts number of parameters using the platform native directory slash. More...

Detailed Description

This section contains abstracted file system and I/O utilities.

Macro Definition Documentation

◆ RU_WALK_FOLDER_FIRST

#define RU_WALK_FOLDER_FIRST 0x1

Used by ruFolderWalk to specify that the folder be handled before its contents.

◆ RU_WALK_FOLDER_LAST

#define RU_WALK_FOLDER_LAST 0x2

Used by ruFolderWalk to specify that the folder be handled after its contents.

◆ RU_WALK_NO_RECURSE

#define RU_WALK_NO_RECURSE 0x4

Used by ruFolderWalk to specify whether to not recurse into subfolders.

◆ RU_WALK_NO_SELF

#define RU_WALK_NO_SELF 0x8

Used by ruFolderWalk to specify not to process the top level folder.

◆ RU_WALK_UNIX_SLASHES

#define RU_WALK_UNIX_SLASHES 0x10

Used by ruFolderWalk to specify passing paths with unix style directory slashes to the callbacks. Ignored on Unix platforms.

Typedef Documentation

◆ entryFilter

typedef bool(* entryFilter) (trans_chars folderPath, trans_chars fileName, bool isFolder, ptr ctx)

A function that is called with each entry of a ruFolderWalk to decide whether that entry should be processed or not.

Parameters

folderPath	The full file path to the folder under which fileName resides. Must be copied to persist. Folder may or may not contain a trailing slash.
fileName	The file base name of the current entry. Must be copied to persist.
isFolder	whether this is a folder.
ctx	a user definable context.

Returns: true to filter the entry or false to continue processing it and its potential sub foilders.

◆ entryMgr

typedef int32_t(* entryMgr) (trans_chars fullPath, bool isFolder, ptr ctx)

A function that is called with each entry of a ruFolderWalk.

Parameters

fullPath	The full file path to the entry in question. Must be copied to persist. Folder may or may not contain a trailing slash.
isFolder	whether this is a folder.
ctx	a user definable context.

Returns: RUE_OK to continue, else a regify error code.

◆ ruStat_t

typedef struct stat ruStat_t

An abstracted version of struct stat.

Function Documentation

◆ ruBaseName()

RUAPI perm_chars ruBaseName ( perm_chars filePath )

Returns the filename of a path with the preceding path removed.

Parameters

filePath File path to return the basename of.

Returns: Returns the start of the basename within the given filePath so do not free this reference and copy it as needed.

◆ ruDirName()

RUAPI alloc_chars ruDirName ( trans_chars filePath )

Returns the dirname part of a full path without the trailing slash.

Parameters

filePath File path to return the dirname of.

Returns: Returns the directory name part of the given path excluding its trailing slash or NULL if no slashes were found. Caller needs to free the result with ruFree after use.

◆ ruDiskFree()

RUAPI int32_t ruDiskFree	(	trans_chars	path,
		uint64_t *	total,
		uint64_t *	avail
	)

Returns the total and avail size of the partition where path resides on.

Parameters

path	Path whose partition to examine.
total	Optional, Where total partition size will be stored in bytes
avail	Optional, Where left over user partition size will be stored in bytes.

Returns: RUE_OK on success else RUE_CANT_OPEN_FILE. Then check errno for details.

◆ ruFileCopy()

RUAPI int ruFileCopy	(	trans_chars	srcpath,
		trans_chars	destpath
	)

Copies srcpath to destpath.

Parameters

srcpath	file to copy
destpath	path to copy srcpath to

Returns: Return code of the operation or RUE_OK on success.

◆ ruFileExists()

RUAPI bool ruFileExists ( trans_chars filename )

Checks whether a file or folder exists.

Parameters

filename Name of file, folder or other filesystem entity.

Returns: Return true if the path exists else false.

◆ ruFileExtension()

RUAPI perm_chars ruFileExtension ( perm_chars filePath )

Returns the extension part of the given file name if there is one.

Parameters

filePath File path to get extension from

Returns: NULL if there's no extension otherwise pointer to where it starts in filePath.

◆ ruFileGetContents()

RUAPI int ruFileGetContents	(	trans_chars	filename,
		alloc_chars *	contents,
		rusize *	length
	)

Reads the contents out of the given filepath into the variable and sets the length.

Parameters

filename	Path to the file to read.
contents	Where to store the read content. Caller must use ruFree when done with it.
length	Number of bytes in contents.

Returns: Return code of the operation or RUE_OK on success.

◆ ruFileRemove()

RUAPI int ruFileRemove ( trans_chars filename )

Delete a given file or empty folder.

Parameters

filename File or folder to delete.

Returns: Return code of the operation or RUE_OK on success.

◆ ruFileRename()

RUAPI int ruFileRename	(	trans_chars	oldName,
		trans_chars	newName
	)

Renames a given file. This is equivalent to moving a file. Any previous file at the destination will be overwritten.

Parameters

oldName	Old file path.
newName	The new file path.

Returns: Return code of the operation or RUE_OK on success.

◆ ruFileSetContents()

RUAPI int32_t ruFileSetContents	(	trans_chars	filename,
		trans_chars	contents,
		rusize	length
	)

Write the string stored in contents into a new file at filename. Any old file at that location will be overwritten by the new file.

Parameters

filename	Path to the file to create.
contents	Contents to write into the file. This may be a NULL terminated encoding irrelevant string or binary data. If contents is NULL an empty file will be created.
length	Length of the content. May be RU_SIZE_AUTO for a NULL terminated string.

Returns: Return code of the operation or RUE_OK on success.

◆ ruFileSetUtcTime()

RUAPI int32_t ruFileSetUtcTime	(	trans_chars	filePath,
		sec_t	date
	)

Set UTC access and mod time of given filePath to given date.

Parameters

filePath	file to set time on
date	UTC time stamp to set file time to

Returns: Parameter validation error or RUE_OK if parameters are good.

◆ ruFileSize()

RUAPI rusize ruFileSize	(	trans_chars	filePath,
		int32_t *	code
	)

Return the size of the given file if it exists.

Parameters

filePath	File path to get size of
code	Where the status of the operation will be stored. RUE_OK on success else RUE_PARAMETER_NOT_SET if filename was NULL or RUE_FILE_NOT_FOUND if file didn't exists or RUE_CANT_OPEN_FILE if it was another error. Check errno for details.

Returns: file size or 0 on error

◆ ruFileTryRename()

RUAPI int ruFileTryRename	(	trans_chars	oldName,
		trans_chars	newName
	)

Renames a given file like ruFileRename, but fails when newName already exists instead of overwriting it.

Parameters

oldName	Old file path.
newName	The new file path.

Returns: Return code of the operation or RUE_OK on success.

◆ ruFileUtcTime()

RUAPI sec_t ruFileUtcTime	(	trans_chars	filePath,
		int32_t *	code
	)

Return the UTC modification date of the given file if it exists.

Parameters

filePath	File path to get date of
code	Where the status of the operation will be stored. RUE_OK on success else RUE_PARAMETER_NOT_SET if filename was NULL or RUE_FILE_NOT_FOUND if file didn't exists or RUE_CANT_OPEN_FILE if it was another error. Check errno for details.

Returns: UTC modification date or 0 on error

◆ ruFilteredFolderWalk()

RUAPI int32_t ruFilteredFolderWalk	(	trans_chars	folder,
		uint32_t	flags,
		entryFilter	filter,
		entryMgr	actor,
		ptr	ctx
	)

Like ruFolderWalk with additional filtering capability. Folder entries . and .. are not passed to filter.

Parameters

folder	Folder to start descending into. Does not accept / or \
flags	Flags of type RU_WALK_* to specify walking behavior. All flags may be specified.
filter	Function to call with each entry to decide filtering
actor	Function to call with each entry
ctx	a user definable context to be passed to the entryFilter and entryMgr functions.

Returns

◆ ruFolderEntries()

RUAPI ru_int ruFolderEntries ( trans_chars folder )

Returns the number of folder entries including itself.

Parameters

folder Folder to count entries of

Returns: 0 if folder is not readable, 1 if folder is empty or the number of entries it has - 1 for itself.

◆ ruFolderRemove()

RUAPI int32_t ruFolderRemove ( trans_chars folder )

Recursively delete given folder and all it's sub contents. If given path is a file or symlink, it will also be removed.

Parameters

folder Name of folder to delete. May not be "", "/" or "\\"

Returns: RUE_OK on success else and error call ruLastError on RUE_GENERAL for details.

◆ ruFolderWalk()

RUAPI int32_t ruFolderWalk	(	trans_chars	folder,
		uint32_t	flags,
		entryMgr	actor,
		ptr	ctx
	)

Decends into given folder depth first and calls actor on each entry. Folder entries . and .. are not passed to actor.

Parameters

folder	Folder to start descending into. Does not accept / or \
flags	Flags of type RU_WALK_* to specify walking behavior. All flags may be specified.
actor	Function to call with each entry
ctx	a user definable context to be passed to the entryMgr function.

Returns

◆ ruFOpen()

RUAPI FILE* ruFOpen	(	trans_chars	filepath,
		trans_chars	mode,
		int32_t *	code
	)

Abstracted version of the Posix fopen call.

Parameters

filepath	Path to the file to open
mode	File access mode such as r, r+, w, w+, a or a+.
code	Parameter validation error or RUE_OK if parameters are good.

Returns: A valid file handle or -1 in case of error. Then check errno.

◆ ruFullPath()

RUAPI alloc_chars ruFullPath ( trans_chars filePath )

Returns an absolute filepath leading to the given relative path.

This function merely appends the given path to CWD if it's relative. It does not validate or process the given path in any other way.

Parameters

filePath File path to append the current working directory to if it is relative.

Returns: Returns an absolute filepath leading to the given relative path or the given path if it was absolute. Path must be freed by the caller.

◆ ruIsDir()

RUAPI bool ruIsDir ( trans_chars filename )

Returns true if the given path exists and is a folder. On Unix if the underlying path is a symlink it is dereferenced and the status of the target is returned.

Parameters

filename File path to test

Returns: Returns true if it is a folder.

◆ ruIsExecutable()

RUAPI bool ruIsExecutable ( trans_chars filename )

Returns true if the given path exists and is executable. On Unix if the underlying path is a symlink it is dereferenced and the status of the target is returned. On Unix the file permissions are test for -x. On Windows the file extension is check for .com, .cmd, .bat, .exe and whatever extension is set in the PATHEXT environment variable.

Parameters

filename File path to test

Returns: Returns true if it is executable.

◆ ruIsFile()

RUAPI bool ruIsFile ( trans_chars filename )

Returns true if the given path exists and is a regular file. On Unix if the underlying path is a symlink it is dereferenced and the status of the target is returned.

Parameters

filename File path to test

Returns: Returns true if it is a regular file.

◆ ruIsSymlink()

RUAPI bool ruIsSymlink ( trans_chars filename )

Returns true if the given path exists and is a symbolic link (Unix only).

Parameters

filename File path to test

Returns: Returns true if it is a symlink.

◆ ruMkdir()

RUAPI int32_t ruMkdir	(	trans_chars	pathname,
		int	mode,
		bool	deep
	)

Creates the requested folder with the requested permissions.

Parameters

pathname	Folder to create
mode	Permissions to set (Unix only).
deep	Whether to create any upper level folders.

Returns: RUE_OK on success, else a regify error code.

◆ ruOpen()

RUAPI int ruOpen	(	trans_chars	filepath,
		int	flags,
		int	mode,
		int32_t *	code
	)

Abstracted version of the Posix open call.

Parameters

filepath	Path to the file to open
flags	File access flags such as O_RDONLY, O_WRONLY or O_RDWR.
mode	Desired file permissions if this file is to be created. Ignored on Windows.
code	Parameter validation error or RUE_OK if parameters are good.

Returns: A valid file handle or -1 in case of error. Then check errno.

◆ ruOpenTmp()

RUAPI int ruOpenTmp	(	char *	pathTemplate,
		int	flags,
		int	mode,
		int32_t *	code
	)

Creates and returns the file handle to a new temporary file.

Parameters

pathTemplate	The filepath to where the file should be written. The folders where the file is to be created must already exist and be writable, and the pattern ^^^ will be replaced by random unique characters between a-z. The pathTemplate variable is actually modified and will point to the path corresponding to the returned file handle.
flags	File access flags such as O_RDONLY, O_WRONLY or O_RDWR.
mode	Desired file permissions if this file is to be created. Ignored on Windows.
code	Parameter validation error or RUE_OK if parameters are good.

Returns: A valid file handle or -1 in case of error. Then check errno.

◆ ruPathJoin()

RUAPI alloc_chars ruPathJoin	(	trans_chars	base,
		trans_chars	file
	)

Returns base and file joined with the a unix filesystem slash in a new string.

Parameters

base	folder with or without trailing slash
file	file anme to append

Returns: Returns a new filepath to be freed by the caller after use.

◆ ruPathJoinNative()

RUAPI alloc_chars ruPathJoinNative	(	trans_chars	base,
		trans_chars	file
	)

Returns base and file joined with the filesystem slash in a new string.

Parameters

base	folder with or without trailing slash
file	file anme to append

Returns: Returns a new filepath to be freed by the caller after use.

◆ ruPathMultiJoin()

RUAPI alloc_chars ruPathMultiJoin	(	int	parts,
			...
	)

Return a path by concatenating the given parts number of parameters using a unix style directory slash.

The returned path will have the leading slash supplied with the first folder argument. There will be no trailing slash returned.

Parameters

parts	Number of folder name that follow
...	parts number of folder names to concatenate. Trailing slashes and leading slashes after the second folder are accounted for.

Returns: Allocated path to be freed by the caller. Or NULL if parts was < 1.

◆ ruPathMultiJoinNative()

RUAPI alloc_chars ruPathMultiJoinNative	(	int	parts,
			...
	)

Return a path by concatenating the given parts number of parameters using the platform native directory slash.

The returned path will have the leading slash supplied with the first folder argument. There will be no trailing slash returned.

Parameters

parts	Number of folder name that follow
...	parts number of folder names to concatenate. Trailing slashes and leading slashes after the second folder are accounted for.

Returns: Allocated path to be freed by the caller. Or NULL if parts was < 1.

◆ ruStat()

RUAPI int32_t ruStat	(	trans_chars	filepath,
		ruStat_t *	dest
	)

Populates the given ruStat_t with the data of the filepath if it exists.

Parameters

filepath	File path to test
dest	Pointer to ruStat_t to populate.

Returns: Returns RUE_OK on success else RUE_PARAMETER_NOT_SET if filename was NULL or RUE_FILE_NOT_FOUND if file didn't exists or RUE_CANT_OPEN_FILE if it was another error. Check errno or call ruLastError for details.

◆ ruWrite()

RUAPI rusize_s ruWrite	(	int	oh,
		trans_ptr	contents,
		rusize	length
	)

Abstracted version of the standard write function.

Parameters

oh	A handle returned by ruOpenTmp or ruOpen
contents	buffer to write
length	number of bytes to write

Returns: number of bytes written or < 0 on error then check errno

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ RU_WALK_FOLDER_FIRST

◆ RU_WALK_FOLDER_LAST

◆ RU_WALK_NO_RECURSE

◆ RU_WALK_NO_SELF

◆ RU_WALK_UNIX_SLASHES

Typedef Documentation

◆ entryFilter

◆ entryMgr

◆ ruStat_t

Function Documentation

◆ ruBaseName()

◆ ruDirName()

◆ ruDiskFree()

◆ ruFileCopy()

◆ ruFileExists()

◆ ruFileExtension()

◆ ruFileGetContents()

◆ ruFileRemove()

◆ ruFileRename()

◆ ruFileSetContents()

◆ ruFileSetUtcTime()

◆ ruFileSize()

◆ ruFileTryRename()

◆ ruFileUtcTime()

◆ ruFilteredFolderWalk()

◆ ruFolderEntries()

◆ ruFolderRemove()

◆ ruFolderWalk()

◆ ruFOpen()

◆ ruFullPath()

◆ ruIsDir()

◆ ruIsExecutable()

◆ ruIsFile()

◆ ruIsSymlink()

◆ ruMkdir()

◆ ruOpen()

◆ ruOpenTmp()

◆ ruPathJoin()

◆ ruPathJoinNative()

◆ ruPathMultiJoin()

◆ ruPathMultiJoinNative()

◆ ruStat()

◆ ruWrite()