Vte PTY: VTE Reference Manual

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

## Functions

VtePty * | vte_pty_new_sync ()
VtePty * | vte_pty_new_foreign_sync ()
void | vte_pty_child_setup ()
int | vte_pty_get_fd ()
gboolean | vte_pty_set_size ()
gboolean | vte_pty_get_size ()
gboolean | vte_pty_set_utf8 ()
void | vte_pty_spawn_async ()
void | vte_pty_spawn_with_fds_async ()
gboolean | vte_pty_spawn_finish ()
void | vte_pty_close ()

## Properties

int | fd | Read / Write / Construct Only
VtePtyFlags | flags | Read / Write / Construct Only

## Types and Values

enum | VtePtyFlags
enum | VtePtyError
| VtePty
#define | VTE_SPAWN_NO_PARENT_ENVV
#define | VTE_SPAWN_NO_SYSTEMD_SCOPE
#define | VTE_SPAWN_REQUIRE_SYSTEMD_SCOPE

## 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` . | [nullable][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 man:execve(2). Note also that no file descriptor may be mapped to stdin, stdout, or stderr (file descriptors 0, 1, or 2), since these will be assigned to the PTY. All open file descriptors apart from those mapped as above will be closed when `execve()` is called.

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` . | [nullable][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”                       int

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