## gnome-util

gnome-util — Miscellaneous utility functions.

## Synopsis

    #include <libgnome/libgnome.h>

    #define             gnome_is_program_in_path            (program)
    const char*         g_extension_pointer                 (const char *path);
    #define             gnome_util_prepend_user_home        (x)
    #define             gnome_util_home_file                (afile)
    char*               gnome_util_user_shell               (void);
    int                 gnome_setenv                        (const char *name,
                                                             const char *value,
                                                             gboolean overwrite);
    void                gnome_unsetenv                      (const char *name);
    void                gnome_clearenv                      (void);

    #define             g_concat_dir_and_file               (dir,file)
    #define             g_file_exists                       (filename)
    #define             g_unix_error_string                 (error_num)
    #define             gnome_util_user_home                ()
    #define             g_copy_vector                       (vec)
    #define             gnome_libdir_file                   (f)
    #define             gnome_datadir_file                  (f)
    #define             gnome_sound_file                    (f)
    #define             gnome_pixmap_file                   (f)
    #define             gnome_config_file                   (f)
    #define             gnome_unconditional_libdir_file     (f)
    #define             gnome_unconditional_datadir_file    (f)
    #define             gnome_unconditional_sound_file      (f)
    #define             gnome_unconditional_pixmap_file     (f)
    #define             gnome_unconditional_config_file     (f)

## Description

The functions in this section provide some shortcuts to finding certain file paths. There are also some functions for manipulating environment variables for those systems that do not have ``getenv()`` and similar functions.

### Note

Many of the function in here are now deprecated in favour of similar functions in glib. The preferred replacement function in those cases is indicated below.

## Details

### gnome_is_program_in_path()

    #define             gnome_is_program_in_path(program)

### Warning

`gnome_is_program_in_path` is deprecated and should not be used in newly-written code.

Deprecated, use g_find_program_in_path

`program` : | A program name.
Returns : | `NULL` if program is not on the path or a string allocated with `g_malloc()` with the full path name of the program found.

### g_extension_pointer ()

    const char*         g_extension_pointer                 (const char *path);

Extracts the extension from the end of a filename (the part after the final '.' in the filename).

`path` : | A filename or file path.
Returns : | A pointer to the extension part of the filename, or a pointer to the end of the string if the filename does not have an extension.

### gnome_util_prepend_user_home()

    #define             gnome_util_prepend_user_home(x)

Prepends the home directory of the user to a filename.

`x` : | A relative filename in the user's home directory.
Returns : | A string containing `x` with the user's home directory path prepended. The string should be freed with `g_free()` when no longer required.

### gnome_util_home_file()

    #define             gnome_util_home_file(afile)

Similar to `gnome_util_prepend_user_home()`, except that "/home/fred/.gnome2", instead of just "/home/fred/" is put on the front.

`afile` : | A filename relative to the user's .gnome2 directory. Returns: A string containing `afile` with the user's home directory path and "/.gnome2" prepended. The string should be freed with `g_free()` when no longer required.

### gnome_util_user_shell ()

    char*               gnome_util_user_shell               (void);

Retrieves the user's preferred shell.

Returns : | A newly allocated string that is the path to the shell.

### gnome_setenv ()

    int                 gnome_setenv                        (const char *name,
                                                             const char *value,
                                                             gboolean overwrite);

Adds "`name`=`value`" to the environment. Note that on systems without setenv, this leaks memory so please do not use inside a loop or anything like that. The semantics are the same as the glibc `setenv()` (if `setenv()` exists, it is used).

If `overwrite` is `FALSE` and the variable already exists in the environment, then `0` is returned and the value is not changed.

`name` : | An environment variable name.
`value` : | The value to assign to the environment variable.
`overwrite` : | If `TRUE`, overwrite the existing `name` variable in the environment.
Returns : | `0` on success, `-1` on error

### gnome_unsetenv ()

    void                gnome_unsetenv                      (const char *name);

Removes `name` from the environment. In case there is no native implementation of unsetenv, this could cause leaks depending on the implementation of environment.

`name` : | The environment variable to unset.

### gnome_clearenv ()

    void                gnome_clearenv                      (void);

Clears out the environment completely. In case there is no native implementation of clearenv, this could cause leaks depending on the implementation of environment.

### g_concat_dir_and_file()

    #define             g_concat_dir_and_file(dir,file)

### Warning

`g_concat_dir_and_file` is deprecated and should not be used in newly-written code.

Programs should use `g_build_filename()` instead of this function.

`dir` : | Directory name.
`file` : | Filename.
Returns : | A newly allocated string that is the concatenation of `dir` and `file`, with seperators appropriate for the filesystem automatically taken care of.

### g_file_exists()

    #define             g_file_exists(filename)

### Warning

`g_file_exists` is deprecated and should not be used in newly-written code.

Programs should use g_file_test(`filename`, G_FILE_TEST_EXISTS) instead of this function.

`filename` : | Filename.
Returns : | Returns `TRUE` if `filename` exists, `FALSE` otherwise.

### g_unix_error_string()

    #define             g_unix_error_string(error_num)

### Warning

`g_unix_error_string` is deprecated and should not be used in newly-written code.

Programs should use `g_strerror()` instead of this function. Also, note that the returned string is only valid until the next call to `g_strerror()` or `g_unix_error_string()`.

`error_num` : | A system error number (see C errno documentation for more info).
Returns : | A string describing the error code.

### gnome_util_user_home()

    #define             gnome_util_user_home()

### Warning

`gnome_util_user_home` is deprecated and should not be used in newly-written code.

Programs should use `g_get_home_dir()` instead of this function.

Returns : | The current user's home directory.

### g_copy_vector()

    #define             g_copy_vector(vec)

### Warning

`g_copy_vector` is deprecated and should not be used in newly-written code.

Use `g_strdupv()` instead of this function.

`vec` : | An array of strings. `NULL` terminated.
Returns : | A copy of the `NULL`-terminated string array.

### gnome_libdir_file()

    #define             gnome_libdir_file(f)

### Warning

`gnome_libdir_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME library directory (not the application's directory).

### gnome_datadir_file()

    #define             gnome_datadir_file(f)

### Warning

`gnome_datadir_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME data directory (not the application's directory).

### gnome_sound_file()

    #define             gnome_sound_file(f)

### Warning

`gnome_sound_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME sound files directory (not the application's directory).

### gnome_pixmap_file()

    #define             gnome_pixmap_file(f)

### Warning

`gnome_pixmap_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME pixmap directory (not the application's directory).

### gnome_config_file()

    #define             gnome_config_file(f)

### Warning

`gnome_config_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME config directory (not the application's directory).

### gnome_unconditional_libdir_file()

    #define             gnome_unconditional_libdir_file(f)

### Warning

`gnome_unconditional_libdir_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME library directory (not the application's directory).

### gnome_unconditional_datadir_file()

    #define             gnome_unconditional_datadir_file(f)

### Warning

`gnome_unconditional_datadir_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME data directory (not the application's directory).

### gnome_unconditional_sound_file()

    #define             gnome_unconditional_sound_file(f)

### Warning

`gnome_unconditional_sound_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME sound files directory (not the application's directory).

### gnome_unconditional_pixmap_file()

    #define             gnome_unconditional_pixmap_file(f)

### Warning

`gnome_unconditional_pixmap_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME pixmap directory (not the application's directory).

### gnome_unconditional_config_file()

    #define             gnome_unconditional_config_file(f)

### Warning

`gnome_unconditional_config_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME config directory (not the application's directory).