Vte PTY

Vte PTY — Functions for starting a new process on a new pseudo-terminal and for manipulating pseudo-terminals

Functions

Properties

gint fd Read / Write / Construct Only
VtePtyFlags flags Read / Write / Construct Only

Types and Values

Object Hierarchy

    GEnum
    ╰── VtePtyError
    GFlags
    ╰── VtePtyFlags
    GObject
    ╰── VtePty

Implemented Interfaces

VtePty implements GInitable.

Description

The terminal widget uses these functions to start commands with new controlling pseudo-terminals and to resize pseudo-terminals.

Functions

vte_pty_new_sync ()

VtePty *
vte_pty_new_sync (VtePtyFlags flags,
                  GCancellable *cancellable,
                  GError **error);

Allocates a new pseudo-terminal.

You can later use fork() or the g_spawn_async() family of functions to start a process on the PTY.

If using fork(), you MUST call vte_pty_child_setup() in the child.

If using g_spawn_async() and friends, you MUST either use vte_pty_child_setup() directly as the child setup function, or call vte_pty_child_setup() from your own child setup function supplied.

When using vte_terminal_spawn_sync() with a custom child setup function, vte_pty_child_setup() will be called before the supplied function; you must not call it again.

Also, you MUST pass the G_SPAWN_DO_NOT_REAP_CHILD flag.

Note also that G_SPAWN_STDOUT_TO_DEV_NULL, G_SPAWN_STDERR_TO_DEV_NULL, and G_SPAWN_CHILD_INHERITS_STDIN are not supported, since stdin, stdout and stderr of the child process will always be connected to the PTY.

Note that you should set the PTY's size using vte_pty_set_size() before spawning the child process, so that the child process has the correct size from the start instead of starting with a default size and then shortly afterwards receiving a SIGWINCH signal. You should prefer using vte_terminal_pty_new_sync() which does this automatically.

[constructor]

Parameters

flags

flags from VtePtyFlags

 

cancellable

a GCancellable, or NULL.

[allow-none]

error

return location for a GError, or NULL.

[allow-none]

Returns

a new VtePty, or NULL on error with error filled in.

[transfer full]


vte_pty_new_foreign_sync ()

VtePty *
vte_pty_new_foreign_sync (int fd,
                          GCancellable *cancellable,
                          GError **error);

Creates a new VtePty for the PTY master fd .

No entry will be made in the lastlog, utmp or wtmp system files.

Note that the newly created VtePty will take ownership of fd and close it on finalize.

[constructor]

Parameters

fd

a file descriptor to the PTY

 

cancellable

a GCancellable, or NULL.

[allow-none]

error

return location for a GError, or NULL.

[allow-none]

Returns

a new VtePty for fd , or NULL on error with error filled in.

[transfer full]


vte_pty_child_setup ()

void
vte_pty_child_setup (VtePty *pty);

Parameters

pty

a VtePty

 

vte_pty_get_fd ()

int
vte_pty_get_fd (VtePty *pty);

Parameters

pty

a VtePty

 

Returns

the file descriptor of the PTY master in pty . The file descriptor belongs to pty and must not be closed or have its flags changed


vte_pty_set_size ()

gboolean
vte_pty_set_size (VtePty *pty,
                  int rows,
                  int columns,
                  GError **error);

Attempts to resize the pseudo terminal's window size. If successful, the OS kernel will send SIGWINCH to the child process group.

If setting the window size failed, error will be set to a GIOError.

Parameters

pty

a VtePty

 

rows

the desired number of rows

 

columns

the desired number of columns

 

error

return location to store a GError, or NULL.

[allow-none]

Returns

TRUE on success, FALSE on failure with error filled in


vte_pty_get_size ()

gboolean
vte_pty_get_size (VtePty *pty,
                  int *rows,
                  int *columns,
                  GError **error);

Reads the pseudo terminal's window size.

If getting the window size failed, error will be set to a GIOError.

Parameters

pty

a VtePty

 

rows

a location to store the number of rows, or NULL.

[out][allow-none]

columns

a location to store the number of columns, or NULL.

[out][allow-none]

error

return location to store a GError, or NULL

 

Returns

TRUE on success, FALSE on failure with error filled in


vte_pty_set_utf8 ()

gboolean
vte_pty_set_utf8 (VtePty *pty,
                  gboolean utf8,
                  GError **error);

