## fs

fs — Utilities for modifying the file system and other aspects of user/group management.

## Synopsis

    #include <libuser/fs.h>

    gboolean            lu_homedir_move                     (const char *oldhome,
                                                             const char *newhome,
                                                             struct lu_error **error);
    gboolean            lu_homedir_populate                 (struct lu_context *ctx,
                                                             const char *skeleton,
                                                             const char *directory,
                                                             uid_t owner,
                                                             gid_t group,
                                                             mode_t mode,
                                                             struct lu_error **error);
    gboolean            lu_homedir_remove                   (const char *directory,
                                                             struct lu_error **error);
    gboolean            lu_homedir_remove_for_user          (struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_homedir_remove_for_user_if_owned (struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_mail_spool_create                (struct lu_context *ctx,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    gboolean            lu_mail_spool_remove                (struct lu_context *ctx,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);
    #define             LU_NSCD_CACHE_GROUP
    #define             LU_NSCD_CACHE_PASSWD
    void                lu_nscd_flush_cache                 (const char *table);

## Description

These routines allow an application to work with home directories, mail spools and nscd caches.

## Details

### lu_homedir_move ()

    gboolean            lu_homedir_move                     (const char *oldhome,
                                                             const char *newhome,
                                                             struct lu_error **error);

Moves user's home directory to `newhome`.

Currently implemented by first creating a copy, then deleting the original, expect this to take a long time.

If you want to use this in a hostile environment, ensure that no untrusted user has write permission to any parent of `oldhome` or `newhome`. Usually /home is only writable by root, which is safe; user's write permission to `oldhome` itself is OK.

`oldhome` : | Path to the old home directory
`newhome` : | Path to the new home directory
`error` : | Filled with lu_error if an error occurs
Returns : | `TRUE` on success

### lu_homedir_populate ()

    gboolean            lu_homedir_populate                 (struct lu_context *ctx,
                                                             const char *skeleton,
                                                             const char *directory,
                                                             uid_t owner,
                                                             gid_t group,
                                                             mode_t mode,
                                                             struct lu_error **error);

Creates a new home directory for an user.

If you want to use this in a hostile environment, ensure that no untrusted user has write permission to any parent of `skeleton` or `directory`. Usually /home is only writable by root, which is safe.

`ctx` : | A context
`skeleton` : | Path to a "skeleton" directory, or `NULL` for the system default
`directory` : | The home directory to populate
`owner` : | UID to use for contents of the new home directory
`group` : | GID to use for contents of the new home directory that have GID set to 0 in the skeleton director
`mode` : | Mode to use for the top-level directory, also affected by umask
`error` : | Filled with lu_error if an error occurs
Returns : | `TRUE` on success

### lu_homedir_remove ()

    gboolean            lu_homedir_remove                   (const char *directory,
                                                             struct lu_error **error);

Recursively removes a user's home (or really, any) directory.

If you want to use this in a hostile environment, ensure that no untrusted user has write permission to any parent of `directory`.

`directory` : | Path to the root of the directory tree
`error` : | Filled with lu_error if an error occurs
Returns : | `TRUE` on success

### lu_homedir_remove_for_user ()

    gboolean            lu_homedir_remove_for_user          (struct lu_ent *ent,
                                                             struct lu_error **error);

Recursively removes the home directory of user `ent`.

If you want to use this in a hostile environment, ensure that no untrusted user has write permission to any parent of `ent`'s home directory.

`ent` : | An entity describing the user
`error` : | Filled with lu_error if an error occurs
Returns : | `TRUE` on success

### lu_homedir_remove_for_user_if_owned ()

    gboolean            lu_homedir_remove_for_user_if_owned (struct lu_ent *ent,
                                                             struct lu_error **error);

Recursively removes the home directory of user `ent`, only if the directory is owned by `ent`. Otherwise fails with `lu_error_homedir_not_owned`.

If you want to use this in a hostile environment, ensure that no untrusted user has write permission to any parent of `ent`'s home directory.

`ent` : | An entity describing the user
`error` : | Filled with lu_error if an error occurs
Returns : | `TRUE` on success

### lu_mail_spool_create ()

    gboolean            lu_mail_spool_create                (struct lu_context *ctx,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Creates a mail spool for the specified user.

`ctx` : | A context
`ent` : | An entity representing the relevant user
`error` : | Filled with lu_error if an error occurs
Returns : | `TRUE` on success

### lu_mail_spool_remove ()

    gboolean            lu_mail_spool_remove                (struct lu_context *ctx,
                                                             struct lu_ent *ent,
                                                             struct lu_error **error);

Creates a mail spool for the specified user.

`ctx` : | A context
`ent` : | An entity representing the relevant user
`error` : | Filled with lu_error if an error occurs
Returns : | `TRUE` on success

### LU_NSCD_CACHE_GROUP

    #define LU_NSCD_CACHE_GROUP "group"

Name of the NSCD cache containing group data.

### LU_NSCD_CACHE_PASSWD

    #define LU_NSCD_CACHE_PASSWD "passwd"

Name of the NSCD cache containing user data.

### lu_nscd_flush_cache ()

    void                lu_nscd_flush_cache                 (const char *table);

Flushes the specified nscd cache to make the changes performed by other libuser functions immediately visible.

`table` : | Name of the relevant nscd table