UNIX-specific utilities and integration

## UNIX-specific utilities and integration UNIX-specific utilities and integration — pipes, signal handling |

## Synopsis

    #include <glib-unix.h>

    #define             G_UNIX_ERROR
    gboolean            g_unix_open_pipe                    (gint *fds,
                                                             gint flags,
                                                             GError **error);
    guint               g_unix_signal_add                   (gint signum,
                                                             GSourceFunc handler,
                                                             gpointer user_data);
    guint               g_unix_signal_add_full              (gint priority,
                                                             gint signum,
                                                             GSourceFunc handler,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    GSource *           g_unix_signal_source_new            (gint signum);
    gboolean            g_unix_set_fd_nonblocking           (gint fd,
                                                             gboolean nonblock,
                                                             GError **error);

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

## Details

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

### Note

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

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

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

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

### Note

For reliable behavior, if your program links to gthread (either directly or indirectly via GObject, GIO, or a higher level library), you should ensure `g_thread_init()` is called before using this function. For example, if your program uses GObject, call `g_type_init()`.

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.

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

`fd` : | A file descriptor
`nonblock` : | If `TRUE`, set the descriptor to be non-blocking
`error` : | a GError
Returns : | `TRUE` if successful

Since 2.30