POSIX_OPENPT(3P)                                    POSIX Programmer's Manual                                   POSIX_OPENPT(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult 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 is 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 master pseudo-terminal device and return a non-nega-
       tive  integer  representing  the lowest numbered unused file descriptor. Otherwise, -1 shall be returned and errno set to
       indicate the error.

ERRORS
       The posix_openpt() function shall fail if:

       EMFILE {OPEN_MAX} file descriptors are currently open in the calling process.

       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(slave, 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()  func-
       tions.

       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.

SEE ALSO
       grantpt(), open(), ptsname(), unlockpt(), the Base Definitions volume of IEEE Std 1003.1-2001, <fcntl.h>

COPYRIGHT
       Portions  of  this  text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for
       Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6,  Copy-
       right (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any
       discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open  Group
       Standard   is   the   referee   document.   The   original   Standard   can   be   obtained  online  at  http://www.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                              POSIX_OPENPT(3P)