lib/libutil/openpty.3

   1 .\"     $NetBSD: openpty.3,v 1.17 2012/07/27 21:33:46 christos Exp $
   2 .\"
   3 .\" Copyright (c) 1995
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software developed by the Computer Systems
   7 .\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
   8 .\" BG 91-66 and contributed to Berkeley.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .Dd July 27, 2012
  35 .Dt OPENPTY 3
  36 .Os
  37 .Sh NAME
  38 .Nm openpty ,
  39 .Nm login_tty ,
  40 .Nm forkpty
  41 .Nd tty utility functions
  42 .Sh LIBRARY
  43 .Lb libutil
  44 .Sh SYNOPSIS
  45 .In util.h
  46 .Ft int
  47 .Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp"
  48 .Ft int
  49 .Fn login_tty "int fd"
  50 .Ft pid_t
  51 .Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp"
  52 .Sh DESCRIPTION
  53 The
  54 .Fn openpty ,
  55 .Fn login_tty ,
  56 and
  57 .Fn forkpty
  58 functions perform manipulations on ttys and pseudo-ttys.
  59 .Pp
  60 The
  61 .Fn openpty
  62 function finds an available pseudo-tty and returns file descriptors
  63 for the master and slave in
  64 .Fa amaster
  65 and
  66 .Fa aslave .
  67 If
  68 .Fa name
  69 is non-null, the filename of the slave is returned in
  70 .Fa name .
  71 The length of
  72 .Fa name
  73 is limited to
  74 .Dv PATH_MAX
  75 as any other regular path name, so a buffer of this size should be used.
  76 .\" .Dv 16
  77 .\" characters in the current
  78 .\" .Xr ptm 4
  79 .\" device driver (including the terminating
  80 .\" .Dv NUL )
  81 .\" which limits the maximum to
  82 .\" .Dv 100,000
  83 .\" ptys.
  84 If
  85 .Fa termp
  86 is non-null, the terminal parameters of the slave will be set to the
  87 values in
  88 .Fa termp .
  89 If
  90 .Fa winp
  91 is non-null, the window size of the slave will be set to the values in
  92 .Fa winp .
  93 .Pp
  94 The
  95 .Fn login_tty
  96 function prepares for a login on the tty
  97 .Fa fd
  98 (which may be a real tty device, or the slave of a pseudo-tty as
  99 returned by
 100 .Fn openpty )
 101 by creating a new session, making
 102 .Fa fd
 103 the controlling terminal for the current process, setting
 104 .Fa fd
 105 to be the standard input, output, and error streams of the current
 106 process, and closing
 107 .Fa fd .
 108 .Pp
 109 The
 110 .Fn forkpty
 111 function combines
 112 .Fn openpty ,
 113 .Fn fork ,
 114 and
 115 .Fn login_tty
 116 to create a new process operating in a pseudo-tty.
 117 The file descriptor of the master side of the pseudo-tty is returned
 118 (to the parent process only) in
 119 .Fa amaster .
 120 The filename of the slave is returned (to both the parent and child
 121 processes) in
 122 .Fa name
 123 if
 124 .Fa name
 125 is non-null.
 126 The
 127 .Fa termp
 128 and
 129 .Fa winp
 130 parameters, if non-null, will determine the terminal attributes and
 131 window size of the slave side of the pseudo-tty.
 132 .Sh RETURN VALUES
 133 If a call to
 134 .Fn openpty ,
 135 .Fn login_tty ,
 136 or
 137 .Fn forkpty
 138 is not successful, -1 is returned and
 139 .Va errno
 140 is set to indicate the error.
 141 Otherwise,
 142 .Fn openpty ,
 143 .Fn login_tty ,
 144 and the child process of
 145 .Fn forkpty
 146 return 0, and the parent process of
 147 .Fn forkpty
 148 returns the process ID of the child process.
 149 .Sh FILES
 150 .Bl -tag -width /dev/[pt]ty[p-zP-T][0-9a-zA-Z] -compact
 151 .It Pa /dev/[pt]ty[p-zP-T][0-9a-zA-Z]
 152 .El
 153 .Sh ERRORS
 154 .Fn openpty
 155 will fail if:
 156 .Bl -tag -width Er
 157 .It Bq Er ENOENT
 158 There are no available ttys.
 159 .It Bq Er EPERM
 160 The caller was not the superuser and the
 161 .Xr ptm 4
 162 device is missing or not configured.
 163 .El
 164 .Pp
 165 .Fn login_tty
 166 will fail if
 167 .Fn ioctl
 168 fails to set
 169 .Fa fd
 170 to the controlling terminal of the current process.
 171 .Fn forkpty
 172 will fail if either
 173 .Fn openpty
 174 or
 175 .Fn fork
 176 fails.
 177 .Sh SEE ALSO
 178 .Xr fork 2