1 POSIX_OPENPT(3C)         Standard C Library Functions         POSIX_OPENPT(3C)
   2 
   3 NAME
   4      posix_openpt - open a pseudo-terminal manager device
   5 
   6 SYNOPSIS
   7      #include <stdlib.h>
   8      #include <fcntl.h>
   9 
  10      int
  11      posix_openpt(int oflag);
  12 
  13 DESCRIPTION
  14      The posix_openpt() function establishes a connection between a manager
  15      device for a pseudo-terminal and a file descriptor.  The file descriptor
  16      is used by other I/O functions that refer to that pseudo-terminal.
  17 
  18      The file status flags and file access modes of the open file description
  19      are set according to the value of oflag.
  20 
  21      Values for oflag are constructed by a bitwise-inclusive OR of flags from
  22      the following list, defined in fcntl.h(3HEAD):
  23 
  24      O_RDWR  Open for reading and writing.
  25 
  26      O_NOCTTY
  27              If set, posix_openpt() does not cause the terminal device to
  28              become the controlling terminal for the process.
  29 
  30      The behavior of other values for the oflag argument is unspecified.
  31 
  32 RETURN VALUES
  33      The posix_getopt() function opens a manager pseudo-terminal device and,
  34      if successful, returns a non-negative integer representing the lowest
  35      numbered unused file descriptor ; otherwise, the value -1 is returned and
  36      the global variable errno is set to indicate the error.
  37 
  38 EXAMPLES
  39      Example 1 Open a pseudo-terminal.
  40 
  41      The following example opens a pseudo-terminal and returns the name of the
  42      subsidiary device and a file descriptor.
  43 
  44            #include <fcntl.h>
  45            #include <stdio.h>
  46            #include <err.h>
  47 
  48            int managerfd, subsidiaryfd;
  49            char *subsidiarydevice;
  50 
  51            if ((managerfd = posix_openpt(O_RDWR|O_NOCTTY)) < 0)      {
  52                    err(1, "opening pseudo-terminal manager");
  53            }
  54 
  55            if (grantpt(managerfd) != 0 ||
  56                unlockpt(managerfd) != 0 ||
  57                (subsidiarydevice = ptsname(managerfd)) == NULL) {
  58                    (void) close(managerfd);
  59                    err(1, "locating pseudo-terminal subsidiary");
  60            }
  61 
  62            printf("subsidiary device is: %s\n", subsidiarydevice);
  63 
  64            if ((subsidiaryfd = open(subsidiary, O_RDWR|O_NOCTTY)) < 0) {
  65                    err(1, "opening pseudo-terminal subsidiary");
  66            }
  67 
  68 ERRORS
  69      The posix_openpt() function will fail if:
  70 
  71      EMFILE             {OPEN_MAX} file descriptors are currently open in the
  72                         calling process.
  73 
  74      ENFILE             The maximum allowable number of files is currently
  75                         open in the system.
  76 
  77      The posix_openpt() function may fail if:
  78 
  79      EINVAL             The value of oflag is not valid.
  80 
  81      EAGAIN             The system has run out of pseudo-terminal resources.
  82 
  83      ENOSR              The system has run out of STREAMS resources.
  84 
  85 USAGE
  86      This function provides a portable method for obtaining the file
  87      descriptor of a manager terminal device for a pseudo-terminal, as opposed
  88      to using open(2) on the ptm(7D) device which is system-specific.
  89 
  90      The grantpt(3C) function can be used to manipulate the mode and ownership
  91      permissions of the subsidiary device.  The ptsname(3C) function can be
  92      used to obtain the name of the subsidiary device.
  93 
  94 INTERFACE STABILITY
  95      Committed
  96 
  97 MT LEVEL
  98      MT-Safe
  99 
 100 SEE ALSO
 101      open(2), grantpt(3C), ptsname(3C), unlockpt(3C), attributes(5),
 102      standards(5), ptm(7D), pts(7D)
 103 
 104 illumos                        February 5, 2022                        illumos