Class: Vte::Pty

Inherits:
Object
  • Object
show all
Defined in:
lib/vte3/pty.rb

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ Vte::Pty

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.

Parameters:

  • flags (Vte::PtyFlags) —

    flags from Vte::PtyFlags

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil



20
21
22
23
24
25
26
27
 
# File 'lib/vte3/pty.rb', line 20

def initialize(*args)
  case args[0]
  when PtyFlags
    initialize_new_sync(*args)
  else
    initialize_raw(*args)
  end
end

Instance Method Details

#child_setup ⇒ nil

Returns:

  • (nil)

#close ⇒ nil

Since 0.42 this is a no-op.

Returns:

  • (nil)

#fd ⇒ Integer

The file descriptor of the PTY master.

Returns:

  • (Integer) —

    fd

#fd=(fd) ⇒ Integer

The file descriptor of the PTY master.

Parameters:

  • fd (Integer)

Returns:

  • (Integer) —

    fd

  • (Integer) —

    fd

#flags ⇒ Vte::PtyFlags

Flags.

Returns:

#flags=(flags) ⇒ Vte::PtyFlags

Flags.

Parameters:

Returns:

#get_size(rows, columns) ⇒ Boolean

Reads the pseudo terminal's window size.

If getting the window size failed, error will be set to a #GIOError.

Parameters:

  • rows (Integer) —

    a location to store the number of rows, or nil

  • columns (Integer) —

    a location to store the number of columns, or nil

Returns:

  • (Boolean) —

    true on success, false on failure with error filled in

#initialize_raw ⇒ Vte::Pty

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.

Parameters:

  • flags (Vte::PtyFlags) —

    flags from Vte::PtyFlags

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

Returns:

  • (Vte::Pty) —

    a new Vte::Pty, or nil on error with error filled in




# File 'lib/vte3/pty.rb', line 19

#set_size(rows, columns) ⇒ Boolean

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:

  • rows (Integer) —

    the desired number of rows

  • columns (Integer) —

    the desired number of columns

Returns:

  • (Boolean) —

    true on success, false on failure with error filled in

#size ⇒ Object 



30
31
32
33
34
35
36
37
 
# File 'lib/vte3/pty.rb', line 30

def size
  succeeded, rows, columns = size_raw
  if succeeded
    [rows, columns]
  else
    nil
  end
end

#size_raw ⇒ Object 



29
 
# File 'lib/vte3/pty.rb', line 29

alias_method :size_raw, :size

#spawn_async(working_directory, argv, envv, spawn_flags, child_setup, child_setup_data, child_setup_data_destroy, timeout, cancellable, callback, user_data) ⇒ nil

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:

  • working_directory (String) —

    the name of a directory the command should start in, or nil to use the current working directory

  • argv (Array<Vte::filename>) —

    child's argument vector

  • envv (Array<Vte::filename>) —

    a list of environment variables to be added to the environment before starting the process, or nil

  • spawn_flags (GLib::SpawnFlags) —

    flags from GSpawn::Flags

  • child_setup (GLib::SpawnChildSetupFunc) —

    an extra child setup function to run in the child just before exec(), or nil

  • child_setup_data (GObject) —

    user data for child_setup, or nil

  • child_setup_data_destroy (GLib::DestroyNotify) —

    a GDestroy::Notify for child_setup_data, or nil

  • timeout (Integer) —

    a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

  • callback (Gio::AsyncReadyCallback) —

    a GAsync::ReadyCallback, or nil

  • user_data (GObject) —

    user data for callback

Returns:

  • (nil)

#spawn_finish(result, child_pid) ⇒ Boolean

Returns true on success, or false on error with error filled in.

Parameters:

  • result (Gio::AsyncResult) —

    a GAsync::Result

  • child_pid (GLib::Pid) —

    a location to store the child PID, or nil

Returns:

  • (Boolean) —

    true on success, or false on error with error filled in

#spawn_with_fds_async(working_directory, argv, envv, fds, n_fds, map_fds, n_map_fds, spawn_flags, child_setup, child_setup_data, child_setup_data_destroy, timeout, cancellable, callback, user_data) ⇒ nil

Starts the specified command under the pseudo-terminal pty. The argv and envv lists should be nil-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 nil, 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:

  • working_directory (String) —

    the name of a directory the command should start in, or nil to use the current working directory

  • argv (Array<Vte::filename>) —

    child's argument vector

  • envv (Array<Vte::filename>) —

    a list of environment variables to be added to the environment before starting the process, or nil

  • fds (Array<Integer>) —

    an array of file descriptors, or nil

  • n_fds (Integer) —

    the number of file descriptors in fds, or 0 if fds is nil

  • map_fds (Array<Integer>) —

    an array of integers, or nil

  • n_map_fds (Integer) —

    the number of elements in map_fds, or 0 if map_fds is nil

  • spawn_flags (GLib::SpawnFlags) —

    flags from GSpawn::Flags

  • child_setup (GLib::SpawnChildSetupFunc) —

    an extra child setup function to run in the child just before exec(), or nil

  • child_setup_data (GObject) —

    user data for child_setup, or nil

  • child_setup_data_destroy (GLib::DestroyNotify) —

    a GDestroy::Notify for child_setup_data, or nil

  • timeout (Integer) —

    a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely

  • cancellable (Gio::Cancellable) —

    a #GCancellable, or nil

  • callback (Gio::AsyncReadyCallback) —

    a GAsync::ReadyCallback, or nil

  • user_data (GObject) —

    user data for callback

Returns:

  • (nil)

#utf8=(utf8) ⇒ Boolean

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:

  • utf8 (Boolean) —

    whether or not the pty is in UTF-8 mode

Returns:

  • (Boolean) —

    true on success, false on failure with error filled in