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

NAME

12       posix_openpt — open a pseudo-terminal device
13

SYNOPSIS

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

DESCRIPTION

21       The posix_openpt() function shall establish a connection between a mas‐
22       ter  device  for  a  pseudo-terminal  and  a  file descriptor. The file
23       descriptor shall be  allocated  as  described  in  Section  2.14,  File
24       Descriptor Allocation and can be used by other I/O functions that refer
25       to that pseudo-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       file descriptor for a master pseudo-terminal device and return  a  non-
43       negative  integer representing the 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
106           mfdp = open("/dev/ptmx", oflag );
107           if (mfdp < 0)
108               return -1;
109

FUTURE DIRECTIONS

111       None.
112

SEE ALSO

114       Section 2.14, File Descriptor Allocation, grantpt(), open(), ptsname(),
115       unlockpt()
116
117       The Base Definitions volume of POSIX.1‐2017, <fcntl.h>, <stdlib.h>
118

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