@c -*-texinfo-*-
@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2020 - 2021 Free Software Foundation, Inc.
@c See the file g-golf.texi for copying conditions.


@c @defindex tl


@node Miscellaneous Utility Functions
@subsection Miscellaneous Utility Functions

G-Golf Glib Miscellaneous Utility Functions low level API.@*
Miscellaneous Utility Functions - a selection of portable utility functions


@subheading Procedures

@indentedblock
@table @code
@item @ref{g-get-prgname}
@item @ref{g-set-prgname}
@item @ref{g-get-system-data-dirs}
@item @ref{g-get-system-config-dirs}
@item @ref{g-get-os-info}
@end table
@end indentedblock


@c @subheading Types and Values

@c @indentedblock
@c @table @code
@c @item @ref{<gi-enum>}
@c @end table
@c @end indentedblock


@c @subheading Struct Hierarchy

@c @indentedblock
@c GIBaseInfo           	       		@*
@c @ @ +--- GIRegisteredTypeInfo  		@*
@c @ @ @ @ @ @ @ @ @ @ @  +--- GIEnumInfo
@c @end indentedblock


@subheading Description

These are portable utility functions.


@subheading Procedures


@anchor{g-get-prgname}
@deffn Procedure g-get-prgname

Returns the name of the program, or #f if it has not been set yet.

Obtains and returns the name of the program. This name should not be
localized, in contrast to @code{g-get-application-name}.

If you are using @code{GApplication}, the program name is set in
@code{g-application-run}.

@c In case of @code{GDK} or @code{GTK+} it is set in @code{gdk-init}, which
@c is called by @code{gtk_init} and the @samp{startup} handler. The program
@c name is found by taking the last component of argv [0].
@end deffn


@anchor{g-set-prgname}
@deffn Procedure g-set-prgname name

Returns nothing.

Sets the name of the program to @var{name}. This name should not be
localized, in contrast to @code{g-set-application-name}.

If you are using @code{GApplication}, the program name is set in
@code{g-application-run}.

@c In case of @code{GDK} or @code{GTK+} it is set in @code{gdk-init}, which
@c is called by @code{gtk_init} and the @samp{startup} handler. The program
@c name is found by taking the last component of argv [0].

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

@end deffn


@anchor{g-get-system-data-dirs}
@deffn Procedure g-get-system-data-dirs

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 @uref{@value{UXDG-BASEDIR-SPEC}, XDG Base Directory
Specification}. In this case the list of directories retrieved will be
@code{XDG_DATA_DIRS}.

On Windows it follows XDG Base Directory Specification if XDG_DATA_DIRS
is defined. If XDG_DATA_DIRS is undefined, 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.
@end deffn


@anchor{g-get-system-config-dirs}
@deffn Procedure g-get-system-config-dirs

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 @uref{@value{UXDG-BASEDIR-SPEC}, XDG Base Directory
Specification}. In this case the list of directories retrieved will be
@code{XDG_CONFIG_DIRS}.

On Windows it follows XDG Base Directory Specification if
XDG_CONFIG_DIRS is defined. If XDG_CONFIG_DIRS is undefined, the
directory that contains application data for all users is used
instead. 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.
@end deffn


@anchor{g-get-os-info}
@deffn Procedure g-get-os-info key-name

Returns a string or #f.

Obtains and returns information about the operating system.

On Linux this comes from the @file{/etc/os-release} file. On other
systems, it may come from a variety of sources. You can pass any UTF-8
string key name.

The associated value for the requested @var{key-name} is returned or
@code{#f} if this information is not provided.
@end deffn


@c @subheading Types and Values
