]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) OpenBSD Group |
2 | .\" All rights reserved. | |
3 | .\" | |
491b7776 | 4 | .\" %%%LICENSE_START(BSD_3_CLAUSE_UCB) |
fea681da MK |
5 | .\" Redistribution and use in source and binary forms, with or without |
6 | .\" modification, are permitted provided that the following conditions | |
7 | .\" are met: | |
8 | .\" 1. Redistributions of source code must retain the above copyright | |
9 | .\" notice, this list of conditions and the following disclaimer. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. Neither the name of the University nor the names of its contributors | |
14 | .\" may be used to endorse or promote products derived from this software | |
15 | .\" without specific prior written permission. | |
16 | .\" | |
17 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
18 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
19 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
20 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
21 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
22 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
23 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
24 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
25 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
26 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
27 | .\" SUCH DAMAGE. | |
8c9302dc | 28 | .\" %%%LICENSE_END |
fea681da MK |
29 | .\" |
30 | .\" Converted into a manpage again by Martin Schulze <joey@infodrom.org> | |
31 | .\" | |
32 | .\" Added -lutil remark, 030718 | |
33 | .\" | |
8b3f5f59 | 34 | .TH OPENPTY 3 2010-06-13 "GNU" "Linux Programmer's Manual" |
fea681da | 35 | .SH NAME |
1285ff3d | 36 | openpty, login_tty, forkpty \- terminal utility functions |
fea681da | 37 | .SH SYNOPSIS |
b9f02710 | 38 | .nf |
fea681da | 39 | .B #include <pty.h> |
fea681da | 40 | .sp |
c13182ef | 41 | .BI "int openpty(int *" amaster ", int *" aslave ", char *" name , |
671c2ab4 EB |
42 | .BI " const struct termios *" termp , |
43 | .BI " const struct winsize *" winp ); | |
fea681da | 44 | .sp |
671c2ab4 EB |
45 | .BI "pid_t forkpty(int *" amaster ", char *" name , |
46 | .BI " const struct termios *" termp , | |
47 | .BI " const struct winsize *" winp ); | |
fea681da | 48 | .sp |
cbaed691 MK |
49 | .B #include <utmp.h> |
50 | .sp | |
51 | .BI "int login_tty(int " fd ); | |
52 | .sp | |
7c2bff69 | 53 | Link with \fI\-lutil\fP. |
b9f02710 | 54 | .fi |
fea681da MK |
55 | .SH DESCRIPTION |
56 | The | |
63aa9df0 | 57 | .BR openpty () |
b218b023 | 58 | function finds an available pseudoterminal and returns file descriptors |
fea681da MK |
59 | for the master and slave in |
60 | .I amaster | |
61 | and | |
62 | .IR aslave . | |
63 | If | |
64 | .I name | |
65 | is not NULL, the filename of the slave is returned in | |
66 | .IR name . | |
67 | If | |
68 | .I termp | |
69 | is not NULL, the terminal parameters of the slave will be set to the | |
70 | values in | |
71 | .IR termp . | |
72 | If | |
73 | .I winp | |
74 | is not NULL, the window size of the slave will be set to the values in | |
75 | .IR winp . | |
76 | ||
77 | The | |
63aa9df0 | 78 | .BR login_tty () |
1285ff3d | 79 | function prepares for a login on the terminal |
fea681da | 80 | .I fd |
1285ff3d | 81 | (which may be a real terminal device, or the slave of a pseudoterminal as |
fea681da | 82 | returned by |
63aa9df0 | 83 | .BR openpty ()) |
fea681da MK |
84 | by creating a new session, making |
85 | .I fd | |
a1ffe9f5 | 86 | the controlling terminal for the calling process, setting |
fea681da MK |
87 | .I fd |
88 | to be the standard input, output, and error streams of the current | |
89 | process, and closing | |
90 | .IR fd . | |
91 | ||
92 | The | |
63aa9df0 | 93 | .BR forkpty () |
fea681da | 94 | function combines |
63aa9df0 | 95 | .BR openpty (), |
fb186734 | 96 | .BR fork (2), |
fea681da | 97 | and |
63aa9df0 | 98 | .BR login_tty () |
b218b023 | 99 | to create a new process operating in a pseudoterminal. |
c13182ef | 100 | The file |
b218b023 | 101 | descriptor of the master side of the pseudoterminal is returned in |
fea681da MK |
102 | .IR amaster , |
103 | and the filename of the slave in | |
104 | .I name | |
c13182ef MK |
105 | if it is not NULL. |
106 | The | |
fea681da MK |
107 | .I termp |
108 | and | |
109 | .I winp | |
c4bb193f | 110 | arguments, if not NULL, |
fea681da | 111 | will determine the terminal attributes and window size of the slave |
b218b023 | 112 | side of the pseudoterminal. |
47297adb | 113 | .SH RETURN VALUE |
fea681da | 114 | If a call to |
63aa9df0 MK |
115 | .BR openpty (), |
116 | .BR login_tty (), | |
fea681da | 117 | or |
63aa9df0 | 118 | .BR forkpty () |
8729177b | 119 | is not successful, \-1 is returned and |
fea681da | 120 | .I errno |
c13182ef MK |
121 | is set to indicate the error. |
122 | Otherwise, | |
63aa9df0 MK |
123 | .BR openpty (), |
124 | .BR login_tty (), | |
fea681da | 125 | and the child process of |
63aa9df0 | 126 | .BR forkpty () |
fea681da | 127 | return 0, and the parent process of |
63aa9df0 | 128 | .BR forkpty () |
fea681da MK |
129 | returns the process ID of the child process. |
130 | .SH ERRORS | |
63aa9df0 | 131 | .BR openpty () |
fea681da MK |
132 | will fail if: |
133 | .TP | |
134 | .B ENOENT | |
1285ff3d | 135 | There are no available terminals. |
fea681da | 136 | .LP |
2a1b7cdc | 137 | .BR login_tty () |
fea681da | 138 | will fail if |
fb186734 | 139 | .BR ioctl (2) |
fea681da MK |
140 | fails to set |
141 | .I fd | |
a1ffe9f5 | 142 | to the controlling terminal of the calling process. |
fea681da | 143 | .LP |
63aa9df0 | 144 | .BR forkpty () |
fea681da | 145 | will fail if either |
63aa9df0 | 146 | .BR openpty () |
fea681da | 147 | or |
fb186734 | 148 | .BR fork (2) |
fea681da | 149 | fails. |
47297adb | 150 | .SH CONFORMING TO |
2b2581ee | 151 | These are BSD functions, present in libc5 and glibc2. |
8b3f5f59 | 152 | They are not standardized in POSIX. |
660dd25f | 153 | .SH NOTES |
49c32f8f MK |
154 | The |
155 | .B const | |
156 | modifiers were added to the structure pointer arguments of | |
157 | .BR openpty () | |
158 | and | |
159 | .BR forkpty () | |
160 | in glibc 2.8. | |
161 | ||
660dd25f MK |
162 | In versions of glibc before 2.0.92, |
163 | .BR openpty () | |
b218b023 | 164 | returns file descriptors for a BSD pseudoterminal pair; |
c13182ef | 165 | since glibc 2.0.92, |
b218b023 MK |
166 | it first attempts to open a UNIX 98 pseudoterminal pair, |
167 | and falls back to opening a BSD pseudoterminal pair if that fails. | |
fea681da MK |
168 | .SH BUGS |
169 | Nobody knows how much space should be reserved for | |
170 | .IR name . | |
171 | So, calling | |
63aa9df0 | 172 | .BR openpty () |
fea681da | 173 | or |
63aa9df0 | 174 | .BR forkpty () |
fea681da MK |
175 | with non-NULL |
176 | .I name | |
177 | may not be secure. | |
47297adb | 178 | .SH SEE ALSO |
88ab292b | 179 | .BR fork (2), |
4d31e3ea | 180 | .BR ttyname (3), |
88ab292b | 181 | .BR pty (7) |