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 unlockpt
  42 .Nd pseudo-terminal access functions
  43 .Sh SYNOPSIS
  44 .In stdlib.h
  45 .Ft int
  46 .Fo grantpt
  47 .Fa "int fildes"
  48 .Fc
  49 .Ft "char *"
  50 .Fo ptsname
  51 .Fa "int fildes"
  52 .Fc
  53 .Ft int
  54 .Fo unlockpt
  55 .Fa "int fildes"
  56 .Fc
  57 .In stdlib.h
  58 .In fcntl.h
  59 .Ft int
  60 .Fo posix_openpt
  61 .Fa "int oflag"
  62 .Fc
  63 .Sh DESCRIPTION
  64 The
  65 .Fn grantpt ,
  66 .Fn ptsname ,
  67 .Fn unlockpt ,
  68 and
  69 .Fn posix_openpt
  70 functions allow access to pseudo-terminal devices.
  71 The first three functions accept a file descriptor
  72 that references the master half of a pseudo-terminal pair.
  73 This file descriptor is created with
  74 .Fn posix_openpt .
  75 .Pp
  76 The
  77 .Fn grantpt
  78 function is used to establish ownership and permissions
  79 of the slave device counterpart to the master device
  80 specified with
  81 .Fa fildes .
  82 The slave device's ownership is set to the real user ID
  83 of the calling process; its permissions are set to
  84 user readable-writable and group writable.
  85 The group owner of the slave device is also set to the group
  86 .Dq Li tty
  87 if it exists on the system; otherwise, it
  88 is left untouched.
  89 .Pp
  90 The
  91 .Fn ptsname
  92 function returns the full pathname of the slave device
  93 counterpart to the master device specified with
  94 .Fa fildes .
  95 This value can be used
  96 to subsequently open the appropriate slave after
  97 .Fn posix_openpt
  98 and
  99 .Fn grantpt
 100 have been called.
 101 .Pp
 102 The
 103 .Fn unlockpt
 104 function unlocks the slave pseudo-terminal device associated
 105 with the master device to which
 106 .Fa fildes
 107 refers.
 108 .Pp
 109 The
 110 .Fn posix_openpt
 111 function opens the first available master pseudo-terminal
 112 device and returns a descriptor to it.
 113 The
 114 .Fa oflag
 115 argument
 116 specifies the flags used for opening the device:
 117 .Bl -tag -width ".Dv O_NOCTTY"
 118 .It Dv O_RDWR
 119 Open for reading and writing.
 120 .It Dv O_NOCTTY
 121 If set, do not allow the terminal to become
 122 the controlling terminal for the calling process.
 123 .El
 124 .Sh RETURN VALUES
 125 .Rv -std grantpt unlockpt
 126 .Pp
 127 The
 128 .Fn ptsname
 129 function returns a pointer to the name
 130 of the slave device on success; otherwise a
 131 .Dv NULL
 132 pointer is returned and the global variable
 133 .Va errno
 134 is set to indicate the error.
 135 .Pp
 136 The
 137 .Fn posix_openpt
 138 function returns a file descriptor to the first
 139 available master pseudo-terminal device on success;
 140 otherwise \-1 is returned and the global variable
 141 .Va errno
 142 is set to indicate the error.
 143 .Sh ERRORS
 144 The
 145 .Fn grantpt ,
 146 .Fn ptsname ,
 147 and
 148 .Fn unlockpt
 149 functions may fail and set
 150 .Va errno
 151 to:
 152 .Bl -tag -width Er
 153 .It Bq Er EINVAL
 154 .Fa fildes
 155 is not a master pseudo-terminal device.
 156 .El
 157 .Pp
 158 In addition, the
 159 .Fn grantpt
 160 function may set
 161 .Va errno
 162 to:
 163 .Bl -tag -width Er
 164 .It Bq Er EACCES
 165 The slave pseudo-terminal device could not be accessed.
 166 .El
 167 .Pp
 168 The
 169 .Fn posix_openpt
 170 function may fail and set
 171 .Va errno
 172 to:
 173 .Bl -tag -width Er
 174 .It Bq Er EINVAL
 175 .Fa oflag
 176 consists of an invalid mode bit.
 177 .It Bq Er EAGAIN
 178 The system has no available pseudo-terminal devices.
 179 .El
 180 .Pp
 181 The
 182 .Fn grantpt ,
 183 .Fn ptsname ,
 184 and
 185 .Fn unlockpt
 186 functions may also fail and set
 187 .Va errno
 188 for any of the errors specified for the
 189 .Xr fstat 2
 190 system call.
 191 .Pp
 192 The
 193 .Fn posix_openpt
 194 function may also fail and set
 195 .Va errno
 196 for any of the errors specified for the
 197 .Xr open 2
 198 system call.
 199 .Sh LEGACY SYNOPSIS
 200 .Fd #include <stdlib.h>
 201 .Fd #include <fcntl.h>
 202 .Pp
 203 .Ft int
 204 .br
 205 .Fo grantpt
 206 .Fa "int fildes"
 207 .Fc ;
 208 .Pp
 209 .Ft "char *"
 210 .br
 211 .Fo ptsname
 212 .Fa "int fildes"
 213 .Fc ;
 214 .Pp
 215 .Ft int
 216 .br
 217 .Fo unlockpt
 218 .Fa "int fildes"
 219 .Fc ;
 220 .Pp
 221 .Fd #include <fcntl.h>
 222 .Pp
 223 .Ft int
 224 .br
 225 .Fo posix_openpt
 226 .Fa "int oflag"
 227 .Fc ;
 228 .Sh SEE ALSO
 229 .Xr open 2 ,
 230 .Xr pty 4 ,
 231 .Xr tty 4 ,
 232 .Xr compat 5
 233 .Sh STANDARDS
 234 The
 235 .Fn grantpt ,
 236 .Fn ptsname ,
 237 .Fn unlockpt ,
 238 and
 239 .Fn posix_openpt
 240 functions conform to
 241 .St -p1003.1-2001 .