stdlib/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 .