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

NAME

6       posix_openpt - open a pseudo-terminal device
7

SYNOPSIS

9       #include <stdlib.h>
10       #include <fcntl.h>
11
12       int posix_openpt(int oflag);
13
14

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

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

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

116       None.
117

SEE ALSO

119       grantpt() , open() , ptsname() , unlockpt() , the Base Definitions vol‐
120       ume of IEEE Std 1003.1-2001, <fcntl.h>
121

123       Portions of this text are reprinted and reproduced in  electronic  form
124       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
125       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
126       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
127       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
128       event of any discrepancy between this version and the original IEEE and
129       The Open Group Standard, the original IEEE and The Open Group  Standard
130       is  the  referee document. The original Standard can be obtained online
131       at http://www.opengroup.org/unix/online.html .
132
133
134
135IEEE/The Open Group                  2003                      POSIX_OPENPT(P)
Impressum