Specifies a function to be called at normal program termination.

Since GLib 2.8.2, on Windows Atexit actually is a preprocessor macro that maps to a call to the atexit() function in the C library. This means that in case the code that calls Atexit, i.e. atexit(), is in a DLL, the function will be called when the DLL is detached from the program. This typically makes more sense than that the function is called when the GLib DLL is detached, which happened earlier when Atexit was a function in the GLib DLL.

The behaviour of atexit() in the context of dynamically loaded modules is not formally specified and varies wildly.

On POSIX systems, calling Atexit (or atexit()) in a dynamically loaded module which is unloaded before the program terminates might well cause a crash at program exit.

Some POSIX systems implement atexit() like Windows, and have each dynamically loaded module maintain an own atexit chain that is called when the module is unloaded.

On other POSIX systems, before a dynamically loaded module is unloaded, the registered atexit functions (if any) residing in that module are called, regardless where the code that registered them resided. This is presumably the most robust approach.

As can be seen from the above, for portability it's best to avoid calling Atexit (or atexit()) except in the main executable of a program.

Find the position of the first bit set in mask, searching from (but not including) nth_bit upwards. Bits are numbered from 0 (least significant) to sizeof(gulong) * 8 - 1 (31 or 63, usually). To start searching from the 0th bit, set nth_bit to -1.

Find the position of the first bit set in mask, searching from (but not including) nth_bit downwards. Bits are numbered from 0 (least significant) to sizeof(gulong) * 8 - 1 (31 or 63, usually). To start searching from the last bit, set nth_bit to -1 or GLIB_SIZEOF_LONG * 8.

Gets the number of bits used to hold number, e.g. if number is 4, 3 bits are needed.

Locates the first executable named program in the user's path, in the same way that execvp() would locate it. Returns an allocated string with the absolute path name, or NULL if the program is not found in the path. If program is already an absolute path, returns a copy of program if program exists and is executable, and NULL otherwise. On Windows, if program does not have a file type suffix, tries with the suffixes .exe, .cmd, .bat and .com, and the suffixes in the PATHEXT environment variable.

On Windows, it looks for the file in the same way as CreateProcess() would. This means first in the directory where the executing program was loaded from, then in the current directory, then in the Windows 32-bit system directory, then in the Windows directory, and finally in the directories in the PATH environment variable. If the program is found, the return value contains the full name including the type suffix.

Gets a human-readable name for the application, as set by SetApplicationName. This name should be localized if possible, and is intended for display to the user. Contrast with GetPrgname, which gets a non-localized name. If SetApplicationName has not been called, returns the result of GetPrgname (which may be NULL if SetPrgname has also not been called).

Gets the current directory. The returned string should be freed when no longer needed. The encoding of the returned string is system defined. On Windows, it is always UTF-8.

Gets the list of environment variables for the current process. The list is NULL terminated and each item in the list is of the form 'NAME=VALUE'.

This is equivalent to direct access to the 'environ' global variable, except portable.

The return value is freshly allocated and it should be freed with Gtk.Glib.GStrfuncs.Strfreev when it is no longer needed.

Gets the current user's home directory as defined in the password database.

Note that in contrast to traditional UNIX tools, this function prefers passwd entries over the HOME environment variable.

One of the reasons for this decision is that applications in many cases need special handling to deal with the case where HOME is

Since applications are in general not written to deal with these situations it was considered better to make GetHomeDir not pay attention to HOME and to return the real home directory for the user. If applications want to pay attention to HOME, they can do:

1
2
3

const char *homedir = g_getenv ("HOME");
 if (!homedir)
    homedir = g_get_home_dir ();

Return a name for the machine.

The returned name is not necessarily a fully-qualified domain name, or even present in DNS or some other name service at all. It need not even be unique on your local network or site, but usually it is. Callers should not rely on the return value having any specific properties like uniqueness for security purposes. Even if the name of the machine is changed while an application is running, the return value from this function does not change. The returned string is owned by GLib and should not be modified or freed. If no name can be determined, a default fixed string "localhost" is returned.

Computes a list of applicable locale names, which can be used to e.g. construct locale-dependent filenames or search paths. The returned list is sorted from most desirable to least desirable and always contains the default locale "C".

For example, if LANGUAGE=de:en_US, then the returned list is "de", "en_US", "en", "C".

