Vte PTY

## 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 ()
VtePty * | vte_pty_new_foreign ()
void | vte_pty_close ()
void | vte_pty_child_setup ()
int | vte_pty_get_fd ()
gboolean | vte_pty_set_size ()
gboolean | vte_pty_get_size ()
void | vte_pty_set_term ()
gboolean | vte_pty_set_utf8 ()

## Properties

gint | fd | Read / Write / Construct Only
VtePtyFlags | flags | Read / Write / Construct Only
gchar * | term | Read / Write

## 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 ()

    VtePty *
    vte_pty_new (VtePtyFlags flags,
                 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_fork_command_full()` 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.

If GNOME PTY Helper is available and unless some of the `VTE_PTY_NO_LASTLOG`, `VTE_PTY_NO_UTMP` or `VTE_PTY_NO_WTMP` flags are passed in `flags` , the session is logged in the corresponding lastlog, utmp or wtmp system files. When passing `VTE_PTY_NO_HELPER` in `flags` , the GNOME PTY Helper is bypassed entirely.

When passing `VTE_PTY_NO_FALLBACK` in `flags` , and opening a PTY using the PTY helper fails, there will be no fallback to allocate a PTY using Unix98 PTY functions.

#### Parameters

flags | flags from VtePtyFlags |
error | return location for a GError, or `NULL`. | [allow-none]

#### Returns

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

[transfer full]

Since 0.26

### vte_pty_new_foreign ()

    VtePty *
    vte_pty_new_foreign (int fd,
                         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.

#### Parameters

fd | a file descriptor to the PTY. | [transfer full]
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]

Since 0.26

### vte_pty_close ()

    void
    vte_pty_close (VtePty *pty);

Cleans up the PTY, specifically any logging performed for the session. The file descriptor to the PTY master remains open.

#### Parameters

pty | a VtePty |

Since 0.26

### vte_pty_child_setup ()

    void
    vte_pty_child_setup (VtePty *pty);

FIXMEchpe

#### Parameters

pty | a VtePty |

Since 0.26

### 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 | (allow-none); return location to store a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on failure with `error` filled in

Since 0.26

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

Since 0.26

### vte_pty_set_term ()

    void
    vte_pty_set_term (VtePty *pty,
                      const char *emulation);

Sets what value of the TERM environment variable to set just after forking.

#### Parameters

pty | a VtePty |
emulation | the name of a terminal description, or `NULL`. | [allow-none]

Since 0.26

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

Since 0.26

## Types and Values

### enum VtePtyFlags

#### Members

VTE_PTY_NO_LASTLOG | don't record the session in lastlog |
VTE_PTY_NO_UTMP | don't record the session in utmp |
VTE_PTY_NO_WTMP | don't record the session in wtmp |
VTE_PTY_NO_HELPER | don't use the GNOME PTY helper to allocate the PTY |
VTE_PTY_NO_FALLBACK | when allocating the PTY with the PTY helper fails, don't fall back to try using PTY98 |
VTE_PTY_DEFAULT | the default flags |

Since 0.26

### enum VtePtyError

#### Members

VTE_PTY_ERROR_PTY_HELPER_FAILED | failure when using the GNOME PTY helper to allocate the PTY |
VTE_PTY_ERROR_PTY98_FAILED | failure when using PTY98 to allocate the PTY |

Since 0.26

### VtePty

    typedef struct _VtePty VtePty;

Since 0.26

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

Since 0.26

### The `“flags”` property

      “flags”                    VtePtyFlags

Controls how the session is recorded in lastlog, utmp, and wtmp, and whether to use the GNOME PTY helper.

Flags: Read / Write / Construct Only

Since 0.26

### The `“term”` property

      “term”                     gchar *

The value to set for the TERM environment variable just after forking.

Flags: Read / Write

Default value: "xterm"

Since 0.26