grantpt.3
1 .\" 2 .\" Copyright (c) 2002 The FreeBSD Project, Inc. 3 .\" All rights reserved. 4 .\" 5 .\" This software includes code contributed to the FreeBSD Project 6 .\" by Ryan Younce of North Carolina State University. 7 .\" 8 .\" Redistribution and use in source and binary forms, with or without 9 .\" modification, are permitted provided that the following conditions 10 .\" are met: 11 .\" 1. Redistributions of source code must retain the above copyright 12 .\" notice, this list of conditions and the following disclaimer. 13 .\" 2. Redistributions in binary form must reproduce the above copyright 14 .\" notice, this list of conditions and the following disclaimer in the 15 .\" documentation and/or other materials provided with the distribution. 16 .\" 3. Neither the name of the FreeBSD Project nor the names of its 17 .\" contributors may be used to endorse or promote products derived from 18 .\" this software without specific prior written permission. 19 .\" 20 .\" THIS SOFTWARE IS PROVIDED BY THE FREEBSD PROJECT AND CONTRIBUTORS 21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 23 .\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD PROJECT 24 .\" OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 26 .\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27 .\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28 .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29 .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 .\" 32 .\" $FreeBSD: src/lib/libc/stdlib/grantpt.3,v 1.3 2003/09/14 13:41:57 ru Exp $ 33 .\" 34 .Dd February 2, 2005 35 .Os 36 .Dt GRANTPT 3 37 .Sh NAME 38 .Nm grantpt , 39 .Nm posix_openpt , 40 .Nm ptsname , 41 .Nm ptsname_r , 42 .Nm unlockpt 43 .Nd pseudo-terminal access functions 44 .Sh SYNOPSIS 45 .In stdlib.h 46 .Ft int 47 .Fo grantpt 48 .Fa "int fildes" 49 .Fc 50 .Ft "char *" 51 .Fo ptsname 52 .Fa "int fildes" 53 .Fc 54 .Ft "int" 55 .Fo ptsname_r 56 .Fa "int fildes" 57 .Fa "char *buffer" 58 .Fa "size_t buflen" 59 .Fc 60 .Ft int 61 .Fo unlockpt 62 .Fa "int fildes" 63 .Fc 64 .In stdlib.h 65 .In fcntl.h 66 .Ft int 67 .Fo posix_openpt 68 .Fa "int oflag" 69 .Fc 70 .Sh DESCRIPTION 71 The 72 .Fn grantpt , 73 .Fn ptsname , 74 .Fn ptsname_r , 75 .Fn unlockpt , 76 and 77 .Fn posix_openpt 78 functions allow access to pseudo-terminal devices. 79 The first four functions accept a file descriptor 80 that references the master half of a pseudo-terminal pair. 81 This file descriptor is created with 82 .Fn posix_openpt . 83 .Pp 84 The 85 .Fn grantpt 86 function is used to establish ownership and permissions 87 of the slave device counterpart to the master device 88 specified with 89 .Fa fildes . 90 The slave device's ownership is set to the real user ID 91 of the calling process; its permissions are set to 92 user readable-writable and group writable. 93 The group owner of the slave device is also set to the group 94 .Dq Li tty 95 if it exists on the system; otherwise, it 96 is left untouched. 97 .Pp 98 The 99 .Fn ptsname 100 and 101 .Fn ptsname_r 102 functions return the full pathname of the slave device 103 counterpart to the master device specified with 104 .Fa fildes . 105 This value can be used 106 to subsequently open the appropriate slave after 107 .Fn posix_openpt 108 and 109 .Fn grantpt 110 have been called. The 111 .Fn ptsname 112 function is not guaranteed to be reentrant or thread safe. The 113 .Fn ptsname_r 114 function takes a buffer and length as arguments to avoid this problem. 115 .Pp 116 The 117 .Fn unlockpt 118 function unlocks the slave pseudo-terminal device associated 119 with the master device to which 120 .Fa fildes 121 refers. 122 .Pp 123 The 124 .Fn posix_openpt 125 function opens the first available master pseudo-terminal 126 device and returns a descriptor to it. 127 The 128 .Fa oflag 129 argument 130 specifies the flags used for opening the device: 131 .Bl -tag -width ".Dv O_NOCTTY" 132 .It Dv O_RDWR 133 Open for reading and writing. 134 .It Dv O_NOCTTY 135 If set, do not allow the terminal to become 136 the controlling terminal for the calling process. 137 .El 138 .Sh RETURN VALUES 139 .Rv -std grantpt unlockpt 140 .Pp 141 The 142 .Fn ptsname 143 function returns a pointer to the name 144 of the slave device on success; otherwise a 145 .Dv NULL 146 pointer is returned and the global variable 147 .Va errno 148 is set to indicate the error. 149 .Pp 150 The 151 .Fn ptsname_r 152 function returns 0 if successful. On failure, it returns -1 and the global variable 153 .Va errno 154 is set to indicate the error. 155 .Pp 156 The 157 .Fn posix_openpt 158 function returns a file descriptor to the first 159 available master pseudo-terminal device on success; 160 otherwise \-1 is returned and the global variable 161 .Va errno 162 is set to indicate the error. 163 .Sh ERRORS 164 The 165 .Fn grantpt , 166 .Fn ptsname , 167 .Fn ptsname_r , 168 and 169 .Fn unlockpt 170 functions may fail and set 171 .Va errno 172 to: 173 .Bl -tag -width Er 174 .It Bq Er EINVAL 175 .Fa fildes 176 is not a master pseudo-terminal device. 177 .El 178 .Pp 179 In addition, the 180 .Fn ptsname_r 181 function may set 182 .Va errno 183 to: 184 .Bl -tag -width Er 185 .It Bq Er EINVAL 186 The 187 .Va buffer 188 argument is NULL. 189 .El 190 .Bl -tag -width Er 191 .It Bq Er ERANGE 192 The 193 .Va bufsize 194 argument is smaller than the length of the string to be returned. 195 .El 196 .Pp 197 In addition, the 198 .Fn grantpt 199 function may set 200 .Va errno 201 to: 202 .Bl -tag -width Er 203 .It Bq Er EACCES 204 The slave pseudo-terminal device could not be accessed. 205 .El 206 .Pp 207 The 208 .Fn posix_openpt 209 function may fail and set 210 .Va errno 211 to: 212 .Bl -tag -width Er 213 .It Bq Er EINVAL 214 .Fa oflag 215 consists of an invalid mode bit. 216 .It Bq Er EAGAIN 217 The system has no available pseudo-terminal devices. 218 .El 219 .Pp 220 The 221 .Fn grantpt , 222 .Fn ptsname , 223 .Fn ptsname_r , 224 and 225 .Fn unlockpt 226 functions may also fail and set 227 .Va errno 228 for any of the errors specified for the 229 .Xr fstat 2 230 system call. 231 .Pp 232 The 233 .Fn posix_openpt 234 function may also fail and set 235 .Va errno 236 for any of the errors specified for the 237 .Xr open 2 238 system call. 239 .Sh LEGACY SYNOPSIS 240 .Fd #include <stdlib.h> 241 .Fd #include <fcntl.h> 242 .Pp 243 .Ft int 244 .br 245 .Fo grantpt 246 .Fa "int fildes" 247 .Fc ; 248 .Pp 249 .Ft "char *" 250 .br 251 .Fo ptsname 252 .Fa "int fildes" 253 .Fc ; 254 .Pp 255 .Ft int 256 .br 257 .Fo unlockpt 258 .Fa "int fildes" 259 .Fc ; 260 .Pp 261 .Fd #include <fcntl.h> 262 .Pp 263 .Ft int 264 .br 265 .Fo posix_openpt 266 .Fa "int oflag" 267 .Fc ; 268 .Sh SEE ALSO 269 .Xr open 2 , 270 .Xr pty 4 , 271 .Xr tty 4 , 272 .Xr compat 5 273 .Sh STANDARDS 274 The 275 .Fn grantpt , 276 .Fn ptsname , 277 .Fn unlockpt , 278 and 279 .Fn posix_openpt 280 functions conform to 281 .St -p1003.1-2001 .