## UNIX-specific utilities and integration

UNIX-specific utilities and integration — pipes, signal handling

## Functions

gboolean | g_unix_open_pipe ()
gboolean | g_unix_set_fd_nonblocking ()
guint | g_unix_signal_add ()
guint | g_unix_signal_add_full ()
GSource * | g_unix_signal_source_new ()
gboolean | (*GUnixFDSourceFunc) ()
guint | g_unix_fd_add ()
guint | g_unix_fd_add_full ()
GSource * | g_unix_fd_source_new ()
struct passwd * | g_unix_get_passwd_entry ()

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

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