Top | ![]() |
![]() |
![]() |
![]() |
Vte PTYVte PTY — Functions for starting a new process on a new pseudo-terminal and for manipulating pseudo-terminals |
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 () |
void | vte_pty_spawn_with_fds_async () |
gboolean | vte_pty_spawn_finish () |
void | vte_pty_close () |
enum | VtePtyFlags |
enum | VtePtyError |
VtePty | |
#define | VTE_SPAWN_NO_PARENT_ENVV |
#define | VTE_SPAWN_NO_SYSTEMD_SCOPE |
#define | VTE_SPAWN_REQUIRE_SYSTEMD_SCOPE |
The terminal widget uses these functions to start commands with new controlling pseudo-terminals and to resize pseudo-terminals.
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.
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.
[constructor]
flags |
flags from VtePtyFlags |
|
cancellable |
a GCancellable, or |
[allow-none] |
error |
[allow-none] |
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]
fd |
a file descriptor to the PTY |
|
cancellable |
a GCancellable, or |
[allow-none] |
error |
[allow-none] |
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.
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.
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.
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
);
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.
pty |
a VtePty |
|
working_directory |
the name of a directory the command should start
in, or |
[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 |
[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 |
[allow-none][scope async] |
child_setup_data |
user data for |
[nullable][closure child_setup] |
child_setup_data_destroy |
a GDestroyNotify for |
[nullable][destroy child_setup_data] |
timeout |
a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely |
|
cancellable |
a GCancellable, or |
[allow-none] |
callback |
a GAsyncReadyCallback, or |
[nullable][scope async] |
user_data |
user data for |
[closure callback] |
Since: 0.48
void vte_pty_spawn_with_fds_async (VtePty *pty
,char const*working_directory
,char const* const*argv
,char const* const*envv
,int const*fds
,int n_fds
,int const*map_fds
,int n_map_fds
,GSpawnFlags spawn_flags
,GSpawnChildSetupFunc child_setup
,gpointer child_setup_data
,GDestroyNotify child_setup_data_destroy
,int timeout
,GCancellable *cancellable
,GAsyncReadyCallback callback
);
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 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 NULL
, 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 exec.
Note that all open file descriptors apart from those mapped as above will be closed in the child. (If you want to keep some other 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 manually.)
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.
pty |
a VtePty |
|
working_directory |
the name of a directory the command should start
in, or |
[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 |
[allow-none][array zero-terminated=1][element-type filename] |
fds |
an array of file descriptors, or |
[nullable][array length=n_fds][transfer none][scope call] |
n_fds |
the number of file descriptors in |
|
map_fds |
an array of integers, or |
[nullable][array length=n_map_fds][transfer none][scope call] |
n_map_fds |
the number of elements in |
|
spawn_flags |
flags from GSpawnFlags |
|
child_setup |
an extra child setup function to run in the child just before |
[allow-none][scope async] |
child_setup_data |
user data for |
[nullable][closure child_setup] |
child_setup_data_destroy |
a GDestroyNotify for |
[nullable][destroy child_setup_data] |
timeout |
a timeout value in ms, -1 for the default timeout, or G_MAXINT to wait indefinitely |
|
cancellable |
a GCancellable, or |
[allow-none] |
callback |
a GAsyncReadyCallback, or |
[nullable][scope async] |
user_data |
user data for |
[closure callback] |
Since: 0.62
gboolean vte_pty_spawn_finish (VtePty *pty
,GAsyncResult *result
,GPid *child_pid
);
Since: 0.48
Unused. Deprecated: 0.38 |
||
Unused. Deprecated: 0.38 |
||
Unused. Deprecated: 0.38 |
||
Unused. Deprecated: 0.38 |
||
Unused. Deprecated: 0.38 |
||
Do not start a new session for the child in
|
||
Do not set the PTY as the controlling TTY for the child
in |
||
the default flags |
#define VTE_SPAWN_NO_PARENT_ENVV (1 << 25)
Use this as a spawn flag (together with flags from GSpawnFlags) in
vte_pty_spawn_async()
.
Normally, the spawned process inherits the environment from the parent
process; when this flag is used, only the environment variables passed
to vte_pty_spawn_async()
etc. are passed to the child process.
#define VTE_SPAWN_NO_SYSTEMD_SCOPE (1 << 26)
Use this as a spawn flag (together with flags from GSpawnFlags) in
vte_pty_spawn_async()
.
Prevents vte_pty_spawn_async()
etc. from moving the newly created child
process to a systemd user scope.
Since: 0.60
#define VTE_SPAWN_REQUIRE_SYSTEMD_SCOPE (1 << 27)
Use this as a spawn flag (together with flags from GSpawnFlags) in
vte_pty_spawn_async()
.
Requires vte_pty_spawn_async()
etc. to move the newly created child
process to a systemd user scope; if that fails, the whole spawn fails.
This is supported on Linux only.
Since: 0.60
“fd”
property“fd” gint
The file descriptor of the PTY master.
Owner: VtePty
Flags: Read / Write / Construct Only
Allowed values: >= -1
Default value: -1