\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#316: Portable Access Functions for Stat Buffers}
\date{May 02, 2008}
\author{Donal K. Fellows}
\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 \#316}&\textbf{Portable Access Functions for Stat Buffers}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{manchester.ac.uk}
\\
Created&Friday, \(\text{2}^{\text{nd}}\) May 2008\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.4 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Tcl exposes the definition of the \textit{struct stat} type to users of its C API, but this can vary between builds. This TIP proposes a set of portable functions for reading (portable) fields out of those structures so that code does not need to match the API version when reading the fields (the most common case by far).
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The \textit{struct stat} type used by Tcl can be one of many different types depending on compile-time options (as a consequence of 64-bit filesystem support). Tcl conceals these details by wrapping the type as a \textit{Tcl\_StatBuf} and providing a way to allocate these independently of compiler configuration. However, there is no way to access the contents of the field without binding to a particular type i.e. particular compile time configuration of Tcl (and not necessarily the extension code using the API!) This TIP proposes a set of simple access functions to conceal these details and enable the portable read-only use of the \textit{Tcl\_StatBuf} type.

\section{Proposed Change}

This TIP proposes that the following functions will be defined. Each will take a pointer to a \textit{Tcl\_StatBuf} as its only argument, and will return the contents of the field indicated below.
\begin{description}
\item[Tcl\_GetFSDeviceFromStat]
Returns the \textit{st\_dev} field as an unsigned integer.
\item[Tcl\_GetFSInodeFromStat]
Returns the \textit{st\_ino} field as an unsigned integer.
\item[Tcl\_GetModeFromStat]
Returns the \textit{st\_mode} field as an unsigned integer.
\item[Tcl\_GetLinkCountFromStat]
Returns the \textit{st\_nlink} field as an integer.
\item[Tcl\_GetUserIdFromStat]
Returns the \textit{st\_uid} field as an integer.
\item[Tcl\_GetGroupIdFromStat]
Returns the \textit{st\_gid} field as an integer.
\item[Tcl\_GetDeviceTypeFromStat]
Returns the \textit{st\_rdev} field as an integer.
\item[Tcl\_GetAccessTimeFromStat]
Returns the \textit{st\_atime} field as a wide integer.
\item[Tcl\_GetModificationTimeFromStat]
Returns the \textit{st\_mtime} field as a wide integer.
\item[Tcl\_GetChangeTimeFromStat]
Returns the \textit{st\_ctime} field as a wide integer.
\item[Tcl\_GetSizeFromStat]
Returns the \textit{st\_size} field as an unsigned wide integer.
\item[Tcl\_GetBlocksFromStat]
Returns the \textit{st\_blocks} field as an unsigned wide integer.
\item[Tcl\_GetBlockSizeFromStat]
Returns the \textit{st\_blksize} field as an unsigned integer.
\end{description}

Some platforms may support other fields; these are not universal and are hence not portable.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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