This function consults the environment variables LANGUAGE, LC_ALL, LC_MESSAGES and LANG to find the list of locales specified by the user.

Gets the name of the program. This name should not be localized, contrast with GetApplicationName. (If you are using GDK or GTK+ the program name is set in gdk_init(), which is called by gtk_init(). The program name is found by taking the last component of argv[0].)

Gets the real name of the user. This usually comes from the user's entry in the passwd file. The encoding of the returned string is system-defined. (On Windows, it is, however, always UTF-8.) If the real user name cannot be determined, the string "Unknown" is returned.

Returns an ordered list of base directories in which to access system-wide configuration information.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification. In this case the list of directories retrieved will be XDG_CONFIG_DIRS.

On Windows is the directory that contains application data for all users. A typical path is C:\Documents and Settings\All Users\Application Data. This folder is used for application data that is not user specific. For example, an application can store a spell-check dictionary, a database of clip art, or a log file in the CSIDL_COMMON_APPDATA folder. This information will not roam and is available to anyone using the computer.

Returns an ordered list of base directories in which to access system-wide application data.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification In this case the list of directories retrieved will be XDG_DATA_DIRS.

On Windows the first elements in the list are the Application Data and Documents folders for All Users. (These can be determined only on Windows 2000 or later and are not present in the list on other Windows versions.) See documentation for CSIDL_COMMON_APPDATA and CSIDL_COMMON_DOCUMENTS.

Then follows the "share" subfolder in the installation folder for the package containing the DLL that calls this function, if it can be determined.

Finally the list contains the "share" subfolder in the installation folder for GLib, and in the installation folder for the package the application's .exe file belongs to.

The installation folders above are determined by looking up the folder where the module (DLL or EXE) in question is located. If the folder's name is "bin", its parent is used, otherwise the folder itself.

Note that on Windows the returned list can vary depending on where this function is called.

Gets the directory to use for temporary files. This is found from inspecting the environment variables TMPDIR, TMP, and TEMP in that order. If none of those are defined "/tmp" is returned on UNIX and "C:\" on Windows. The encoding of the returned string is system-defined. On Windows, it is always UTF-8. The return value is never NULL or the empty string.

Returns a base directory in which to store non-essential, cached data specific to particular user.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification. In this case the directory retrieved will be XDG_CACHE_HOME.

On Windows is the directory that serves as a common repository for temporary Internet files. A typical path is C:\Documents and Settings\username\Local Settings\Temporary Internet Files. See documentation for CSIDL_INTERNET_CACHE.

Returns a base directory in which to store user-specific application configuration information such as user preferences and settings.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification. In this case the directory retrieved will be XDG_CONFIG_HOME.

On Windows this is the folder to use for local (as opposed to roaming) application data. See documentation for CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as what GetUserDataDir returns.

Returns a base directory in which to access application data such as icons that is customized for a particular user.

On UNIX platforms this is determined using the mechanisms described in the XDG Base Directory Specification. In this case the directory retrieved will be XDG_DATA_HOME.

On Windows this is the folder to use for local (as opposed to roaming) application data. See documentation for CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as what GetUserConfigDir returns.

Gets the user name of the current user. The encoding of the returned string is system-defined. On UNIX, it might be the preferred file name encoding, or something else, and there is no guarantee that it is even consistent on a machine. On Windows, it is always UTF-8.

Returns the full path of a special directory using its logical id.

On Unix this is done using the XDG special user directories. For compatibility with existing practise, Gtk.Glib.GUserDirectory.DirectoryDesktop falls back to $HOME/Desktop when XDG special user directories have not been set up.

Depending on the platform, the user might be able to change the path of the special directory without requiring the session to restart; GLib will not reflect any change once the special directories are loaded.

Returns the value of an environment variable. The name and value are in the GLib file name encoding. On UNIX, this means the actual bytes which might or might not be in some consistent character set and encoding. On Windows, it is in UTF-8. On Windows, in case the environment variable's value contains references to other environment variables, they are expanded.

Gets the names of all variables set in the environment.

Set the pointer at the specified location to NULL.

Parses a string containing debugging options into a guint containing bit flags. This is used within GDK and GTK+ to parse the debug options passed on the command line or through environment variables.

If string is equal to "all", all flags are set. If string is equal to "help", all the available keys in keys are printed out to standard error.

