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 {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 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 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, Copyright (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.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                     POSIX_OPENPT(3P)