file_functions.h File Reference

File functions. More...

#include <string.h>
#include <stdbool.h>
#include <limits.h>
#include <glib.h>
#include "str_functions.h"

Go to the source code of this file.

Defines

#define DIRECTORY_SEPARATOR   '/'

DIRECTORY_SEPARATOR is the separator for splits the directories in paths.

#define PATH_SEPARATOR   ':'

PATH_SEPARATOR is the separator for splits the paths in configuration files or environment variables.

File access mode

Access modes of a file or directory.
This is similar to F_OK, R_OK, W_OK, X_OK in unistd.h. However, as F_OK == 0, which is not very helpful when cooperates with other modes.

#define FILE_MODE_NO_SYMLINK   1<<5

Test whether the file is not symbol link.

#define FILE_MODE_EXIST   1<<4

Test for existence.

#define FILE_MODE_DIRECTORY   1<<3

Test whether the 'file' is directory.

#define FILE_MODE_READ   1<<2

Test for read permission.

#define FILE_MODE_WRITE   1<<1

Test for write permission.

#define FILE_MODE_EXECUTE   1

Test for execute permission.

Typedefs

typedef TaskStatus(* ChooseFilenameFunc )(gchar *filename_buf, guint filename_len, StringList *extensions, guint access_mode_mask, const gchar *prompt, gpointer option)

Prototype of callback function for choosing a filename.

Enumerations

enum TaskStatus { TASK_RUNNING, TASK_CANCELED, TASK_FAILED, TASK_COMPLETED }

An enumeration of task running status. More...

Functions

gboolean isReadable (const gchar *filename)

Whether the file is readable.

gboolean isWritable (const gchar *filename)

Whether the file is writable.

gboolean filename_meets_accessMode (const gchar *filename, guint access_mode_mask)

Whether the file meets the given access mode mask.

gchar * filename_search_paths (const gchar *filename, const gchar *search_paths)

Find a file from the search path.

gchar * filename_search_paths_mode (const gchar *filename, const gchar *search_paths, guint access_mode_mask)

Find a file with specified access mode from the search path.

gchar * filename_choose (const gchar *filename_default, guint filename_len, StringList *extensions, guint access_mode_mask, const gchar *prompt, gpointer option, ChooseFilenameFunc callback)

Choose a suitable filename if default one is not.

StringList * lsDir (const gchar *dir, const gchar *globStr, guint access_mode_mask, gboolean keepPath)

List files which meet the given pattern and access modes in a directory.

StringList * lsDir_append (StringList *sList, const gchar *dir, const gchar *globStr, guint access_mode_mask, gboolean keepPath)

Append the files which meet the given pattern and access modes in a directory to the existing list.

StringList * path_split (const gchar *path)

Split a composite path string by path separator.

gchar * path_concat (gchar *dest, const gchar *src, gsize destSize)

Concatenate two path strings.

gchar * truepath (const gchar *path, gchar *resolved_path)

Return the canonicalized absolute pathname.

Detailed Description

This header filed define file functions.

Define Documentation

#define DIRECTORY_SEPARATOR '/'

If WIN32 is defined, DIRECTORY_SEPARATOR is '\', otherwise '/' is used as DIRECTORY_SEPARATOR.

#define PATH_SEPARATOR ':'

If WIN32 is defined, PATH_SEPARATOR is ';', otherwise ':' is used as PATH_SEPARATOR.

Typedef Documentation

typedef TaskStatus(* ChooseFilenameFunc)(gchar *filename_buf, guint filename_len, StringList *extensions, guint access_mode_mask, const gchar *prompt, gpointer option)

This callback function should provide an UI for user select a filename. It should return:

TASK_COMPLETED if a suitable file is chosen, and the chosen filename is in filename_buf.
TASK_CANCELED if user canceled the operation.
TAKS_FAILED if user selected an unsuitable file, or encounter I/O error, the selected file should be in filename_buf

The parameter filename_buf is a buffer that hold the result filename. and filename_len is the buffer size. The present content of filename_buf will be default filename.

Parameter extensions for available extension filename, assign NULL if no need to have a specific extension. Use access_modes_mask to filter the files that has suitable access mode and permission.

Value in prompt is to be show in UI, such as dialog title or textual prompt in CLI. Use option to pass other data to the callback function.

Parameters:

	filename_buf	Buffer that holds the filename, the present content will be default filename.
	filename_len	pre-selected filename. Can be NULL.
	extensions	acceptable file extensions. NULL for don't care.
	access_mode_mask	the required access mode mask defined in File access mode..
	prompt	the string to be shown in UI, usually shown as dialog title for GUI.
	option	Other custom option.

