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 ()
gboolean | vte_pty_spawn_finish ()
void | vte_pty_close ()

## Properties

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

## Types and Values

enum | VtePtyFlags
enum | VtePtyError
| VtePty

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

[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. | [transfer full]
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);

FIXMEchpe

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

[transfer none]

### 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,
                         gpointer user_data);

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 that `G_SPAWN_DO_NOT_REAP_CHILD` will always be added to `spawn_flags` .

Note that all open file descriptors will be closed in the child. If you want to keep some 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.

See `vte_pty_new()`, `g_spawn_async()` 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]
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`. | [closure child_setup]
child_setup_data_destroy | a GDestroyNotify for `child_setup_data` , or `NULL`. | [destroy child_setup_data]
timeout | a timeout value in ms, or -1 to wait indefinitely |
cancellable | a GCancellable, or `NULL`. | [allow-none]

Since: 0.48

### vte_pty_spawn_finish ()

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

#### 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_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;

## Property Details

### The `“fd”` property

      “fd”                       gint

The file descriptor of the PTY master.

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1

### The `“flags”` property

      “flags”                    VtePtyFlags

Flags.

Flags: Read / Write / Construct Only