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
gchar * term Read / Write

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

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