File and directory utility functions

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

Stability Level

Unstable, unless otherwise indicated

Functions

Types and Values

Includes

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

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.

Functions

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().

Parameters

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.

Parameters

path

The directory to create.

[type filename]

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.

Parameters

path

The directory to create.

[type filename]

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.

Parameters

path

The directory to explore.

[type filename]

func

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

[scope call]

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.

Parameters

path

Path to the file to delete.

[type filename]

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.

Parameters

path

Path to the directory to delete.

[type filename]

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.

Parameters

path

Path to the directory to delete.

[type filename]

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.

Parameters

path

Path to the object to delete.

[type filename]

error

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

 

Returns

TRUE on success or FALSE on error.


inf_file_util_write_private_data ()

gboolean
inf_file_util_write_private_data (const gchar *filename,
                                  const void *data,
                                  size_t length,
                                  GError **error);

Writes data to the file pointed to by filename . On Unix-like systems, filename is created with 0600 permission. If the function fails, FALSE is returned and error is set.

Parameters

filename

Filename of the file to be written to.

 

data

Data that should be written to file.

 

length

Length of data in bytes.

 

error

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

 

Returns

TRUE on success or FALSE on error.

Types and Values

enum InfFileType

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

Members

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.