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