## GUnixFDMessage

GUnixFDMessage — A GSocketControlMessage containing a GUnixFDList

## Synopsis

    #include <gio/gunixfdmessage.h>

                        GUnixFDMessage;
    GSocketControlMessage * g_unix_fd_message_new_with_fd_list
                                                            (GUnixFDList *fd_list);
    GSocketControlMessage * g_unix_fd_message_new           (void);
    GUnixFDList *       g_unix_fd_message_get_fd_list       (GUnixFDMessage *message);
    gboolean            g_unix_fd_message_append_fd         (GUnixFDMessage *message,
                                                             gint fd,
                                                             GError **error);
    gint *              g_unix_fd_message_steal_fds         (GUnixFDMessage *message,
                                                             gint *length);

## Object Hierarchy

      GObject
       +----GSocketControlMessage
             +----GUnixFDMessage

## Properties

      "fd-list"                  GUnixFDList*          : Read / Write / Construct Only

## Description

This GSocketControlMessage contains a GUnixFDList. It may be sent using `g_socket_send_message()` and received using `g_socket_receive_message()` over UNIX sockets (ie: sockets in the `G_SOCKET_ADDRESS_UNIX` family). The file descriptors are copied between processes by the kernel.

For an easier way to send and receive file descriptors over stream-oriented UNIX sockets, see `g_unix_connection_send_fd()` and `g_unix_connection_receive_fd()`.

Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file when using it.

## Details

### GUnixFDMessage

    typedef struct _GUnixFDMessage GUnixFDMessage;

### g_unix_fd_message_new_with_fd_list ()

    GSocketControlMessage * g_unix_fd_message_new_with_fd_list
                                                            (GUnixFDList *fd_list);

Creates a new GUnixFDMessage containing `list`.

`fd_list` : | a GUnixFDList
Returns : | a new GUnixFDMessage

Since 2.24

### g_unix_fd_message_new ()

    GSocketControlMessage * g_unix_fd_message_new           (void);

Creates a new GUnixFDMessage containing an empty file descriptor list.

Returns : | a new GUnixFDMessage

Since 2.22

### g_unix_fd_message_get_fd_list ()

    GUnixFDList *       g_unix_fd_message_get_fd_list       (GUnixFDMessage *message);

Gets the GUnixFDList contained in `message`. This function does not return a reference to the caller, but the returned list is valid for the lifetime of `message`.

`message` : | a GUnixFDMessage
Returns : | the GUnixFDList from `message`. [transfer none]

Since 2.24

### g_unix_fd_message_append_fd ()

    gboolean            g_unix_fd_message_append_fd         (GUnixFDMessage *message,
                                                             gint fd,
                                                             GError **error);

Adds a file descriptor to `message`.

The file descriptor is duplicated using `dup()`. You keep your copy of the descriptor and the copy contained in `message` will be closed when `message` is finalized.

A possible cause of failure is exceeding the per-process or system-wide file descriptor limit.

`message` : | a GUnixFDMessage
`fd` : | a valid open file descriptor
`error` : | a GError pointer
Returns : | `TRUE` in case of success, else `FALSE` (and `error` is set)

Since 2.22

### g_unix_fd_message_steal_fds ()

    gint *              g_unix_fd_message_steal_fds         (GUnixFDMessage *message,
                                                             gint *length);

Returns the array of file descriptors that is contained in this object.

After this call, the descriptors are no longer contained in `message`. Further calls will return an empty list (unless more descriptors have been added).

The return result of this function must be freed with `g_free()`. The caller is also responsible for closing all of the file descriptors.

If `length` is non-`NULL` then it is set to the number of file descriptors in the returned array. The returned array is also terminated with -1.

This function never returns `NULL`. In case there are no file descriptors contained in `message`, an empty array is returned.

`message` : | a GUnixFDMessage
`length` : | pointer to the length of the returned array, or `NULL`. [out][allow-none]
Returns : | an array of file descriptors. [array length=length][transfer full]

Since 2.22

## Property Details

### The `"fd-list"` property

      "fd-list"                  GUnixFDList*          : Read / Write / Construct Only

The GUnixFDList object to send with the message.

## See Also

GUnixConnection, GUnixFDList, GSocketControlMessage