Return values:

	TASK_COMPLETED	if a suitable file is chosen, and the chosen filename is in filename_buf.
	TASK_CANCELED	if user canceled the operation.
	TAKS_FAILED	if user selected an unsuitable file, or encounter I/O error, the selected file should be in filename_buf

See also:: filename_meets_accessMode()
filename_choose()

Enumeration Type Documentation

enum TaskStatus

This enumeration lists the task running status. It can be used as function return values, or as concurrent process running status.

Enumerator:

TASK_CANCELED	< The task is still running, usually this for concurrent process.
TASK_FAILED	< The task is canceled.
TASK_COMPLETED	< The task is failed. < The task is complete.

Function Documentation

gchar* filename_choose	(	const gchar *	filename_default,
		guint	filename_len,
		StringList *	extensions,
		guint	access_mode_mask,
		const gchar *	prompt,
		gpointer	option,
		ChooseFilenameFunc	callback
	)

This function returns either a newly allocated filename string that meets the access_mode_mask, or NULL if user cancel the process.

This function firstly try the filename given by a non-NULL filename_default, if it does not meet access_mode_make, then it will keep calling callback() to open an UI for user input until:

user inputs a valid filename, or
user cancels the operation (usually by clicking "cancel" button.)

If filename_default is NULL, this function will call callback() directly for user input.

Parameters:

	filename_default	The default filename to be check, NULL or "" if no default filename.
	filename_len	pre-selected filename. Can be NULL.
	extensions	acceptable file extensions. NULL for don't care.
	access_mode_mask	the required access mode mask defined in File access mode..
	prompt	the string to be shown in UI, usually shown as dialog title for GUI.
	option	Other custom option.
	callback	a ChooseFilenameFunc callback that open a UI for filename input.

Returns:: a newly allocated filename string that meets the access_mode_mask; NULL otherwise.

See also:: ChooseFilenameFunc()
filename_meets_accessMode()

gboolean filename_meets_accessMode	(	const gchar *	filename,
		guint	access_mode_mask
	)

This function checks whether the filename meets the requirement specified as access_mode_mask. It returns TRUE if all file access mode are meet; FALSE otherwise.

Note that if only FILE_MODE_WRITE is given to access_mode_mask, this function returns TRUE even if the file does not exist, but can be created and written. Use FILE_MODE_EXIST|FILE_MODE_WRITE the check the write permission of existing file.

Parameters:

	filename	The filename to be checked.
	access_mode_mask	the required access mode mask defined in File access mode..

gchar* filename_search_paths	(	const gchar *	filename,
		const gchar *	search_paths
	)

This function searches the given file within the search_paths. It is essentially filename_search_paths_mode(filename, search_paths, FILE_MODE_EXIST).

Parameters:

	filename	The filename to be located.
	search_paths	The paths to be searched.

Returns:: A newly allocated string of the exact location of the file; otherwise NULL is returned.

gchar* filename_search_paths_mode	(	const gchar *	filename,
		const gchar *	search_paths,
		guint	access_mode_mask
	)

This function searches the file within the search_paths, after the file is found, filename_meets_accessMode() is called to check whether the file meets the required access_mode_mask.

This function return newly allocated string of the exact location of the file if the file is found and it match the requirement; otherwise NULL is returned.

Parameters:

	filename	The filename to be located.
	search_paths	The paths to be searched.
	access_mode_mask	the required access mode mask defined in File access mode..

Returns:: A newly allocated string of the exact location of the file if the file is found and it match the requirement; otherwise NULL is returned.

See also:: File access mode..
filename_meets_accessMode()

gboolean isReadable ( const gchar * filename )

Parameters:

filename

The path name of the file.

Returns:: TRUE if the file is readable; FALSE otherwise.

gboolean isWritable ( const gchar * filename )

This function checks whether the file is writable, or can be created if filename does not exists.

Parameters:

filename

The path name of the file.

Returns:: TRUE if the file is writeable ; FALSE otherwise.

StringList* lsDir	(	const gchar *	dir,
		const gchar *	globStr,
		guint	access_mode_mask,
		gboolean	keepPath
	)

This function returns all files that match the pattern glob and the access mode access_mode_mask; NULL if error occurred.

The pattern glob is matched in the same way as in shell.

Use stringList_free() to free the result StringList.

Parameters:

	dir	Directory to be listed.
	globStr	Glob/Shell pattern such as ".", use space to separate multiple patterns.
	access_mode_mask	the required access mode mask defined in File access mode..
	keepPath	TRUE to concatenate dir to each string in the returned StringList; FALSE for the filename only (without path).

Returns:: A newly allocate StringList instance which contains the matched filename; NULL if error occurred.

