GUnixFDMessage: GIO Reference Manual

## GUnixFDMessage GUnixFDMessage — A GSocketControlMessage containing a GUnixFDList |

## Functions

GSocketControlMessage * | g_unix_fd_message_new_with_fd_list ()
GSocketControlMessage * | g_unix_fd_message_new ()
GUnixFDList * | g_unix_fd_message_get_fd_list ()
gboolean | g_unix_fd_message_append_fd ()
gint * | g_unix_fd_message_steal_fds ()

## Properties

GUnixFDList * | fd-list | Read / Write / Construct Only

## Types and Values

struct | GUnixFDMessage

## Object Hierarchy

        GObject
        ╰── GSocketControlMessage
            ╰── GUnixFDMessage

## Includes

    #include <gio/gunixfdmessage.h>

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

## Functions

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

message | a GUnixFDMessage |
length | pointer to the length of the returned array, or `NULL`. | [out][optional]

#### Returns

an array of file descriptors.

[array length=length][transfer full]

Since: 2.22

## Types and Values

### struct GUnixFDMessage

    struct GUnixFDMessage;

GUnixFDMessage is an opaque data structure and can only be accessed using the following functions.

## Property Details

### The `“fd-list”` property

      “fd-list”                  GUnixFDList *

The GUnixFDList object to send with the message.

Flags: Read / Write / Construct Only

## See Also

GUnixConnection, GUnixFDList, GSocketControlMessage