GUnixFDMessage

GUnixFDMessage — A GSocketControlMessage containing a GUnixFDList

Functions

Properties

GUnixFDList * fd-list Read / Write / Construct Only

Types and Values

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

Owner: GUnixFDMessage

Flags: Read / Write / Construct Only

See Also

GUnixConnection, GUnixFDList, GSocketControlMessage