UNIX-specific utilities and integration

UNIX-specific utilities and integration — pipes, signal handling

Functions

Types and Values

#define G_UNIX_ERROR

Includes

#include <glib-unix.h>

Description

Most of GLib is intended to be portable; in contrast, this set of functions is designed for programs which explicitly target UNIX, or are using it to build higher level abstractions which would be conditionally compiled if the platform matches G_OS_UNIX.

To use these functions, you must explicitly include the "glib-unix.h" header.

Functions

g_unix_open_pipe ()

gboolean
g_unix_open_pipe (gint *fds,
                  gint flags,
                  GError **error);

Similar to the UNIX pipe() call, but on modern systems like Linux uses the pipe2() system call, which atomically creates a pipe with the configured flags. The only supported flag currently is FD_CLOEXEC. If for example you want to configure O_NONBLOCK, that must still be done separately with fcntl().

This function does not take O_CLOEXEC, it takes FD_CLOEXEC as if for fcntl(); these are different on Linux/glibc.

Parameters

fds

Array of two integers.

[array fixed-size=2]

flags

Bitfield of file descriptor flags, as for fcntl()

 

error

a GError

 

Returns

TRUE on success, FALSE if not (and errno will be set).

Since: 2.30


g_unix_set_fd_nonblocking ()

gboolean
g_unix_set_fd_nonblocking (gint fd,
                           gboolean nonblock,
                           GError **error);

Control the non-blocking state of the given file descriptor, according to nonblock . On most systems this uses O_NONBLOCK, but on some older ones may use O_NDELAY.

Parameters

fd

A file descriptor

 

nonblock

If TRUE, set the descriptor to be non-blocking

 

error

a GError

 

Returns

TRUE if successful

Since: 2.30


g_unix_signal_add ()

guint
g_unix_signal_add (gint signum,
                   GSourceFunc handler,
                   gpointer user_data);

A convenience function for g_unix_signal_source_new(), which attaches to the default GMainContext. You can remove the watch using g_source_remove().

Parameters

signum

Signal number

 

handler

Callback

 

user_data

Data for handler

 

Returns

An ID (greater than 0) for the event source

Since: 2.30


g_unix_signal_add_full ()

guint
g_unix_signal_add_full (gint priority,
                        gint signum,
                        GSourceFunc handler,
                        gpointer user_data,
                        GDestroyNotify notify);

A convenience function for g_unix_signal_source_new(), which attaches to the default GMainContext. You can remove the watch using g_source_remove().

[rename-to g_unix_signal_add]

Parameters

priority

the priority of the signal source. Typically this will be in the range between G_PRIORITY_DEFAULT and G_PRIORITY_HIGH.

 

signum

Signal number

 

handler

Callback

 

user_data

Data for handler

 

notify

GDestroyNotify for handler

 

Returns

An ID (greater than 0) for the event source

Since: 2.30


g_unix_signal_source_new ()

GSource *
g_unix_signal_source_new (gint signum);

Create a GSource that will be dispatched upon delivery of the UNIX signal signum . In GLib versions before 2.36, only SIGHUP, SIGINT, SIGTERM can be monitored. In GLib 2.36, SIGUSR1 and SIGUSR2 were added. In GLib 2.54, SIGWINCH was added.

Note that unlike the UNIX default, all sources which have created a watch will be dispatched, regardless of which underlying thread invoked g_unix_signal_source_new().

For example, an effective use of this function is to handle SIGTERM cleanly; flushing any outstanding files, and then calling g_main_loop_quit(). It is not safe to do any of this from a regular UNIX signal handler; such a handler may be invoked while malloc() or another library function is running, causing reentrancy issues if the handler attempts to use those functions. None of the GLib/GObject API is safe against this kind of reentrancy.

The interaction of this source when combined with native UNIX functions like sigprocmask() is not defined.

The source will not initially be associated with any GMainContext and must be added to one with g_source_attach() before it will be executed.

Parameters

signum

A signal number

 

Returns

A newly created GSource

Since: 2.30


GUnixFDSourceFunc ()

gboolean
(*GUnixFDSourceFunc) (gint fd,
                      GIOCondition condition,
                      gpointer user_data);

The type of functions to be called when a UNIX fd watch source triggers.

Parameters

fd

the fd that triggered the event

 

condition

the IO conditions reported on fd

 

user_data

user data passed to g_unix_fd_add()

 

Returns

FALSE if the source should be removed


g_unix_fd_add ()

guint
g_unix_fd_add (gint fd,
               GIOCondition condition,
               GUnixFDSourceFunc function,
               gpointer user_data);

Sets a function to be called when the IO condition, as specified by condition becomes true for fd .

function will be called when the specified IO condition becomes TRUE. The function is expected to clear whatever event caused the IO condition to become true and return TRUE in order to be notified when it happens again. If function returns FALSE then the watch will be cancelled.

The return value of this function can be passed to g_source_remove() to cancel the watch at any time that it exists.

The source will never close the fd -- you must do it yourself.

Parameters

fd

a file descriptor

 

condition

IO conditions to watch for on fd

 

function

a GUnixFDSourceFunc

 

user_data

data to pass to function

 

Returns

the ID (greater than 0) of the event source

Since: 2.36


g_unix_fd_add_full ()

guint
g_unix_fd_add_full (gint priority,
                    gint fd,
                    GIOCondition condition,
                    GUnixFDSourceFunc function,
                    gpointer user_data,
                    GDestroyNotify notify);

Sets a function to be called when the IO condition, as specified by condition becomes true for fd .

This is the same as g_unix_fd_add(), except that it allows you to specify a non-default priority and a provide a GDestroyNotify for user_data .

Parameters

priority

the priority of the source

 

fd

a file descriptor

 

condition

IO conditions to watch for on fd

 

function

a GUnixFDSourceFunc

 

user_data

data to pass to function

 

notify

function to call when the idle is removed, or NULL

 

Returns

the ID (greater than 0) of the event source

Since: 2.36


g_unix_fd_source_new ()

GSource *
g_unix_fd_source_new (gint fd,
                      GIOCondition condition);

Creates a GSource to watch for a particular IO condition on a file descriptor.

The source will never close the fd -- you must do it yourself.

Parameters

fd

a file descriptor

 

condition

IO conditions to watch for on fd

 

Returns

the newly created GSource

Since: 2.36


g_unix_get_passwd_entry ()

struct passwd *
g_unix_get_passwd_entry (const gchar *user_name,
                         GError **error);

Get the passwd file entry for the given user_name using getpwnam_r(). This can fail if the given user_name doesn’t exist.

The returned struct passwd has been allocated using g_malloc() and should be freed using g_free(). The strings referenced by the returned struct are included in the same allocation, so are valid until the struct passwd is freed.

This function is safe to call from multiple threads concurrently.

You will need to include pwd.h to get the definition of struct passwd.

Parameters

user_name

the username to get the passwd file entry for

 

error

return location for a GError, or NULL

 

Returns

passwd entry, or NULL on error; free the returned value with g_free().

[transfer full]

Since: 2.64

Types and Values

G_UNIX_ERROR

#define G_UNIX_ERROR (g_unix_error_quark())

Error domain for API in the g_unix_ namespace. Note that there is no exported enumeration mapping errno. Instead, all functions ensure that errno is relevant. The code for all G_UNIX_ERROR is always 0, and the error message is always generated via g_strerror().

It is expected that most code will not look at errno from these APIs. Important cases where one would want to differentiate between errors are already covered by existing cross-platform GLib API, such as e.g. GFile wrapping ENOENT. However, it is provided for completeness, at least.