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: src/lib/libutil/pty.3,v 1.8.2.3 2001/12/17 10:08:32 ru Exp $
  27 .\"
  28 .Dd December 29, 1996
  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 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.  The caller is
  66 responsible for allocating the required space in this array.
  67 .Pp
  68 If the arguments
  69 .Fa termp
  70 or
  71 .Fa winp
  72 are not
  73 .Dv NULL ,
  74 .Fn openpty
  75 initializes the termios and window size settings from the structures
  76 these arguments point to, respectively.
  77 .Pp
  78 Upon return, the open file descriptors for the master and slave side
  79 of the pty are returned in the locations pointed to by
  80 .Fa amaster
  81 and
  82 .Fa aslave ,
  83 respectively.
  84 .Pp
  85 .Fn Forkpty
  86 first calls
  87 .Fn openpty
  88 to obtain the next available pseudo-terminal from the system.  Upon success,
  89 it forks off a new process.  In the child process, it closes the descriptor
  90 for the master side of the pty, and calls
  91 .Xr login_tty 3
  92 for the slave pty.  In the parent process, it closes the descriptor for the
  93 slave side of the pty.  The arguments
  94 .Fa amaster ,
  95 .Fa name ,
  96 .Fa termp ,
  97 and
  98 .Fa winp
  99 have the same meaning as described for
 100 .Fn openpty .
 101 .Sh RETURN VALUES
 102 .Fn Openpty
 103 returns 0 on success, or -1 on failure.
 104 .Pp
 105 .Fn Forkpty
 106 returns -1 on failure, 0 in the slave process, and the process ID of the
 107 slave process in the parent process.
 108 .Sh ERRORS
 109 On failure,
 110 .Fn openpty
 111 will set the global variable
 112 .Va errno
 113 to
 114 .Er ENOENT .
 115 .Pp
 116 In addition to this,
 117 .Fn forkpty
 118 may set it to any value as described for
 119 .Xr fork 2 .
 120 .Sh SEE ALSO
 121 .Xr chmod 2 ,
 122 .Xr chown 2 ,
 123 .Xr fork 2 ,
 124 .Xr getuid 2 ,
 125 .Xr open 2 ,
 126 .Xr revoke 2 ,
 127 .Xr login_tty 3 ,
 128 .Xr pty 4 ,
 129 .Xr termios 4 ,
 130 .Xr group 5
 131 .Sh BUGS
 132 The calling process must have an effective UID of super-user in order
 133 to perform all the intended actions.  No notification will occur if
 134 .Fn openpty
 135 or
 136 .Fn forkpty
 137 failed to proceed with one of the described steps, as long as they could
 138 at least allocate the pty at all (and create the new process in the case
 139 of
 140 .Fn forkpty ) .