Tells the kernel whether the terminal is UTF-8 or not, in case it can make use of the info. Linux 2.6.5 or so defines IUTF8 to make the line discipline do multibyte backspace correctly.

Parameters

pty

a VtePty

 

utf8

whether or not the pty is in UTF-8 mode

 

error

return location to store a GError, or NULL.

[allow-none]

Returns

TRUE on success, FALSE on failure with error filled in


vte_pty_spawn_async ()

void
vte_pty_spawn_async (VtePty *pty,
                     const char *working_directory,
                     char **argv,
                     char **envv,
                     GSpawnFlags spawn_flags,
                     GSpawnChildSetupFunc child_setup,
                     gpointer child_setup_data,
                     GDestroyNotify child_setup_data_destroy,
                     int timeout,
                     GCancellable *cancellable,
                     GAsyncReadyCallback callback);

Like vte_pty_spawn_with_fds_async(), except that this function does not allow passing file descriptors to the child process. See vte_pty_spawn_with_fds_async() for more information.

Parameters

pty

a VtePty

 

working_directory

the name of a directory the command should start in, or NULL to use the current working directory.

[allow-none]

argv

child's argument vector.

[array zero-terminated=1][element-type filename]

envv

a list of environment variables to be added to the environment before starting the process, or NULL.

[allow-none][array zero-terminated=1][element-type filename]

spawn_flags

flags from GSpawnFlags

 

child_setup

an extra child setup function to run in the child just before exec(), or NULL.

[allow-none][scope async]

child_setup_data

user data for child_setup , or NULL.

[nullable][closure child_setup]

child_setup_data_destroy

a GDestroyNotify for child_setup_data , or NULL.

[nullable][destroy child_setup_data]

timeout

a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely

 

cancellable

a GCancellable, or NULL.

[allow-none]

callback

a GAsyncReadyCallback, or NULL.

[nullable][scope async]

user_data

user data for callback .

[closure callback]

Since: 0.48


vte_pty_spawn_with_fds_async ()

void
vte_pty_spawn_with_fds_async (VtePty *pty,
                              char const*working_directory,
                              char const* const*argv,
                              char const* const*envv,
                              int const*fds,
                              int n_fds,
                              int const*map_fds,
                              int n_map_fds,
                              GSpawnFlags spawn_flags,
                              GSpawnChildSetupFunc child_setup,
                              gpointer child_setup_data,
                              GDestroyNotify child_setup_data_destroy,
                              int timeout,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback);

Starts the specified command under the pseudo-terminal pty . The argv and envv lists should be NULL-terminated. The "TERM" environment variable is automatically set to a default value, but can be overridden from envv . pty_flags controls logging the session to the specified system log files.

Note also that G_SPAWN_STDOUT_TO_DEV_NULL, G_SPAWN_STDERR_TO_DEV_NULL, and G_SPAWN_CHILD_INHERITS_STDIN are not supported in spawn_flags , since stdin, stdout and stderr of the child process will always be connected to the PTY. Also G_SPAWN_LEAVE_DESCRIPTORS_OPEN is not supported; and G_SPAWN_DO_NOT_REAP_CHILD will always be added to spawn_flags .

If fds is not NULL, the child process will map the file descriptors from fds according to map_fds ; n_map_fds must be less or equal to n_fds . This function will take ownership of the file descriptors in fds ; you must not use or close them after this call. All file descriptors in fds must have the FD_CLOEXEC flag set on them; it will be unset in the child process before calling exec.

Note that all open file descriptors apart from those mapped as above will be closed in the child. (If you want to keep some other file descriptor open for use in the child process, you need to use a child setup function that unsets the FD_CLOEXEC flag on that file descriptor manually.)

Beginning with 0.60, and on linux only, and unless VTE_SPAWN_NO_SYSTEMD_SCOPE is passed in spawn_flags , the newly created child process will be moved to its own systemd user scope; and if VTE_SPAWN_REQUIRE_SYSTEMD_SCOPE is passed, and creation of the systemd user scope fails, the whole spawn will fail. You can override the options used for the systemd user scope by providing a systemd override file for 'vte-spawn-.scope' unit. See man:systemd.unit(5) for further information.

See vte_pty_new(), and vte_terminal_watch_child() for more information.

Parameters

pty

a VtePty

 

working_directory

the name of a directory the command should start in, or NULL to use the current working directory.

[allow-none]

argv

child's argument vector.

[array zero-terminated=1][element-type filename]

envv

