## File and directory utility functions

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

## Stability Level

Unstable, unless otherwise indicated

## Functions

gboolean | ( *InfFileListFunc ) ()
gboolean | inf_file_util_create_single_directory ()
gboolean | inf_file_util_create_directory ()
gboolean | inf_file_util_list_directory ()
gboolean | inf_file_util_delete_file ()
gboolean | inf_file_util_delete_single_directory ()
gboolean | inf_file_util_delete_directory ()
gboolean | inf_file_util_delete ()
gboolean | inf_file_util_write_private_data ()

## Types and Values

enum | InfFileType

## 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. |