## GUnixFDMessage

GUnixFDMessage — A GSocketControlMessage containing a list of file descriptors

## Synopsis

                        GUnixFDMessage;
    GSocketControlMessage * g_unix_fd_message_new           (void);
    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

## Description

This GSocketControlMessage contains a list of file descriptors. 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).

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

## Details

### GUnixFDMessage

    typedef struct _GUnixFDMessage GUnixFDMessage;

### g_unix_fd_message_new ()

    GSocketControlMessage * g_unix_fd_message_new           (void);

Creates a new GUnixFDMessage containing no file descriptors.

Returns : | a new GUnixFDMessage

Since 2.22

### 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`
Returns : | an array of file descriptors

Since 2.22

## See Also

#GUnixConnection