a list of environment variables to be added to the environment before starting the process, or NULL.

[allow-none][array zero-terminated=1][element-type filename]

fds

an array of file descriptors, or NULL.

[nullable][array length=n_fds][transfer none][scope call]

n_fds

the number of file descriptors in fds , or 0 if fds is NULL

 

map_fds

an array of integers, or NULL.

[nullable][array length=n_map_fds][transfer none][scope call]

n_map_fds

the number of elements in map_fds , or 0 if map_fds is NULL

 

spawn_flags

flags from GSpawnFlags

 

child_setup

an extra child setup function to run in the child just before exec(), or NULL.

[allow-none][scope async]

child_setup_data

user data for child_setup , or NULL.

[nullable][closure child_setup]

child_setup_data_destroy

a GDestroyNotify for child_setup_data , or NULL.

[nullable][destroy child_setup_data]

timeout

a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely

 

cancellable

a GCancellable, or NULL.

[allow-none]

callback

a GAsyncReadyCallback, or NULL.

[nullable][scope async]

user_data

user data for callback .

[closure callback]

Since: 0.62


vte_pty_spawn_finish ()

gboolean
vte_pty_spawn_finish (VtePty *pty,
                      GAsyncResult *result,
                      GPid *child_pid);

Parameters

pty

a VtePty

 

result

a GAsyncResult

 

child_pid

a location to store the child PID, or NULL.

[out][allow-none][transfer full]

error

return location for a GError, or NULL.

[allow-none]

Returns

TRUE on success, or FALSE on error with error filled in

Since: 0.48


vte_pty_close ()

void
vte_pty_close (VtePty *pty);

vte_pty_close has been deprecated since version 0.42 and should not be used in newly-written code.

Since 0.42 this is a no-op.

Parameters

pty

a VtePty

 

Types and Values

enum VtePtyFlags

Members

VTE_PTY_NO_LASTLOG

Unused. Deprecated: 0.38

 

VTE_PTY_NO_UTMP

Unused. Deprecated: 0.38

 

VTE_PTY_NO_WTMP

Unused. Deprecated: 0.38

 

VTE_PTY_NO_HELPER

Unused. Deprecated: 0.38

 

VTE_PTY_NO_FALLBACK

Unused. Deprecated: 0.38

 

VTE_PTY_NO_SESSION

Do not start a new session for the child in vte_pty_child_setup(). See man:setsid(2) for more information. Since: 0.58

 

VTE_PTY_NO_CTTY

Do not set the PTY as the controlling TTY for the child in vte_pty_child_setup(). See man:tty_ioctl(4) for more information. Since: 0.58

 

VTE_PTY_DEFAULT

the default flags

 

enum VtePtyError

Members

VTE_PTY_ERROR_PTY_HELPER_FAILED

Obsolete. Deprecated: 0.42

 

VTE_PTY_ERROR_PTY98_FAILED

failure when using PTY98 to allocate the PTY

 

VtePty

typedef struct _VtePty VtePty;

VTE_SPAWN_NO_PARENT_ENVV

#define VTE_SPAWN_NO_PARENT_ENVV        (1 << 25)

Use this as a spawn flag (together with flags from GSpawnFlags) in vte_pty_spawn_async().

Normally, the spawned process inherits the environment from the parent process; when this flag is used, only the environment variables passed to vte_pty_spawn_async() etc. are passed to the child process.


VTE_SPAWN_NO_SYSTEMD_SCOPE

#define VTE_SPAWN_NO_SYSTEMD_SCOPE      (1 << 26)

Use this as a spawn flag (together with flags from GSpawnFlags) in vte_pty_spawn_async().

Prevents vte_pty_spawn_async() etc. from moving the newly created child process to a systemd user scope.

Since: 0.60


VTE_SPAWN_REQUIRE_SYSTEMD_SCOPE

#define VTE_SPAWN_REQUIRE_SYSTEMD_SCOPE (1 << 27)

Use this as a spawn flag (together with flags from GSpawnFlags) in vte_pty_spawn_async().

Requires vte_pty_spawn_async() etc. to move the newly created child process to a systemd user scope; if that fails, the whole spawn fails.

This is supported on Linux only.

Since: 0.60

Property Details

The “fd” property

  “fd”                       gint

The file descriptor of the PTY master.

Owner: VtePty

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1


The “flags” property

  “flags”                    VtePtyFlags

Flags.

Owner: VtePty

Flags: Read / Write / Construct Only