← Index

x/sys/pty

Pty: pseudo-terminals, and a program run on one.

ioctl goes by syscall, never the fixed-signature ffi door: it is variadic.

A new terminal’s window is set by the child as it attaches: Darwin loses one set on the master first.

Class Pty

A pseudo-terminal: (Pty open) a master and the slave’s path, (Pty window! fd cols rows) its size, (Pty attach! path cols rows) a forked child’s controlling terminal, (Pty fork cols rows) the three together as forkpty(3) does, and (Pty spawn program args cols rows) a program run on one.

The master answers as given, blocking: a poll loop makes it non-blocking with (Sys nonblock! master), which reaches fcntl as a syscall for the reason window! reaches ioctl as one.

(Pty %c name)

The libc entry point named, resolved now.

Parameters:

• name : STRING — A libc function

Returns: POINTER — Its address

(Pty %call name . args)

A libc call’s int answer, sign-folded: -1 is an error.

Parameters:

• name : STRING — A libc function
• args : LIST — Its arguments

Returns: INTEGER — The answer

(Pty %ioctl fd request arg)

ioctl(2) as a syscall, sign-folded: -1 when this platform’s table has no ioctl.

Parameters:

• fd : INTEGER — Descriptor
• request : INTEGER — The request number
• arg : ANY — Its argument: an integer or a buffer

Returns: INTEGER — 0, or negative on error

(Pty tiocswinsz)

The TIOCSWINSZ ioctl request for this OS.

Returns: INTEGER — The request

(Pty tiocsctty)

The TIOCSCTTY ioctl request for this OS.

Returns: INTEGER — The request

(Pty open)

A new pseudo-terminal pair: its master, opened read-write and not as this process’s controlling terminal, and the path of its slave, granted and unlocked. Answers nil when the system gives none.

Returns: ANY — (MASTER . SLAVE-PATH), or nil

(Pty window! fd cols rows)

Set the terminal’s window, struct winsize’s rows and columns with no pixel size. Set on the master, the kernel signals the program’s process group with SIGWINCH. Answers #f when the ioctl fails.

On Darwin a window set on a master whose slave no one has open is lost: a new terminal’s first window is set by attach!, from the child.

Parameters:

• fd : INTEGER — The master, or the slave
• cols : INTEGER — Columns
• rows : INTEGER — Rows

Returns: BOOL — Whether the window was set

(Pty attach! path cols rows)

In a forked child: a session of its own, the slave opened as its controlling terminal with its window set, and made its standard input, output and error. Answers #f, having changed nothing past the new session, when the slave cannot be opened.

Parameters:

• path : STRING — The slave’s path, as open gives it
• cols : INTEGER — Columns
• rows : INTEGER — Rows

Returns: BOOL — Whether the slave is now the terminal

(Pty fork cols rows . close)

Fork a child onto a new pseudo-terminal of cols by rows, as forkpty(3) does. The parent gets (PID . MASTER); the child, attached, gets (0 . -1), having closed the master and every descriptor in close. Answers nil when no terminal or no child can be had. A child that cannot open the slave exits 127.

Parameters:

• cols : INTEGER — Columns
• rows : INTEGER — Rows
• close : LIST — Descriptors the child closes

Returns: ANY — (PID . MASTER) in the parent, (0 . -1) in the child, or nil

(Pty spawn program args cols rows . close)

Run program on a new pseudo-terminal of cols by rows: its standard input, output and error, and its controlling terminal. A child the program cannot replace exits 127.

What the program writes is read from the master; what is written to the master is its input. (Sys wait pid) collects it.

Parameters:

• program : STRING — The program, found on PATH as execvp finds it
• args : LIST — Its arguments, after its name
• cols : INTEGER — Columns
• rows : INTEGER — Rows
• close : LIST — Descriptors the child closes

Returns: ANY — (PID . MASTER), or nil when no terminal or no child can be had