File and directory utility functions

File and directory utility functions — Helper functions to handle directories.

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libinfinity/common/inf-file-util.h>

enum                InfFileType;
gboolean            (*InfFileListFunc)                  (const gchar *name,
                                                         const gchar *path,
                                                         InfFileType type,
                                                         gpointer user_data,
                                                         GError **error);
gboolean            inf_file_util_create_single_directory
                                                        (const gchar *path,
                                                         int mode,
                                                         GError **error);
gboolean            inf_file_util_create_directory      (const gchar *path,
                                                         int mode,
                                                         GError **error);
gboolean            inf_file_util_list_directory        (const gchar *path,
                                                         InfFileListFunc func,
                                                         gpointer user_data,
                                                         GError **error);
gboolean            inf_file_util_delete_file           (const gchar *path,
                                                         GError **error);
gboolean            inf_file_util_delete_single_directory
                                                        (const gchar *path,
                                                         GError **error);
gboolean            inf_file_util_delete_directory      (const gchar *path,
                                                         GError **error);
gboolean            inf_file_util_delete                (const gchar *path,
                                                         GError **error);

Description

These functions are utility functions that can be used when dealing with directories. It allows platform-independent creation, deletion and traversal of directories, with proper error reporting.

Details

enum InfFileType

typedef enum {
  INF_FILE_TYPE_UNKNOWN,
  INF_FILE_TYPE_REG,
  INF_FILE_TYPE_DIR,
  INF_FILE_TYPE_LNK
} InfFileType;

This type represents the possible file types that inf_file_util_list_directory() can report.

INF_FILE_TYPE_UNKNOWN

Unknown file type.

INF_FILE_TYPE_REG

File is a regular file.

INF_FILE_TYPE_DIR

File is a directory.

INF_FILE_TYPE_LNK

File is a symbolic link.

InfFileListFunc ()

gboolean            (*InfFileListFunc)                  (const gchar *name,
                                                         const gchar *path,
                                                         InfFileType type,
                                                         gpointer user_data,
                                                         GError **error);

This is the prototype of the callback function passed to inf_file_util_list_directory(). If the function returns FALSE then directory traversal is stopped immediately. In addition error can be set and it is propagated to the caller of inf_file_util_list_directory().

name :

The name of the current file.

path :

The full path to the current file.

type :

The type of the current file.

user_data :

User data specified at the time of the call.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE if the iteration should be continued or FALSE otherwise.

inf_file_util_create_single_directory ()

gboolean            inf_file_util_create_single_directory
                                                        (const gchar *path,
                                                         int mode,
                                                         GError **error);

Attempts to create a directory at path. The mode parameter is only used on Unix in which case it specifies the permissions to use for all newly created directories in the same way as g_mkdir() would.

path :

The directory to create.

mode :

Permissions to use for the newly created directory.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE on success or FALSE on error.

inf_file_util_create_directory ()

gboolean            inf_file_util_create_directory      (const gchar *path,
                                                         int mode,
                                                         GError **error);

Attempts to create a directory at path, creating intermediate directories as necessary. The mode parameter is only used on Unix in which case it specifies the permissions to use for all newly created directories in the same way as g_mkdir() would.

path :

The directory to create.

mode :

Permissions to use for the newly created directory.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE on success or FALSE on error.

inf_file_util_list_directory ()

gboolean            inf_file_util_list_directory        (const gchar *path,
                                                         InfFileListFunc func,
                                                         gpointer user_data,
                                                         GError **error);

Calls func for each file within the given directory. It also passes the type of the found file to the callback function. The callback function can return FALSE to stop the iteration. If it does this, then this function still returns TRUE. This can for example be used to find a file in a directory. If, in addition, the callback function sets error, then this function returns FALSE and propagates the error.

path :

The directory to explore.

func :

Callback function to be called for each child of the directory at path.

user_data :

Additional data to pass to func.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE on success or FALSE on error.

inf_file_util_delete_file ()

gboolean            inf_file_util_delete_file           (const gchar *path,
                                                         GError **error);

Removes the file at path if it is empty. Fails if path points to a directory and not a regular file. If the function fails FALSE is returned and error is set.

path :

Path to the file to delete.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE on success or FALSE on error.

inf_file_util_delete_single_directory ()

gboolean            inf_file_util_delete_single_directory
                                                        (const gchar *path,
                                                         GError **error);

Removes the directory at path if it is empty, or fails otherwise. Fails if path points to a regular file and not a directory. If the function fails FALSE is returned and error is set.

path :

Path to the directory to delete.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE on success or FALSE on error.

inf_file_util_delete_directory ()

gboolean            inf_file_util_delete_directory      (const gchar *path,
                                                         GError **error);

Removes the directory at path recursively. Fails if path points to a regular file and not a directory. If the function fails FALSE is returned and error is set.

path :

Path to the directory to delete.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE on success or FALSE on error.

inf_file_util_delete ()

gboolean            inf_file_util_delete                (const gchar *path,
                                                         GError **error);

Removes the file or directory at path. If it is a directory the directory is deleted recursively. If the function fails FALSE is returned and error is set.

path :

Path to the object to delete.

error :

Location to store error information, if any, or NULL.

Returns :

TRUE on success or FALSE on error.