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 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-negative 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 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.

SEE ALSO

       grantpt(), open(), ptsname(), unlockpt()

       The Base Definitions volume of POSIX.1‐2008, <fcntl.h>, <stdlib.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2013  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013  by  the
       Institute  of  Electrical  and  Electronics  Engineers,  Inc and The Open Group.  (This is
       POSIX.1-2008 with the  2013  Technical  Corrigendum  1  applied.)  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.unix.org/online.html .

       Any  typographical  or  formatting errors that appear in this page are most likely to have
       been introduced during the conversion of the source files to man page  format.  To  report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .