UNIX-specific utilities and integration

UNIX-specific utilities and integration — pipes, signal handling

Functions

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_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.


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

 

flags

Bitfield of file descriptor flags, see "man 2 fcntl"

 

error

a GError

 

Returns

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

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().

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 . Currently only SIGHUP, SIGINT, and SIGTERM can be monitored. 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 a regular UNIX signal handler; your handler may be invoked while malloc() or another library function is running, causing reentrancy if you attempt to use it from the handler. 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


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

Types and Values