See also:: lsDir_append()

StringList* lsDir_append	(	StringList *	sList,
		const gchar *	dir,
		const gchar *	globStr,
		guint	access_mode_mask,
		gboolean	keepPath
	)

This function appends the files it found to the existing list sList, and return it, otherwise it is similar with lsDir().

Parameters:

	sList	existing list.
	dir	Directory to be listed.
	globStr	Glob/Shell pattern such as ".", use space to separate multiple patterns.
	access_mode_mask	the required access mode mask defined in File access mode..
	keepPath	TRUE to concatenate dir to each string in the returned StringList; FALSE for the filename only (without path).

Returns:: The modified sList, or NULL if error occurred.

See also:: lsDir()

gchar* path_concat	(	gchar *	dest,
		const gchar *	src,
		gsize	destSize
	)

This function concatenate to path strings, a DIRECTORY_SEPARATOR is inserted between dest and src if dest does not ended with a DIRECTORY_SEPARATOR. The result string will be returned.

Parameters:

	dest	destination buffer, already containing one nul-terminated string
	src	string to be appended to dest.
	destSize	length of dest buffer in bytes (not length of existing string inside dest).

Returns:: The result string dest.

StringList* path_split ( const gchar * path )

This function splits a string that has multiple paths (composite path string) separated by PATH_SEPARATOR into individual paths. These paths will be returned as StringList.

Parameters:

path

The composite path.

Returns:: A newly allocated StringList instance that holds the split paths.

gchar* truepath	(	const gchar *	path,
		gchar *	resolved_path
	)

It works exactly the same with realpath(3), except this function can handle the path with ~, where realpath cannot.

Parameters:

	path	The path to be resolved.
	resolved_path	Buffer for holding the resolved_path.

Returns:: resolved path, NULL is the resolution is not sucessful.


Defines
#define	DIRECTORY_SEPARATOR '/'
	DIRECTORY_SEPARATOR is the separator for splits the directories in paths.
#define	PATH_SEPARATOR ':'
	PATH_SEPARATOR is the separator for splits the paths in configuration files or environment variables.
File access mode
Access modes of a file or directory. This is similar to `F_OK`, `R_OK`, `W_OK`, `X_OK` in unistd.h. However, as F_OK == 0, which is not very helpful when cooperates with other modes.
#define	FILE_MODE_NO_SYMLINK 1<<5
	Test whether the file is not symbol link.
#define	FILE_MODE_EXIST 1<<4
	Test for existence.
#define	FILE_MODE_DIRECTORY 1<<3
	Test whether the 'file' is directory.
#define	FILE_MODE_READ 1<<2
	Test for read permission.
#define	FILE_MODE_WRITE 1<<1
	Test for write permission.
#define	FILE_MODE_EXECUTE 1
	Test for execute permission.
Typedefs
typedef TaskStatus(*	ChooseFilenameFunc )(gchar filename_buf, guint filename_len, StringList extensions, guint access_mode_mask, const gchar *prompt, gpointer option)
	Prototype of callback function for choosing a filename.
Enumerations
enum	TaskStatus { TASK_RUNNING, TASK_CANCELED, TASK_FAILED, TASK_COMPLETED }
	An enumeration of task running status. More...
Functions
gboolean	isReadable (const gchar *filename)
	Whether the file is readable.
gboolean	isWritable (const gchar *filename)
	Whether the file is writable.
gboolean	filename_meets_accessMode (const gchar *filename, guint access_mode_mask)
	Whether the file meets the given access mode mask.
gchar *	filename_search_paths (const gchar filename, const gchar search_paths)
	Find a file from the search path.
gchar *	filename_search_paths_mode (const gchar filename, const gchar search_paths, guint access_mode_mask)
	Find a file with specified access mode from the search path.
gchar *	filename_choose (const gchar filename_default, guint filename_len, StringList extensions, guint access_mode_mask, const gchar *prompt, gpointer option, ChooseFilenameFunc callback)
	Choose a suitable filename if default one is not.
StringList *	lsDir (const gchar dir, const gchar globStr, guint access_mode_mask, gboolean keepPath)
	List files which meet the given pattern and access modes in a directory.
StringList *	lsDir_append (StringList sList, const gchar dir, const gchar *globStr, guint access_mode_mask, gboolean keepPath)
	Append the files which meet the given pattern and access modes in a directory to the existing list.
StringList *	path_split (const gchar *path)
	Split a composite path string by path separator.
gchar *	path_concat (gchar dest, const gchar src, gsize destSize)
	Concatenate two path strings.
gchar *	truepath (const gchar path, gchar resolved_path)
	Return the canonicalized absolute pathname.