\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#390: A Logging API for Tcl}
\date{October 27, 2011}
\author{Jeff Rogers}
\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 \#390}&\textbf{A Logging API for Tcl}\\\hline
Author&

Jeff Rogers \tipmail{dvrsn}{diphi.com}
\\
Created&Thursday, \(\text{27}^{\text{th}}\) October 2011\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.1 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a standard API for logging in Tcl applications, both at the Tcl and C level.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Logging is needed in most applications. There is no standard, documented logging API in Tcl, for either Tcl or C code, leading most people to roll their own. The TIP proposes a standard Tcl and C API that handles the most common logging functions.

The default implementation of the logger should just print the message (with substitutions performed as if with \textbf{format}) to the standard error channel.

\section{Specification}
\begin{enumerate}
\item{}
\textbf{Tcl\_Log}(\textit{interp}, \textit{level}, \textit{message}, ...)

This is the main C api call; it logs the formatted message at the specified loglevel. If interp is specified, it operates within the context of that interp; if NULL then it logs in a maner not associated with any interp.
\setcounter{enumi}{1}
\item{}
\textbf{Tcl\_SetLogLevel}(\textit{interp}, \textit{level})

Instructs the logging system to set the loglevel to the given value. Legal levels are TCL\_LOG\_DEV, TCL\_LOG\_DEBUG, TCL\_LOG\_INFO, TCL\_LOG\_NOTICE, TCL\_LOG\_WARNING, TCL\_LOG\_ERROR, TCL\_LOG\_FATAL, TCL\_LOG\_BUG
\setcounter{enumi}{2}
\item{}
\textbf{Tcl\_SetLogHandler}(\textit{interp}, \textit{logHandler})
\begingroup\small\begin{verbatim}
    struct Tcl_LogHandler {
        Tcl_LogHandlerProc(interp, level, message, ...)
        Tcl_SetLogLevelProc(interp, level)
    }
\end{verbatim}
\endgroup

Installs a new loghandler for a specified interp or globally. If no log handler is installed, the default action is to print the formatted message on standard error if the message level is equal to or greater than the loglevel; in the context of an interp the default action is to call the configured log handler (which does the same thing by default)
\setcounter{enumi}{3}
\item{}
\textbf{interp logger} ?\textit{loggerCommandFragment}?

Gets or sets the log handler for an interp. The log handler will have these arguments appended on invoke: \textit{level message args}
\setcounter{enumi}{4}
\item{}
\textbf{log} \textit{level message}

Tcl equivalent of \textbf{Tcl\_Log}.
\end{enumerate}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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