git.saurik.com Git - apple/libc.git/blob

1 .\" $OpenBSD: openpty.3,v 1.3 1996/11/24 23:53:12 millert Exp $

4 .\"

5 .\" This code is derived from software developed by the Computer Systems

6 .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract

7 .\" BG 91-66 and contributed to Berkeley.

8 .\"

9 .\" Redistribution and use in source and binary forms, with or without

10 .\" modification, are permitted provided that the following conditions

11 .\" are met:

12 .\" 1. Redistributions of source code must retain the above copyright

13 .\" notice, this list of conditions and the following disclaimer.

14 .\" 2. Redistributions in binary form must reproduce the above copyright

15 .\" notice, this list of conditions and the following disclaimer in the

16 .\" documentation and/or other materials provided with the distribution.

17 .\" 3. All advertising materials mentioning features or use of this software

18 .\" must display the following acknowledgement:

19 .\" This product includes software developed by the University of

20 .\" California, Berkeley and its contributors.

21 .\" 4. Neither the name of the University nor the names of its contributors

22 .\" may be used to endorse or promote products derived from this software

23 .\" without specific prior written permission.

24 .\"

25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND

26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

28 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE

29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

35 .\" SUCH DAMAGE.

36 .\"

37 .Dd April 5, 2008

38 .Dt OPENPTY 3

39 .Os

40 .Sh NAME

41 .Nm openpty ,

42 .Nm login_tty ,

43 .Nm forkpty

44 .Nd tty utility functions

45 .Sh SYNOPSIS

46 .Fd #include <util.h>

47 .Ft int

48 .Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp"

49 .Ft int

50 .Fn login_tty "int fd"

51 .Ft pid_t

52 .Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp"

53 .Sh DESCRIPTION

54 The

55 .Fn openpty ,

56 .Fn login_tty ,

57 and

58 .Fn forkpty

59 functions perform manipulations on ttys and pseudo-ttys.

60 .Pp

61 The

62 .Fn openpty

63 function allocates a pseudo-tty and returns file descriptors

64 for the master and slave in

65 .Fa amaster

66 and

67 .Fa aslave .

68 If

69 .Fa name

70 is non-null, the filename of the slave is returned in

71 .Fa name .

72 If

73 .Fa termp

74 is non-null, the terminal parameters of the slave will be set to the

75 values in

76 .Fa termp .

77 If

78 .Fa winp

79 is non-null, the window size of the slave will be set to the values in

80 .Fa winp .

81 .Pp

82 The

83 .Fn login_tty

84 function prepares for a login on the tty

85 .Fa fd

86 (which may be a real tty device, or the slave of a pseudo-tty as

87 returned by

88 .Fn openpty )

89 by creating a new session, making

90 .Fa fd

91 the controlling terminal for the current process, setting

92 .Fa fd

93 to be the standard input, output, and error streams of the current

94 process, and closing

95 .Fa fd .

96 .Pp

97 The

98 .Fn forkpty

99 function combines

100 .Fn openpty ,

101 .Fn fork ,

102 and

103 .Fn login_tty

104 to creates a new process operating in a pseudo-tty. The file

105 descriptor of the master side of the pseudo-tty is returned in

106 .Fa amaster ,

107 and the filename of the slave in

108 .Fa name

109 if it is non-null. The

110 .Fa termp

111 and

112 .Fa winp

113 parameters, if non-null, will determine the terminal attributes and

114 window size of the slave side of the pseudo-tty.

115 .Sh RETURN VALUES

116 If a call to

117 .Fn openpty ,

118 .Fn login_tty ,

119 or

120 .Fn forkpty

121 is not successful, -1 is returned and

122 .Va errno

123 is set to indicate the error. Otherwise,

124 .Fn openpty ,

125 .Fn login_tty ,

126 and the child process of

127 .Fn forkpty

128 return 0, and the parent process of

129 .Fn forkpty

130 returns the process ID of the child process.

131 .Sh ERRORS

132 .Fn openpty

133 will fail if:

134 .Bl -tag -width Er

135 .It Bq Er EAGAIN

136 There are no available pseudo-ttys.

137 .El

138 .Pp

139 .Fn login_tty

140 will fail if

141 .Fn ioctl

142 fails to set

143 .Fa fd

144 to the controlling terminal of the current process.

145 .Fn forkpty

146 will fail if either

147 .Fn openpty

148 or

149 .Fn fork

150 fails.

151 .Sh FILES

152 .Bl -tag -width /dev/ttys[0-9][0-9][0-9] -compact

153 .It Pa /dev/ptmx

154 cloning pseudo-tty device

155 .It Pa /dev/ttys[0-9][0-9][0-9]

156 slave pseudo-tty devices

157 .El

158 .Sh SEE ALSO

159 .Xr fork 2