Functions¶

	`closefrom` (lowfd)
	`error_quark` ()
	`fd_add_full` (priority, fd, condition, function, *user_data)
	`fd_query_path` (fd)
	`fd_source_new` (fd, condition)
	`fdwalk_set_cloexec` (lowfd)
	`get_passwd_entry` (user_name)
	`open_pipe` (fds, flags)
	`set_fd_nonblocking` (fd, nonblock)
	`signal_add` (priority, signum, handler, *user_data)
	`signal_source_new` (signum)

Details¶

GLibUnix.closefrom(lowfd)¶

Parameters:: lowfd (int) – Minimum fd to close, which must be non-negative
Returns:: 0 on success, -1 with errno set on error
Return type:: int

Close every file descriptor equal to or greater than lowfd.

Typically lowfd will be 3, to leave standard input, standard output and standard error open.

This is the same as Linux close_range (lowfd, ~0U, 0), but portable to other OSs and to older versions of Linux. Equivalently, it is the same as BSD closefrom (lowfd), but portable, and async-signal-safe on all OSs.

This function is async-signal safe, making it safe to call from a signal handler or a [callback`GLib`.SpawnChildSetupFunc], as long as lowfd is non-negative. See signal(7)) and signal-safety(7)) for more details.

New in version 2.80.

GLibUnix.error_quark()¶

Return type:: int

GLibUnix.fd_add_full(priority, fd, condition, function, *user_data)¶

Parameters:

priority (int) – the priority of the source
fd (int) – a file descriptor
condition (GLib.IOCondition) – IO conditions to watch for on fd
function (GLibUnix.FDSourceFunc) – a GLibUnix.FDSourceFunc
user_data (object or None) – data to pass to function

Returns:

the ID (greater than 0) of the event source

Return type:

int

Sets a function to be called when the IO condition, as specified by condition becomes true for fd.

This is the same as g_unix_fd_add(), except that it allows you to specify a non-default priority and a provide a GLib.DestroyNotify for user_data.

New in version 2.36.

GLibUnix.fd_query_path(fd)¶

Parameters:: fd (int) – The file descriptor to query.
Raises:: GLib.Error
Returns:: The file path, or NULL on error
Return type:: str

Queries the file path for the given FD opened by the current process.

New in version 2.88.

GLibUnix.fd_source_new(fd, condition)¶

Parameters:

fd (int) – a file descriptor
condition (GLib.IOCondition) – I/O conditions to watch for on fd

Returns:

the newly created GLib.Source

Return type:

GLib.Source

Creates a GLib.Source to watch for a particular I/O condition on a file descriptor.

The source will never close the fd — you must do it yourself.

Any callback attached to the returned GLib.Source must have type GLibUnix.FDSourceFunc.

New in version 2.36.

GLibUnix.fdwalk_set_cloexec(lowfd)¶

Parameters:: lowfd (int) – Minimum fd to act on, which must be non-negative
Returns:: 0 on success, -1 with errno set on error
Return type:: int

Mark every file descriptor equal to or greater than lowfd to be closed at the next execve() or similar, as if via the FD_CLOEXEC flag.

Typically lowfd will be 3, to leave standard input, standard output and standard error open after exec.

This is the same as Linux close_range (lowfd, ~0U, CLOSE_RANGE_CLOEXEC), but portable to other OSs and to older versions of Linux.

This function is async-signal safe, making it safe to call from a signal handler or a [callback`GLib`.SpawnChildSetupFunc], as long as lowfd is non-negative. See signal(7)) and signal-safety(7)) for more details.

New in version 2.80.

GLibUnix.get_passwd_entry(user_name)¶

Parameters:: user_name (str) – the username to get the passwd file entry for
Raises:: GLib.Error
Returns:: passwd entry, or None on error; free the returned value with GLib.free()
Return type:: object or None

Get the passwd file entry for the given user_name using getpwnam_r(). This can fail if the given user_name doesn’t exist.

The returned struct passwd has been allocated using GLib.malloc() and should be freed using GLib.free(). The strings referenced by the returned struct are included in the same allocation, so are valid until the struct passwd is freed.

This function is safe to call from multiple threads concurrently.

You will need to include pwd.h to get the definition of struct passwd.

New in version 2.64.

GLibUnix.open_pipe(fds, flags)¶

Parameters:

fds ([int]) – Array of two integers
flags (int) – Bitfield of file descriptor flags, as for fcntl()

Raises:

GLib.Error

Returns:

True on success, False if not (and errno will be set).

Return type:

bool

Similar to the UNIX pipe() call, but on modern systems like Linux uses the pipe2() system call, which atomically creates a pipe with the configured flags.

As of GLib 2.78, the supported flags are O_CLOEXEC/FD_CLOEXEC (see below) and O_NONBLOCK. Prior to GLib 2.78, only FD_CLOEXEC was supported — if you wanted to configure O_NONBLOCK then that had to be done separately with fcntl().

Since GLib 2.80, the constants GLibUnix.PipeEnd.READ and GLibUnix.PipeEnd.WRITE can be used as mnemonic indexes in fds.

It is a programmer error to call this function with unsupported flags, and a critical warning will be raised.

As of GLib 2.78, it is preferred to pass O_CLOEXEC in, rather than FD_CLOEXEC, as that matches the underlying pipe() API more closely. Prior to 2.78, only FD_CLOEXEC was supported. Support for FD_CLOEXEC may be deprecated and removed in future.

New in version 2.30.

GLibUnix.set_fd_nonblocking(fd, nonblock)¶

Parameters:

fd (int) – A file descriptor
nonblock (bool) – If True, set the descriptor to be non-blocking

Raises:

GLib.Error

Returns:

True if successful

Return type:

bool

Control the non-blocking state of the given file descriptor, according to nonblock. On most systems this uses %O_NONBLOCK, but on some older ones may use %O_NDELAY.

New in version 2.30.

GLibUnix.signal_add(priority, signum, handler, *user_data)¶

Parameters:

priority (int) – the priority of the signal source. Typically this will be in the range between GLib.PRIORITY_DEFAULT and GLib.PRIORITY_HIGH.
signum (int) – Signal number
handler (GLib.SourceFunc) – Callback
user_data (object or None) – Data for handler

Returns:

An ID (greater than 0) for the event source

Return type:

int

A convenience function for GLibUnix.signal_source_new(), which attaches to the default GLib.MainContext. You can remove the watch using GLib.Source.remove().

New in version 2.30.

GLibUnix.signal_source_new(signum)¶

Parameters:: signum (int) – A signal number
Returns:: A newly created GLib.Source
Return type:: GLib.Source

Create a GLib.Source that will be dispatched upon delivery of the UNIX signal signum. In GLib versions before 2.36, only SIGHUP, SIGINT, SIGTERM can be monitored. In GLib 2.36, SIGUSR1 and SIGUSR2 were added. In GLib 2.54, SIGWINCH was added.

Note that unlike the UNIX default, all sources which have created a watch will be dispatched, regardless of which underlying thread invoked GLibUnix.signal_source_new().

For example, an effective use of this function is to handle SIGTERM cleanly; flushing any outstanding files, and then calling GLib.MainLoop.quit(). It is not safe to do any of this from a regular UNIX signal handler; such a handler may be invoked while malloc() or another library function is running, causing reentrancy issues if the handler attempts to use those functions. None of the GLib/GObject API is safe against this kind of reentrancy.

The interaction of this source when combined with native UNIX functions like sigprocmask() is not defined.

The source will not initially be associated with any GLib.MainContext and must be added to one with GLib.Source.attach() before it will be executed.

New in version 2.30.