\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#88: Extend Tcl Process Id Control via 'pid'}
\date{March 11, 2002}
\author{Jeff Hobbs, Vince Darley}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#88}&\textbf{Extend Tcl Process Id Control via 'pid'}\\\hline
Author&

Jeff Hobbs \tipmail{JeffH}{ActiveState.com}
\par
Vince Darley \tipmail{vincentdarley}{users.sourceforge.net}
\\
Created&Monday, \(\text{11}^{\text{th}}\) March 2002\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Rejected\\
Vote&Done\\
Version&\tipversion$Revision: 1.9 $\\
Post History&\\
Obsoleted By&240\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes extended the [pid] command to provide more control over native processes in Tcl.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Certain process control functions have shown themselves to be portable and of high usefulness to Tcl programmers. Most of these already exist in TclX, but simply requiring that extension isn't always acceptable. The [pid] command in Tcl is a command that is often overlooked, and so simple that it lends itself easily to being enhanced with new syntax. This TIP proposes adding subcommands to [pid] that extend the process control functionality of pure Tcl.

\section{Specification}
\begingroup\small\begin{verbatim}
   pid ?fileId?
   pid terminate ?-force? ?--? pid ?pid ...?
\end{verbatim}
\endgroup

The first line is the current definition for [pid], which is to return the name of the current process id, or that attached to a \textit{fileId} (as returned by [open] or [socket]). I propose to add only \textit{terminate} initially. This command is adapted almost directly from TclX's signal handling, but changed to work as a subcommand of [pid]. This is to satisfy one of the most common requests from users regarding process management --- killing a known process. It also establishes the framework of extending [pid] for future modifications. The ?-force? argument causes a forceful termination (the usage of SIGKILL on Unix, for Windows and Mac termination is already forceful).

\section{Reference Implementation}

Although TclX's current documentation denies it, the \textit{send} is already implemented for Windows (as \textit{kill} under TclX) as well as Unix. Macintosh implementations for OS 9 and below would need to be created, or the documentation would need to stress that these are not available there (OS X is Unix based). Jim Ingham notes that a variant of \textit{kill} could be created for OS 9. These functions are really meant to round out the process control functionality in Tcl (started with \textit{exec} and \textit{open\tipbar{}}), which are already of limited portability to Mac OS 9 (but undeniable usefulness elsewhere).

File: \textit{tcl/mac/tclMacChan.c}

File: \textit{tcl/unix/tclUnixPipe.c}

File: \textit{tcl/win/tclWinPipe.c}

Function: \textit{Tcl\_PidObjCmd}

\section{Future Potential}

What this also provides is a blueprint for future process management functions like these:
\begingroup\small\begin{verbatim}
   pid id ?-user ?userIdOrName?? ?-group ?groupIdOrName?? ?-parent parentId?
   pid wait ?-nohang bool? ?-untraced bool? ?-group bool? ?fileIdOrPid?
   pid nice ?-level niceLevel? fileIdOrPid
   pid list ?pattern?
   pid id ?-session id? ?-processgroup id?
   pid handle action signal ...
   pid send signalType fileIdOrPid ?fileIdOrPid ...?
\end{verbatim}
\endgroup

[pid wait] was in the initial tip, but it was recommended to rework it with callback to make it much more useful to the user. The [pid id] command was intended for Unix only, operating on the current process id, and would function similar to the [file attributes] command, but Windows NT does have similar functionality. The \textit{-user} and \textit{-group} options will return the name if possible, otherwise the id. The \textit{-parent} option would be read-only (like \textit{-longname} for [file attributes]). [pid send] suffers from cross-platform portability as well. On Windows, you can only \textit{raise} signals inside of your own process.

[pid nice] is easy to implement, while [pid list] is very much platform sensitive. [pid handle] is for signal handling, another oft-requested feature for the core, and would be based on the TclX [signal] command (perhaps named \textit{trap} as in Expect?). It could be massaged to various forms. These aren't to be addressed in this TIP, but are just ideas for the future.

\section{Comments}
\begingroup\small\begin{verbatim}
   pid kill ?-group bool? ?-signal signalType? fileIdOrPid ?fileIdOrPid ...?
\end{verbatim}
\endgroup

This was the original form for [pid send], but it was noted that we are really sending signals. While I prefer the specificity of users recognizing \textit{kill} as a command, what this really does is send specific signals (ANSI C specifies SIGABRT, SIGINT and SIGTERM, and for Unix we would handle the other POSIX names too). Thus I changed it to the \textit{send} command documented above.

[process] rather than [pid] seems a more logical name for this command, but we are working within the constraints of the existing commands in order to prevent command bloat. There is still logic in the naming, as we are dealing with process ids.

[pid terminate] was also recommended to have the ability to terminate a process \textit{and} all its children. This would be useful, but is not in the scope of the current tip.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
