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