# posix_openpt

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           posix_openpt — open a pseudo-terminal device
    


## SYNOPSIS



           #include <stdlib.h>
           #include <fcntl.h>
    
           int posix_openpt(int _oflag_);
    


## DESCRIPTION



           The _posix_openpt_() function shall establish a connection between a
           master device for a pseudo-terminal and a file descriptor. The
           file descriptor shall be allocated as described in _Section 2.14_ ,
           _File Descriptor Allocation_ and can be used by other I/O functions
           that refer to that pseudo-terminal.
    
           The file status flags and file access modes of the open file
           description shall be set according to the value of _oflag_.
    
           Values for _oflag_ are constructed by a bitwise-inclusive OR of
           flags from the following list, defined in _< fcntl.h>_:
    
           O_RDWR      Open for reading and writing.
    
           O_NOCTTY    If set _posix_openpt_() shall not cause the terminal
                       device to become the controlling terminal for the
                       process.
    
           The behavior of other values for the _oflag_ argument is
           unspecified.
    


## RETURN VALUE



           Upon successful completion, the _posix_openpt_() function shall open
           a file descriptor for a master pseudo-terminal device and return a
           non-negative integer representing the file descriptor. Otherwise,
           -1 shall be returned and _errno_ set to indicate the error.
    


## ERRORS



           The _posix_openpt_() function shall fail if:
    
           **EMFILE** All file descriptors available to the process are currently
                  open.
    
           **ENFILE** The maximum allowable number of files is currently open in
                  the system.
    
           The _posix_openpt_() function may fail if:
    
           **EINVAL** The value of _oflag_ is not valid.
    
           **EAGAIN** Out of pseudo-terminal resources.
    
           **ENOSR** Out of STREAMS resources.
    
           _The following sections are informative._
    


## EXAMPLES



       **Opening a Pseudo-Terminal and Returning the Name of the Slave Device**
           **and a File Descriptor**
               #include <fcntl.h>
               #include <stdio.h>
    
               int masterfd, slavefd;
               char *slavedevice;
    
               masterfd = posix_openpt(O_RDWR|O_NOCTTY);
    
               if (masterfd == -1
                   || grantpt (masterfd) == -1
                   || unlockpt (masterfd) == -1
                   || (slavedevice = ptsname (masterfd)) == NULL)
                   return -1;
    
               printf("slave device is: %s\n", slavedevice);
    
               slavefd = open(slavedevice, O_RDWR|O_NOCTTY);
               if (slavefd < 0)
                   return -1;
    


## APPLICATION USAGE



           This function is a method for portably obtaining a file descriptor
           of a master terminal device for a pseudo-terminal. The _grantpt_()
           and _ptsname_() functions can be used to manipulate mode and
           ownership permissions, and to obtain the name of the slave device,
           respectively.
    


## RATIONALE



           The standard developers considered the matter of adding a special
           device for cloning master pseudo-terminals: the **/dev/ptmx** device.
           However, consensus could not be reached, and it was felt that
           adding a new function would permit other implementations. The
           _posix_openpt_() function is designed to complement the _grantpt_(),
           _ptsname_(), and _unlockpt_() functions.
    
           On implementations supporting the **/dev/ptmx** clone device, opening
           the master device of a pseudo-terminal is simply:
    
               mfdp = open("/dev/ptmx", oflag );
               if (mfdp < 0)
                   return -1;
    


## FUTURE DIRECTIONS



           None.
    


* * *