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 {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()
       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 .