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 .\" $DragonFly: src/lib/libutil/pty.3,v 1.3 2007/06/30 19:03:52 swildner Exp $
  28 .\" "
  29 .Dd December 29, 1996
  30 .Os
  31 .Dt PTY 3
  32 .Sh NAME
  33 .Nm openpty ,
  34 .Nm forkpty
  35 .Nd auxiliary functions to obtain a pseudo-terminal
  36 .Sh LIBRARY
  37 .Lb libutil
  38 .Sh SYNOPSIS
  39 .In sys/types.h
  40 .In sys/ioctl.h
  41 .In termios.h
  42 .In libutil.h
  43 .Ft int
  44 .Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp"
  45 .Ft int
  46 .Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp"
  47 .Sh DESCRIPTION
  48 The function
  49 .Fn openpty
  50 attempts to obtain the next available pseudo-terminal from the system (see
  51 .Xr pty 4 ) .
  52 If it successfully finds one, it subsequently tries to change the
  53 ownership of the slave device to the real UID of the current process,
  54 the group membership to the group
  55 .Dq tty
  56 (if such a group exists in the system), the access permissions for
  57 reading and writing by the owner, and for writing by the group, and to
  58 invalidate any current use of the line by calling
  59 .Xr revoke 2 .
  60 .Pp
  61 If the argument
  62 .Fa name
  63 is not
  64 .Dv NULL ,
  65 .Fn openpty
  66 copies the pathname of the slave pty to this area.  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 .Fn Forkpty
  87 first calls
  88 .Fn openpty
  89 to obtain the next available pseudo-terminal from the system.  Upon success,
  90 it forks off a new process.  In the child process, it closes the descriptor
  91 for the master side of the pty, and calls
  92 .Xr login_tty 3
  93 for the slave pty.  In the parent process, it closes the descriptor for the
  94 slave side of the pty.  The arguments
  95 .Fa amaster ,
  96 .Fa name ,
  97 .Fa termp ,
  98 and
  99 .Fa winp
 100 have the same meaning as described for
 101 .Fn openpty .
 102 .Sh RETURN VALUES
 103 .Fn Openpty
 104 returns 0 on success, or -1 on failure.
 105 .Pp
 106 .Fn Forkpty
 107 returns -1 on failure, 0 in the slave process, and the process ID of the
 108 slave process in the parent process.
 109 .Sh ERRORS
 110 On failure,
 111 .Fn openpty
 112 will set the global variable
 113 .Va errno
 114 to
 115 .Er ENOENT .
 116 .Pp
 117 In addition to this,
 118 .Fn forkpty
 119 may set it to any value as described for
 120 .Xr fork 2 .
 121 .Sh SEE ALSO
 122 .Xr chmod 2 ,
 123 .Xr chown 2 ,
 124 .Xr fork 2 ,
 125 .Xr getuid 2 ,
 126 .Xr open 2 ,
 127 .Xr revoke 2 ,
 128 .Xr login_tty 3 ,
 129 .Xr pty 4 ,
 130 .Xr termios 4 ,
 131 .Xr group 5
 132 .Sh BUGS
 133 The calling process must have an effective UID of super-user in order
 134 to perform all the intended actions.  No notification will occur if
 135 .Fn openpty
 136 or
 137 .Fn forkpty
 138 failed to proceed with one of the described steps, as long as they could
 139 at least allocate the pty at all (and create the new process in the case
 140 of
 141 .Fn forkpty ) .