lib/libutil/pty.3

   1 .\"
   2 .\" Copyright (c) 1996 Joerg Wunsch
   3 .\"
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\" "
  28 .Dd December 29, 1996
  29 .Os
  30 .Dt PTY 3
  31 .Sh NAME
  32 .Nm openpty ,
  33 .Nm forkpty
  34 .Nd auxiliary functions to obtain a pseudo-terminal
  35 .Sh LIBRARY
  36 .Lb libutil
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/ioctl.h
  40 .In termios.h
  41 .In libutil.h
  42 .Ft int
  43 .Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp"
  44 .Ft int
  45 .Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp"
  46 .Sh DESCRIPTION
  47 The function
  48 .Fn openpty
  49 attempts to obtain the next available pseudo-terminal from the system (see
  50 .Xr pty 4 ) .
  51 If it successfully finds one, it subsequently tries to change the
  52 ownership of the slave device to the real UID of the current process,
  53 the group membership to the group
  54 .Dq tty
  55 (if such a group exists in the system), the access permissions for
  56 reading and writing by the owner, and for writing by the group, and to
  57 invalidate any current use of the line by calling
  58 .Xr revoke 2 .
  59 .Pp
  60 If the argument
  61 .Fa name
  62 is not
  63 .Dv NULL ,
  64 .Fn openpty
  65 copies the pathname of the slave pty to this area.
  66 The caller is
  67 responsible for allocating the required space in this array.
  68 .Pp
  69 If the arguments
  70 .Fa termp
  71 or
  72 .Fa winp
  73 are not
  74 .Dv NULL ,
  75 .Fn openpty
  76 initializes the termios and window size settings from the structures
  77 these arguments point to, respectively.
  78 .Pp
  79 Upon return, the open file descriptors for the master and slave side
  80 of the pty are returned in the locations pointed to by
  81 .Fa amaster
  82 and
  83 .Fa aslave ,
  84 respectively.
  85 .Pp
  86 The
  87 .Fn forkpty
  88 function first calls
  89 .Fn openpty
  90 to obtain the next available pseudo-terminal from the system.
  91 Upon success,
  92 it forks off a new process.
  93 In the child process, it closes the descriptor
  94 for the master side of the pty, and calls
  95 .Xr login_tty 3
  96 for the slave pty.
  97 In the parent process, it closes the descriptor for the
  98 slave side of the pty.
  99 The arguments
 100 .Fa amaster ,
 101 .Fa name ,
 102 .Fa termp ,
 103 and
 104 .Fa winp
 105 have the same meaning as described for
 106 .Fn openpty .
 107 .Sh RETURN VALUES
 108 The
 109 .Fn openpty
 110 function returns 0 on success, or -1 on failure.
 111 .Pp
 112 The
 113 .Fn forkpty
 114 function returns -1 on failure, 0 in the slave process, and the process ID of
 115 the slave process in the parent process.
 116 .Sh ERRORS
 117 On failure,
 118 .Fn openpty
 119 will set the global variable
 120 .Dv errno
 121 to
 122 .Er ENOENT .
 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 SEE ALSO
 129 .Xr chmod 2 ,
 130 .Xr chown 2 ,
 131 .Xr fork 2 ,
 132 .Xr getuid 2 ,
 133 .Xr open 2 ,
 134 .Xr revoke 2 ,
 135 .Xr login_tty 3 ,
 136 .Xr pty 4 ,
 137 .Xr termios 4 ,
 138 .Xr group 5
 139 .Sh BUGS
 140 The calling process must have an effective UID of super-user in order
 141 to perform all the intended actions.
 142 No notification will occur if
 143 .Fn openpty
 144 or
 145 .Fn forkpty
 146 failed to proceed with one of the described steps, as long as they could
 147 at least allocate the pty at all (and create the new process in the case
 148 of
 149 .Fn forkpty ) .