Gets the last component of the filename. If file_name ends with a directory separator it gets the component before the last slash. If file_name consists only of directory separators (and on Windows, possibly a drive letter), a single separator is returned. If file_name is empty, it gets ".".

Gets the directory components of a file name. If the file name has no directory components "." is returned. The returned string should be freed when no longer needed.

Returns TRUE if the given file_name is an absolute file name. Note that this is a somewhat vague concept on Windows.

On POSIX systems, an absolute file name is well-defined. It always starts from the single root directory. For example "/usr/local".

On Windows, the concepts of current drive and drive-specific current directory introduce vagueness. This function interprets as an absolute file name one that either begins with a directory separator such as "\Users\tml" or begins with the root on a drive, for example "C:\Windows". The first case also includes UNC paths such as "\\myserver\docs\foo". In all cases, either slashes or backslashes are accepted.

Note that a file name relative to the current drive root does not truly specify a file uniquely over time and across processes, as the current drive is a per-process value and can be changed.

File names relative the current directory on some specific drive, such as "D:foo/bar", are not interpreted as absolute by this function, but they obviously are not relative to the normal current directory as returned by getcwd() or GetCurrentDir either. Such paths should be avoided, or need to be handled using Windows-specific code.

Returns a pointer into file_name after the root component, i.e. after the "/" in UNIX or "C:\" under Windows. If file_name is not an absolute path it returns NULL.

Resets the cache used for GetUserSpecialDir, so that the latest on-disk version is used. Call this only if you just changed the data on disk yourself.

Due to threadsafety issues this may cause leaking of strings that were previously returned from GetUserSpecialDir that can't be freed. We ensure to only leak the data for the directories that actually changed value though.

Since 2.22

Sets a human-readable name for the application. This name should be localized if possible, and is intended for display to the user. Contrast with SetPrgname, which sets a non-localized name. SetPrgname will be called automatically by gtk_init(), but SetApplicationName will not.

Note that for thread safety reasons, this function can only be called once.

The application name will be used in contexts such as error messages, or when displaying an application's name in the task list.

Sets the name of the program. This name should not be localized, contrast with SetApplicationName. Note that for thread-safety reasons this function can only be called once.

Sets an environment variable. Both the variable's name and value should be in the GLib file name encoding. On UNIX, this means that they can be any sequence of bytes. On Windows, they should be in UTF-8.

Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed.

A safer form of the standard sprintf() function. The output is guaranteed to not exceed n characters (including the terminating nul character), so it is easy to ensure that a buffer overflow cannot occur.

See also Gtk.Glib.GStrfuncs.StrdupPrintf.

In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be nul-terminated. In versions prior to 1.3.12, this function returns the length of the output string.

The return value of Snprintf conforms to the snprintf() function as standardized in ISO C99. Note that this is different from traditional snprintf(), which returns the length of the output string.

The format string may contain positional parameters, as specified in the Single Unix Specification.

Returns the height of a Gtk.Glib.GTrashStack.T. Note that execution of this function is of O(N) complexity where N denotes the number of items on the stack.

Returns the element at the top of a Gtk.Glib.GTrashStack.T which may be NULL.

Pops a piece of memory off a Gtk.Glib.GTrashStack.T.

Pushes a piece of memory onto a Gtk.Glib.GTrashStack.T.

Removes an environment variable from the environment.

Note that on some systems, when variables are overwritten, the memory used for the previous variables and its value isn't reclaimed. Furthermore, this function can't be guaranteed to operate in a threadsafe way.

A safer form of the standard vsprintf() function. The output is guaranteed to not exceed n characters (including the terminating nul character), so it is easy to ensure that a buffer overflow cannot occur.

See also Gtk.Glib.GStrfuncs.StrdupVprintf.

In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be nul-terminated. In versions prior to 1.3.12, this function returns the length of the output string.

The return value of Vsnprintf conforms to the vsnprintf() function as standardized in ISO C99. Note that this is different from traditional vsnprintf(), which returns the length of the output string.

The format string may contain positional parameters, as specified in the Single Unix Specification.

Checks that the GLib library in use is compatible with the given version. Generally you would pass in the constants GLIB_MAJOR_VERSION, GLIB_MINOR_VERSION, GLIB_MICRO_VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of GLib the application or module was compiled against.

Compatibility is defined by two things: first the version of the running library is newer than the version required_major.required_minor.required_micro. Second the running library must be binary compatible with the version required_major.required_minor.required_micro (same major version.)