forkpty(3)                                                   forkpty(3)

  openpty()

  NAME

    openpty(), forkpty - open pseudo terminal

  SYNOPSIS

    #include 
    #include 
    #include 
    #include 

    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

    The function openpty() attempts to obtain the next pseudo terminal from
    the system (see pty(4)). If it successfully finds one, it subsequently
    tries to change the ownership of the subordinate (also called slave)
    device to the real user identifier (UID) of the current process, the group
    membership to the group tty (if such a group exists in the system), the
    access permissions for reading and writing by the owner, and for writing
    by the group.

    If the argument name is not NULL, openpty() copies the path name of the
    subordinate pty to this area. The caller is responsible for allocating the
    required space in this array.

    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 side of the pty and
    the subordinate side of the pty are returned in the locations pointed to
    by amaster and aslave, respectively.

    The forkpty() function first 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 prepares the subordinate side for a new login session. In the
    parent process, it closes the descriptor for the subordinate side of the
    pty. The arguments amaster, name, termp, and winp have the same meaning as
    described for openpty().

  RETURN VALUES

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

    The forkpty() function returns -1 on failure, or on success, returns 0 in
    the subordinate process, and the process ID of the child process in the
    parent process.

  ERRORS

    On failure, openpty() will set the global variable errno to ENOENT.

    In addition to this, forkpty() may set it to any value described for
    fork(2).

  NOTES

    The calling process must have an effective UID of superuser in order to
    perform all the intended actions. No notification will occur if openpty()
    or forkpty failed to proceed with one of the described steps, as long as
    they could at least allocate the pty and, in the case of forkpty(), create
    the new process.

  SEE ALSO

    chmod(2)

    chown(2)

    fork(2)

    getuid(2)

    open(2)

    pty(4)

    termios(4)

  USAGE NOTES

    All of these functions are thread safe.

    None of these functions are async-signal safe.