huschi.net

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 (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 mas-
       ter  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 descrip-
       tion 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 repre-
       senting 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  per-
       missions, 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.  How-
       ever, consensus could not be reached, and it was felt that adding a new
       function would permit other implementations. The  posix_openpt()  func-
       tion 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 Electri-
       cal  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.ker-
       nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group                  2013                     POSIX_OPENPT(3P)