Vte PTY

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

## Synopsis

    enum                VtePtyFlags;
    enum                VtePtyError;
                        VtePty;
    VtePty *            vte_pty_new                         (VtePtyFlags flags,
                                                             GError **error);
    VtePty *            vte_pty_new_foreign                 (int fd,
                                                             GError **error);
    void                vte_pty_close                       (VtePty *pty);
    void                vte_pty_child_setup                 (VtePty *pty);
    int                 vte_pty_get_fd                      (VtePty *pty);
    gboolean            vte_pty_set_size                    (VtePty *pty,
                                                             int rows,
                                                             int columns,
                                                             GError **error);
    gboolean            vte_pty_get_size                    (VtePty *pty,
                                                             int *rows,
                                                             int *columns,
                                                             GError **error);
    void                vte_pty_set_term                    (VtePty *pty,
                                                             const char *emulation);
    gboolean            vte_pty_set_utf8                    (VtePty *pty,
                                                             gboolean utf8,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----VtePty

## Implemented Interfaces

VtePty implements GInitable.

## Properties

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

## Description

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

## Details

### enum VtePtyFlags

    typedef enum {
      VTE_PTY_NO_LASTLOG  = 1 << 0,
      VTE_PTY_NO_UTMP     = 1 << 1,
      VTE_PTY_NO_WTMP     = 1 << 2,
      VTE_PTY_NO_HELPER   = 1 << 3,
      VTE_PTY_NO_FALLBACK = 1 << 4,
      VTE_PTY_DEFAULT     = 0
    } VtePtyFlags;

`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

    typedef enum {
      VTE_PTY_ERROR_PTY_HELPER_FAILED = 0,
      VTE_PTY_ERROR_PTY98_FAILED
    } VtePtyError;

`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

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

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

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

`pty` : | a VtePty

Since 0.26

### vte_pty_child_setup ()

    void                vte_pty_child_setup                 (VtePty *pty);

FIXMEchpe

`pty` : | a VtePty

Since 0.26

### vte_pty_get_fd ()

    int                 vte_pty_get_fd                      (VtePty *pty);

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

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

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

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

`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

## Property Details

### The `"fd"` property

      "fd"                       gint                  : Read / Write / Construct Only

The file descriptor of the PTY master.

Allowed values: >= -1

Default value: -1

Since 0.26

### The `"flags"` property

      "flags"                    VtePtyFlags           : Read / Write / Construct Only

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

Since 0.26

### The `"term"` property

      "term"                     gchar*                : Read / Write

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

Default value: "xterm"

Since 0.26