1POSIX_OPENPT(3P)           POSIX Programmer's Manual          POSIX_OPENPT(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       posix_openpt — open a pseudo-terminal device
14

SYNOPSIS

16       #include <stdlib.h>
17       #include <fcntl.h>
18
19       int posix_openpt(int oflag);
20

DESCRIPTION

22       The posix_openpt() function shall establish a connection between a mas‐
23       ter  device  for  a  pseudo-terminal  and  a  file descriptor. The file
24       descriptor is used by other I/O functions that refer  to  that  pseudo-
25       terminal.
26
27       The  file  status flags and file access modes of the open file descrip‐
28       tion shall be set according to the value of oflag.
29
30       Values for oflag are constructed by a  bitwise-inclusive  OR  of  flags
31       from the following list, defined in <fcntl.h>:
32
33       O_RDWR      Open for reading and writing.
34
35       O_NOCTTY    If  set  posix_openpt() shall not cause the terminal device
36                   to become the controlling terminal for the process.
37
38       The behavior of other values for the oflag argument is unspecified.
39

RETURN VALUE

41       Upon successful completion, the posix_openpt() function  shall  open  a
42       master  pseudo-terminal device and return a non-negative integer repre‐
43       senting the lowest numbered unused file descriptor. Otherwise, −1 shall
44       be returned and errno set to indicate the error.
45

ERRORS

47       The posix_openpt() function shall fail if:
48
49       EMFILE All  file  descriptors  available  to  the process are currently
50              open.
51
52       ENFILE The maximum allowable number of files is currently open  in  the
53              system.
54
55       The posix_openpt() function may fail if:
56
57       EINVAL The value of oflag is not valid.
58
59       EAGAIN Out of pseudo-terminal resources.
60
61       ENOSR  Out of STREAMS resources.
62
63       The following sections are informative.
64

EXAMPLES

66   Opening  a Pseudo-Terminal and Returning the Name of the Slave Device and a
67       File Descriptor
68           #include <fcntl.h>
69           #include <stdio.h>
70
71           int masterfd, slavefd;
72           char *slavedevice;
73
74           masterfd = posix_openpt(O_RDWR|O_NOCTTY);
75
76           if (masterfd == -1
77               || grantpt (masterfd) == -1
78               || unlockpt (masterfd) == -1
79               || (slavedevice = ptsname (masterfd)) == NULL)
80               return -1;
81
82           printf("slave device is: %s\n", slavedevice);
83
84           slavefd = open(slavedevice, O_RDWR|O_NOCTTY);
85           if (slavefd < 0)
86               return -1;
87

APPLICATION USAGE

89       This function is a method for portably obtaining a file descriptor of a
90       master  terminal  device  for  a  pseudo-terminal.  The  grantpt()  and
91       ptsname() functions can be used to manipulate mode and  ownership  per‐
92       missions, and to obtain the name of the slave device, respectively.
93

RATIONALE

95       The  standard  developers  considered  the  matter  of adding a special
96       device for cloning master pseudo-terminals: the /dev/ptmx device.  How‐
97       ever, consensus could not be reached, and it was felt that adding a new
98       function would permit other implementations. The  posix_openpt()  func‐
99       tion is designed to complement the grantpt(), ptsname(), and unlockpt()
100       functions.
101
102       On implementations supporting the /dev/ptmx clone device,  opening  the
103       master device of a pseudo-terminal is simply:
104
105           mfdp = open("/dev/ptmx", oflag );
106           if (mfdp < 0)
107               return -1;
108

FUTURE DIRECTIONS

110       None.
111

SEE ALSO

113       grantpt(), open(), ptsname(), unlockpt()
114
115       The Base Definitions volume of POSIX.1‐2008, <fcntl.h>, <stdlib.h>
116

118       Portions  of  this text are reprinted and reproduced in electronic form
119       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
120       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
121       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
122       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
123       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
124       event of any discrepancy between this version and the original IEEE and
125       The Open Group Standard, the original IEEE and The Open Group  Standard
126       is  the  referee document. The original Standard can be obtained online
127       at http://www.unix.org/online.html .
128
129       Any typographical or formatting errors that appear  in  this  page  are
130       most likely to have been introduced during the conversion of the source
131       files to man page format. To report such errors,  see  https://www.ker‐
132       nel.org/doc/man-pages/reporting_bugs.html .
133
134
135
136IEEE/The Open Group                  2013                     POSIX_OPENPT(3P)
Impressum