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);
    gboolean            g_unix_set_fd_nonblocking           (gint fd,
                                                             gboolean nonblock,
                                                             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            (*GUnixFDSourceFunc)                (gint fd,
                                                             GIOCondition condition,
                                                             gpointer user_data);
    guint               g_unix_fd_add                       (gint fd,
                                                             GIOCondition condition,
                                                             GUnixFDSourceFunc function,
                                                             gpointer user_data);
    guint               g_unix_fd_add_full                  (gint priority,
                                                             gint fd,
                                                             GIOCondition condition,
                                                             GUnixFDSourceFunc function,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    GSource *           g_unix_fd_source_new                (gint fd,
                                                             GIOCondition condition);

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

### 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 Rename to: g_unix_signal_add

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.

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.

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

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

`fd` : | a file descriptor
`condition` : | IO conditions to watch for on `fd`
`function` : | a GPollFDFunc
`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`.

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

`fd` : | a file descriptor
`condition` : | IO conditions to watch for on `fd`
Returns : | the newly created GSource

Since 2.36