PTY(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💖 NAME 💖

okay bestie, welcome to the PTY(3) page from the Library Functions Manual ✨ this is all about openpty, forkpty — auxiliary functions to obtain a pseudo-terminal 🫶

🌸 LIBRARY 🌸

System Utilities Library (libutil, -lutil) — yes, that means you link with -lutil, iykyk 💅

✨ SYNOPSIS ✨

#include <sys/types.h>
#include <sys/ioctl.h>
#include <termios.h>
#include <libutil.h>

int
openpty(int *amaster, int *aslave, char *name, struct termios *termp,
    struct winsize *winp);

int
forkpty(int *amaster, char *name, struct termios *termp,
    struct winsize *winp);

🦋 DESCRIPTION 🦋

so openpty() is doing main character work: it attempts to obtain the next available pseudo-terminal from the system (peep pty(4) for the lore) 👑

if it successfully finds one, it then changes the ownership of the slave device to the real UID of the current process, changes the group membership to the group “tty” (if such a group exists in the system), sets the access permissions for reading and writing by the owner, and for writing by the group, and invalidates any current use of the line by calling revoke(2) 🔥

if the argument name is not NULL, openpty() copies the pathname of the slave pty to this area. the caller is responsible for allocating the required space in this array — not me, not the pty, you bestie 🙈

if the arguments termp or winp are not NULL, openpty() initializes the termios and window size settings from the structures these arguments point to, respectively 🌈

upon return, the open file descriptors for the master and slave side of the pty are returned in the locations pointed to by amaster and aslave, respectively ✨

forkpty() is like openpty() with extra drama: first it calls openpty() to obtain the next available pseudo-terminal from the system. upon success, it forks off a new process 🧚 in the child process, it closes the descriptor for the master side of the pty, and calls login_tty(3) for the slave pty. in the parent process, it closes the descriptor for the slave side of the pty. the arguments amaster, name, termp, and winp have the same meaning as described for openpty() 💜

🎀 RETURN VALUES 🎀

openpty() returns 0 on success, or -1 on failure.

forkpty() returns -1 on failure, 0 in the slave process, and the process ID of the slave process in the parent process. periodt 💅

🌟 ERRORS 🌟

openpty() may fail and set the global variable errno for any of the errors specified for the grantpt(3), posix_openpt(2), ptsname(3), and unlockpt(3) functions and the revoke(2) system call 😭

in addition to this, forkpty() may set it to any value as described for fork(2) 💀

🍓 SEE ALSO 🍓

👑 HISTORY 👑

the openpty() and forkpty() functions first appeared in 4.3BSD-Reno — vintage icon behavior, no cap ⭐

💀 BUGS 💀

okay this is the important warning bestie: openpty() writes the slave terminal's name to name, but does not check that sufficient space is available. it is advisable to use ptsname(3) instead 🚨

xoxo, your Debian bestie — page dated June 2, 2018, filed under PTY(3) 💅🫶

📦 where this page comes from