1 .\"
   2 .\" Copyright 2015 Nexenta Systems, Inc. All Rights Reserved. 
   3 .\" Copyright (c) 1996 Joerg Wunsch
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .\" "
  28 .Dd October 10, 2015
  29 .Dt PTY 3
  30 .Os
  31 .Sh NAME
  32 .Nm openpty ,
  33 .Nm forkpty
  34 .Nd auxiliary functions to obtain a pseudo-terminal
  35 .Sh SYNOPSIS
  36 .In pty.h
  37 .Ft int
  38 .Fn openpty "int *amaster" "int *aslave" "char *name" "const struct termios *termp" "const struct winsize *winp"
  39 .Ft int
  40 .Fn forkpty "int *amaster" "char *name" "const struct termios *termp" "const struct winsize *winp"
  41 .Sh DESCRIPTION
  42 The function
  43 .Fn openpty
  44 attempts to obtain the next available pseudo-terminal from the
  45 system. If it successfully finds one, it subsequently changes the
  46 ownership of the slave device to the real UID of the current process,
  47 the group membership to the group
  48 .Dq tty
  49 (if such a group exists in the system), the access permissions for
  50 reading and writing by the owner, and for writing by the group.
  51 .Pp
  52 If the argument
  53 .Fa name
  54 is not
  55 .Dv NULL ,
  56 the filename of the slave is returned in name.
  57 .Pp
  58 If the arguments
  59 .Fa termp
  60 or
  61 .Fa winp
  62 are not
  63 .Dv NULL ,
  64 .Fn openpty
  65 initializes the termios and window size settings from the structures
  66 these arguments point to, respectively.
  67 .Pp
  68 Upon return, the open file descriptors for the master and slave side
  69 of the pty are returned in the locations pointed to by
  70 .Fa amaster
  71 and
  72 .Fa aslave ,
  73 respectively.
  74 .Pp
  75 The
  76 .Fn forkpty
  77 function first calls
  78 .Fn openpty
  79 to obtain the next available pseudo-terminal from the system.
  80 Upon success,
  81 it forks off a new process.
  82 In the child process, it closes the descriptor
  83 for the master side of the pty, and calls
  84 .Xr login_tty 3
  85 for the slave pty.
  86 In the parent process, it closes the descriptor for the
  87 slave side of the pty.
  88 The arguments
  89 .Fa amaster ,
  90 .Fa name ,
  91 .Fa termp ,
  92 and
  93 .Fa winp
  94 have the same meaning as described for
  95 .Fn openpty .
  96 .Sh RETURN VALUES
  97 If a call to
  98 .Fn openpty
  99 or
 100 .Fn forkpty
 101 is not successful, -1 is returned and errno is set
 102 to indicate the error.  Otherwise,
 103 .Fn openpty
 104 and the child process of
 105 .Fn forkpty
 106 return 0, and the parent process of
 107 .Fn forkpty
 108 returns the process ID of the child process.
 109 .Sh ERRORS
 110 The
 111 .Fn openpty
 112 function may fail and set the global variable
 113 .Dv errno
 114 for any of the errors specified for the
 115 .Xr open 2,
 116 .Xr grantpt 3 ,
 117 .Xr unlockpt 3,
 118 .Xr ptsname 3 ,
 119 .Xr ioctl 2 ,
 120 and
 121 .Xr tcsetattr 3
 122 functions.
 123 .Pp
 124 In addition to this,
 125 .Fn forkpty
 126 may set it to any value as described for
 127 .Xr fork 2 .
 128 .Sh INTERFACE STABILITY
 129 .Sy Comitted
 130 .Sh MT-LEVEL
 131 .Sy MT-Safe
 132 .Sh SEE ALSO
 133 .Xr chmod 2 ,
 134 .Xr chown 2 ,
 135 .Xr fork 2 ,
 136 .Xr getuid 2 ,
 137 .Xr open 2 ,
 138 .Xr login_tty 3 ,
 139 .Xr termios 3 ,
 140 .Xr group 4