posix_openpt(3p)

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
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
36              If  set  posix_openpt()  shall  not cause the terminal device to
37              become the controlling terminal for the process.
38
39
40       The behavior of other values for the oflag argument is unspecified.
41

RETURN VALUE

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

ERRORS

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

EXAMPLES

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

APPLICATION USAGE

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

RATIONALE

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

FUTURE DIRECTIONS

122       None.
123

COPYRIGHT

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