aboutsummaryrefslogtreecommitdiff
path: root/manual/terminal.texi
diff options
context:
space:
mode:
authorUlrich Drepper <drepper@redhat.com>1998-06-22 17:08:51 +0000
committerUlrich Drepper <drepper@redhat.com>1998-06-22 17:08:51 +0000
commita53bad166c677459239011bcb3275b87c8c38584 (patch)
treec02a4e897a0cc8505b96167e1c5343c4a8246fe5 /manual/terminal.texi
parent899d423eaf3f66e59ffffefe40b2ba2137bd0050 (diff)
downloadglibc-a53bad166c677459239011bcb3275b87c8c38584.zip
glibc-a53bad166c677459239011bcb3275b87c8c38584.tar.gz
glibc-a53bad166c677459239011bcb3275b87c8c38584.tar.bz2
Update.
1998-06-22 17:02 Ulrich Drepper <drepper@cygnus.com> * sysdeps/generic/enbl-secure.c: Don't use __libc_uid. * sysdeps/unix/sysv/linux/aio_sigqueue.c: Likewise. * sysdeps/unix/sysv/linux/sigqueue.c: Likewise. * sysdeps/unix/sysv/linux/init-first.c: Don't initialize __libc_uid. 1998-06-02 Gordon Matzigkeit <gord@profitpress.com> * mach/Makefile: Change `mv' invocations to `mv -f'. * mach/Machrules: Likewise. 1998-06-22 Andreas Jaeger <aj@arthur.rhein-neckar.de> * config.make.in (old-glibc-headers): Add it. * configure.in: Add test for glibc 2.0.x headers. * Makefile (headers2_0): New variable - contains so far only Linux/Intel glibc 2.0.x headers. (remove-old-headers): New rule to remove headers from glibc 2.0.x. (install): Depend on remove-old-headers. 1998-06-19 Mark Kettenis <kettenis@phys.uva.nl> * sysdeps/generic/ftruncate.c: Define function as __ftruncate and make ftruncate a weak alias. * sysdeps/mach/hurd/ftruncate.c: Really define function as __ftruncate. * sysdeps/mach/hurd/truncate.c: Include <unistd.h>. (truncate): Fix function defenition to match prototype. 1998-06-20 Mark Kettenis <kettenis@phys.uva.nl> * manual/terminal.texi: Document ttyname_r, getpt, grantpt, unlockpt, ptsname, ptsname_r, openpty and forkpty. 1998-06-22 Ulrich Drepper <drepper@cygnus.com> * sysdeps/generic/glob.c: Make it possible to include glob.h before loading glob.c. Reported by Felix von Leitner <leitner@math.fu-berlin.de>. 1998-06-22 Andreas Jaeger <aj@arthur.rhein-neckar.de> * nscd/connections.c: Use poll() instead of select(). 1998-06-22 14:08 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> * sysdeps/generic/Dist: Fix typo. 1998-06-20 Thorsten Kukuk <kukuk@vt.uni-paderborn.de> * nis/nis_add.c: Avoid unnecessary strlen () calls. * nis/nis_addmember.c: Likewise. * nis/nis_call.c: Likewise. * nis/nis_creategroup.c: Likewise. * nis/nis_destroygroup.c: Likewise. * nis/nis_findserv.c: Likewise. * nis/nis_ismember.c: Likewise. * nis/nis_print.c: Likewise. * nis/nis_print_group_entry.c: Likewise. * nis/nis_removemember.c: Likewise. * nis/nis_verifygroup.c: Likewise. * nis/ypclnt.c: Likewise. * nis/nis_file.c: Close file handles. * nis/nis_callback.c: Fix typo.
Diffstat (limited to 'manual/terminal.texi')
-rw-r--r--manual/terminal.texi289
1 files changed, 271 insertions, 18 deletions
diff --git a/manual/terminal.texi b/manual/terminal.texi
index 4e4be88..e6dc36d 100644
--- a/manual/terminal.texi
+++ b/manual/terminal.texi
@@ -22,6 +22,7 @@ descriptor is and how to open a file descriptor for a terminal device.
* Line Control:: Sending break sequences, clearing
terminal buffers @dots{}
* Noncanon Example:: How to read single characters without echo.
+* Pseudo-Terminals:: How to open a pseudo-terminal.
@end menu
@node Is It a Terminal
@@ -35,14 +36,14 @@ descriptor is associated with a terminal by using the @code{isatty}
function.
@pindex unistd.h
-Prototypes for both @code{isatty} and @code{ttyname} are declared in
-the header file @file{unistd.h}.
+Prototypes for the functions in this section are declared in the header
+file @file{unistd.h}.
@comment unistd.h
@comment POSIX.1
@deftypefun int isatty (int @var{filedes})
This function returns @code{1} if @var{filedes} is a file descriptor
-associated with an open terminal device, and @code{0} otherwise.
+associated with an open terminal device, and @math{0} otherwise.
@end deftypefun
If a file descriptor is associated with a terminal, you can get its
@@ -59,6 +60,30 @@ the terminal file. The value is a null pointer if the file descriptor
isn't associated with a terminal, or the file name cannot be determined.
@end deftypefun
+@comment unistd.h
+@comment POSIX.1
+@deftypefun int ttyname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
+The @code{ttyname_r} function is similar to the @code{ttyname} function
+except that it places its result into the user-specified buffer starting
+at @var{buf} with length @var{len}.
+
+The normal return value from @code{ttyname_r} is @math{0}. Otherwise an
+error number is returned to indicate the error. The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item ENOTTY
+The @var{filedes} is not associated with a terminal.
+
+@item ERANGE
+The buffer length @var{len} is too small to store the string to be
+returned.
+@end table
+@end deftypefun
+
@node I/O Queues
@section I/O Queues
@@ -237,7 +262,7 @@ This function is used to examine the attributes of the terminal
device with file descriptor @var{filedes}. The attributes are returned
in the structure that @var{termios-p} points to.
-If successful, @code{tcgetattr} returns @code{0}. A return value of @code{-1}
+If successful, @code{tcgetattr} returns @math{0}. A return value of @math{-1}
indicates an error. The following @code{errno} error conditions are
defined for this function:
@@ -302,8 +327,8 @@ write to the terminal. The exception is if the calling process itself
is ignoring or blocking @code{SIGTTOU} signals, in which case the
operation is performed and no signal is sent. @xref{Job Control}.
-If successful, @code{tcsetattr} returns @code{0}. A return value of
-@code{-1} indicates an error. The following @code{errno} error
+If successful, @code{tcsetattr} returns @math{0}. A return value of
+@math{-1} indicates an error. The following @code{errno} error
conditions are defined for this function:
@table @code
@@ -997,27 +1022,27 @@ This function returns the input line speed stored in the structure
@comment POSIX.1
@deftypefun int cfsetospeed (struct termios *@var{termios-p}, speed_t @var{speed})
This function stores @var{speed} in @code{*@var{termios-p}} as the output
-speed. The normal return value is @code{0}; a value of @code{-1}
+speed. The normal return value is @math{0}; a value of @math{-1}
indicates an error. If @var{speed} is not a speed, @code{cfsetospeed}
-returns @code{-1}.
+returns @math{-1}.
@end deftypefun
@comment termios.h
@comment POSIX.1
@deftypefun int cfsetispeed (struct termios *@var{termios-p}, speed_t @var{speed})
This function stores @var{speed} in @code{*@var{termios-p}} as the input
-speed. The normal return value is @code{0}; a value of @code{-1}
+speed. The normal return value is @math{0}; a value of @math{-1}
indicates an error. If @var{speed} is not a speed, @code{cfsetospeed}
-returns @code{-1}.
+returns @math{-1}.
@end deftypefun
@comment termios.h
@comment BSD
@deftypefun int cfsetspeed (struct termios *@var{termios-p}, speed_t @var{speed})
This function stores @var{speed} in @code{*@var{termios-p}} as both the
-input and output speeds. The normal return value is @code{0}; a value
-of @code{-1} indicates an error. If @var{speed} is not a speed,
-@code{cfsetspeed} returns @code{-1}. This function is an extension in
+input and output speeds. The normal return value is @math{0}; a value
+of @math{-1} indicates an error. If @var{speed} is not a speed,
+@code{cfsetspeed} returns @math{-1}. This function is an extension in
4.4 BSD.
@end deftypefun
@@ -1035,7 +1060,7 @@ will succeed. But they do not check that a particular hardware device
can actually support the specified speeds---in fact, they don't know
which device you plan to set the speed for. If you use @code{tcsetattr}
to set the speed of a particular device to a value that it cannot
-handle, @code{tcsetattr} returns @code{-1}.
+handle, @code{tcsetattr} returns @math{-1}.
@strong{Portability note:} In the GNU library, the functions above
accept speeds measured in bits per second as input, and return speed
@@ -1629,7 +1654,7 @@ This function does nothing if the terminal is not an asynchronous serial
data port.
The return value is normally zero. In the event of an error, a value
-of @code{-1} is returned. The following @code{errno} error conditions
+of @math{-1} is returned. The following @code{errno} error conditions
are defined for this function:
@table @code
@@ -1659,7 +1684,7 @@ protected using cancelation handlers.
@c ref pthread_cleanup_push / pthread_cleanup_pop
The return value is normally zero. In the event of an error, a value
-of @code{-1} is returned. The following @code{errno} error conditions
+of @math{-1} is returned. The following @code{errno} error conditions
are defined for this function:
@table @code
@@ -1705,7 +1730,7 @@ Clear both queued input and output.
@end table
The return value is normally zero. In the event of an error, a value
-of @code{-1} is returned. The following @code{errno} error conditions
+of @math{-1} is returned. The following @code{errno} error conditions
are defined for this function:
@table @code
@@ -1759,7 +1784,7 @@ For more information about the STOP and START characters, see @ref{Special
Characters}.
The return value is normally zero. In the event of an error, a value
-of @code{-1} is returned. The following @code{errno} error conditions
+of @math{-1} is returned. The following @code{errno} error conditions
are defined for this function:
@table @code
@@ -1805,3 +1830,231 @@ a process is stopped or continued; see @ref{Job Control}. But some
existing shells do not actually do this, so you may wish to establish
handlers for job control signals that reset terminal modes. The above
example does so.
+
+
+@node Pseudo-Terminals
+@section Pseudo-Terminals
+@cindex pseudo-terminals
+
+A @dfn{pseudo-terminal} is a special interprocess communication channel
+that acts like a terminal. On one end of the channel is called the
+@dfn{master} side or @dfn{master pseudo-terminal device}, the other side
+is called the @dfn{slave} side. Data written to the the master side is
+received by the slave side as if it was the result of a user typing at
+an ordinary terminal, and data written to the slave side is sent to the
+master side as if it was written on an ordinary terminal.
+
+Pseudo terminals are the way programs like @code{xterm} and @code{emacs}
+implement their terminal emulation functionality.
+
+@menu
+* Allocation:: Allocating a pseudo terminal.
+* Pseudo-Terminal Pairs:: How to open both sides of a
+ pseudo-terminal in a single operation.
+@end menu
+
+@node Allocation
+@subsection Allocating Pseudo-Terminals
+@cindex allocating pseudo-terminals
+
+@pindex stdlib.h
+This subsection describes functions for allocating a pseudo-terminals,
+and for making this pseudo-terminal available for actual use. These
+functions are declared in the header file @file{stdlib.h}.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int getpt (void)
+The @code{getpt} function returns a new file descriptor for the next
+available master pseudo-terminal. The normal return value from
+@code{getpt} is a non-negative integer file descriptor. In the case of
+an error, a value of @math{-1} is returned instead. The following
+@code{errno} conditions are defined for this function:
+
+@table @code
+@item ENFILE
+There are no master pseudo-terminals available.
+@end table
+
+This function is a GNU extension.
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID, XPG4.2
+@deftypefun int grantpt (int @var{filedes})
+The @code{grantpt} function changes the ownership and access permission
+of the slave pseudo-terminal device corresponding to the master
+pseudo-terminal device associated with the file descriptor
+@var{filedes}. The owner is set from the real user ID of the calling
+process (@pxref{Process Persona}), and the group is set to a special
+group (typically @dfn{tty}) or from the real group ID of the calling
+process. The access permission is set such that the file is both
+readable and writable by the owner and only writable by the group.
+
+On some systems this function is implemented by invoking a special
+@code{setuid} root program (@pxref{How Change Persona}). As a
+consequence, installing a signal handler for the @code{SIGCHLD} signal
+(@pxref{Job Control Signals}) may interfere with a call to
+@code{grantpt}.
+
+The normal return value from @code{grantpt} is @math{0}; a value of
+@math{-1} is returned in case of failure. The following @code{errno}
+error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item ENINVAL
+The @var{filedes} argument is not associated with a master pseudo-terminal
+device.
+
+@item EACCESS
+The slave pseudo-terminal device corresponding to the master associated
+with @var{filedes} could not be accessed.
+@end table
+
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID, XPG4.2
+@deftypefun int unlockpt (int @var{filedes})
+The @code{unlockpt} function unlocks the slave pseudo-terminal device
+corresponding to the master pseudo-terminal device associated with the
+file descriptor @var{filedes}. On many systems, the slave can only be
+opened after unlocking, so portable applications should always call
+@code{unlockpt} before trying to open the slave.
+
+The normal return value from @code{unlockpt} is @math{0}; a value of
+@math{-1} is returned in case of failure. The following @code{errno}
+error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item EINVAL
+The @var{filedes} argument is not associated with a master pseudo-terminal
+device.
+@end table
+@end deftypefun
+
+@comment stdlib.h
+@comment SVID, XPG4.2
+@deftypefun {char *} ptsname (int @var{filedes})
+If the file descriptor @var{filedes} is associated with a
+master pseudo-terminal device, the @code{ptsname} function returns a
+pointer to a statically-allocated, null-terminated string containing the
+file name of the associated slave pseudo-terminal file. This string
+might be overwritten by subsequent calls to @code{ptsname}.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int ptsname_r (int @var{filedes}, char *@var{buf}, size_t @var{len})
+The @code{ptsname_r} function is similar to the @code{ptsname} function
+except that it places its result into the user-specified buffer starting
+at @var{buf} with length @var{len}.
+
+This function is a GNU extension.
+@end deftypefun
+
+@strong{Portability Note:} On @w{System V} derived systems, the file
+returned by the @code{ptsname} and @code{ptsname_r} functions may be
+STREAMS-based, and therefore require additional processing after opening
+before it actually behaves as a pseudo terminal.
+@c FIXME: xref STREAMS
+
+Typical usage of these functions is illustrated by the following example:
+@smallexample
+int
+open_pty_pair (int *amaster, int *aslave)
+@{
+ int master, slave;
+ char *name
+
+ master = getpt ();
+ if (master < 0)
+ return 0;
+
+ if (grantpt (master) < 0 || unlockpt (master) < 0)
+ goto close_master;
+ name = ptsname (master);
+ if (name == NULL)
+ goto close_master;
+
+ slave open (name, O_RDWR);
+ if (slave == -1)
+ goto close_master;
+
+ if (isastream (slave))
+ @{
+ if (ioctl (slave, I_PUSH, "ptem") < 0
+ || ioctl (slave, I_PUSH, "ldterm") < 0)
+ goto close_slave;
+ @}
+
+ *amaster = master;
+ *aslave = slave;
+ return 1;
+
+close_slave:
+ close (slave);
+
+close_master:
+ close (master);
+ return 0;
+@}
+@end smallexample
+
+@node Pseudo-Terminal Pairs
+@subsection Opening a Pseudo-Terminal Pair
+@cindex opening a pseudo-terminal pair
+
+These functions, derived from BSD, are available in the separate
+@file{libutil} library, and declared in @file{pty.h}.
+
+@comment pty.h
+@comment BSD
+@deftypefun int openpty (int *@var{amaster}, int *@var{aslave}, char *@var{name}, struct termios *@var{termp}, struct winsize *@var{winp})
+This function allocates and opens a pseudo-terminal pair, returning the
+file descriptor for the master in @var{*amaster}, and the file
+descriptor for the slave in @var{*aslave}. If the argument @var{name}
+is not a null pointer, the name file name of the slave pseudo-terminal
+device is stored in @code{*name}. If @var{termp} is not a null pointer,
+the terminal attributes of the slave are set to the ones specified in
+the structure that @var{termp} points to (@pxref{Terminal Modes}).
+Likewise, if the @var{winp} is not a null pointer, the screen size of
+the slave is set to the values specified in the structure that
+@var{winp} points to.
+
+The normal return value from @code{openpty} is @math{0}; a value of
+@math{-1} is returned in case of failure.
+
+@strong{Warning:} Using the @code{openpty} with @var{name} not set to
+@code{NULL} is @strong{very dangerous} because it provides no protection
+against overflowing the string @var{name}. You should use the
+@code{ttyname} function on the file descriptor returned in @var{*slave}
+to find out the file name of the slave pseudo-terminal device instead.
+@end deftypefun
+
+@comment pty.h
+@comment BSD
+@deftypefun int forkpty (int *@var{amaster}, char *@var{name}, struct termios *@var{termp}, struct winsize *@var{winp})
+This function is similar to the @code{openpty} function, but in
+addition, forks creates a new process (@pxref{Creating a Process}) and
+makes the newly opened slave pseudo-terminal device the controlling
+terminal (@pxref{Controlling Terminal}) for the child process.
+
+If the operation is successful, there are then both parent and child
+processes and both see @code{forkpty} return, but with different values:
+it returns a value of @math{0} in the child process and returns the child's
+process ID in the parent process.
+
+If the allocation of a pseudo-terminal pair or the process creation
+failed, @code{forkpty} returns a value of @math{-1} in the parent
+process.
+
+@strong{Warning:} The @code{forkpty} function has the same problems with
+respect to the @var{name} argument as @code{openpty}.
+@end deftypefun