<?xml version="1.0" encoding="UTF-8"?>
<!-- **************************************************************************
.... For copyright and licensing terms, see the file named COPYING.
.... **************************************************************************
.-->
<?xml-stylesheet href="docbook-xml.css" type="text/css"?>

<refentry id="ptyrun">

<refmeta xmlns:xi="http://www.w3.org/2001/XInclude">
<refentrytitle>ptyrun</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">user commands</refmiscinfo>
<refmiscinfo class="source">nosh</refmiscinfo>
<xi:include href="version.xml" />
</refmeta>

<refnamediv>
<refname>ptyrun</refname>
<refpurpose>run a program under a pseudo-terminal</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>ptyrun</command> <arg choice='req'><replaceable>next-prog</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Description</title>

<para>
<command>ptyrun</command> enables running programs that expect terminals on their standard file descriptors, in situations where there are no controlling terminals and the standard file descriptors are things such as pipes or sockets.
It does not itself expect to be running connected to a terminal, and it takes no steps to adjust terminal modes if it is.
If <replaceable>next-prog</replaceable> stops with a signal, it is simply continued.
</para>

<para>
<command>ptyrun</command> combines <citerefentry><refentrytitle>pty-allocate</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>pty-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and <citerefentry><refentrytitle>open-controlling-tty</refentrytitle><manvolnum>1</manvolnum></citerefentry> to run <replaceable>next-prog</replaceable> with its standard input, output, and error routed through a pseudo-terminal.
It is a script that needs <citerefentry><refentrytitle>execlineb</refentrytitle><manvolnum>1</manvolnum></citerefentry> as its script interpreter.
</para>

<para>
<replaceable>next-prog</replaceable> may contain its own command line options, which <command>pty-run</command> will ignore.
</para>

<para>
See <citerefentry><refentrytitle>open-controlling-terminal</refentrytitle><manvolnum>1</manvolnum></citerefentry> for the environment and open file descriptors inherited by <replaceable>next-prog</replaceable>.
</para>

</refsection>

<refsection><title>History</title>

<para>
There was a <command>ptyrun</command> shell script in Daniel J. Bernstein's pty package in 1996.
This workalike <command>execlineb</command> script based upon nosh tools was created in 2013.
</para>

</refsection><refsection><title>Author</title>
<para><author><personname><firstname>Jonathan</firstname> <surname>de Boyne Pollard</surname></personname></author></para>
</refsection>

</refentry>
