NAME

ptyopen, ptysystem, ptyexecvp, ptyclose − pty utilities

SYNOPSIS

#include <codelibs/ptyopen.h>
 int ptyopen(const char *&mastername, const char *&slavename,
int openmode = O_RDWR);
int ptyclose(int filedes, const char *slavename, int waitstatus = 0);
 int ptyexecvp(const char *commandfile, const char *commandargv[],
const char *slavepty, boolean nohup = FALSE, int uid = -1);
int ptysystem(const char *command, const char *slavepty,
boolean nohup = FALSE, int uid = -1);
 CC ... -lcodelibs

DESCRIPTION

This package makes managing pseudo terminals (ptys) very easy.  (Please see pty(4) for more information about ptys).

ptyopen

Scans through the /dev/ptym directory until either an unused master pty is found or no more ptys are available.  When an unused master pty is found, it is opened (via open(2)) with mode openmode (usually O_RDWR).  The file descriptor obtained is returned as the return value (see below).  If possible (i.e., the calling process has read and write permission), an entry is made in /etc/utmp.  The complete path name of the master device is returned via mastername as a pointer to a static buffer.  Slavename is set to a static buffer which has the complete path of the slave device - you will need this to attach a process’ I/O to the slave. 

Return values greater than or equal to 0 indicate success; the return value is the file descriptor associated with the master pty.  Return values less than 0 indicate failure and the reason why is in the global errno (see errno(2)). If errno is zero, the routine could not find an unused pty. 

ptyclose

Assumes that fdes is a file descriptor returned by ptyopen and closes it via close(2). In addition, if possible the entry in /etc/utmp is updated to show the pty as being unused. Slavename is a pointer to the slave pty’s name, as returned by ptyopen. Waitstatus is the exit status that you want to be put in /etc/utmp, as returned by wait(2).

Ptyclose returns the value that the close(2) call returned.

ptysystem

This routine causes “sh -c command” to be executed while attached to the pty defined by slavename (the slave pty’s name, as returned by ptyopen). If possible, the /etc/utmp entry is updated with the child’s process id.

Unlike system(3C), this call returns immediately after forking the child; the return value is the process id of the child. If nohup is non-zero, the signal SIGCLD is set to be ignored (which allows you to close the master side of the pty without terminating the process attached to the slave side).  If uid is not -1, the child will attempt to do a setuid(2).

ptyexecvp

This is identical to ptysystem except that the execvp(2) system call is used after the fork to exec the process. Again, the return value of ptyexecvp is the process id of the child process. 

NOTES

Mastername and slavename are contained in a static buffer, which is overwritten on each call to ptyopen. 

Utmpnam(3C) (with "/etc/utmp" as the file) is called each time ptyopen, ptysystem, or ptyexecvp is called. 

FILES

/etc/utmp

SEE ALSO

close(2), errno(2), exec(2), getut(3C), open(2), system(3C), pty(7), utmp(4).

  —