\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#99: Add 'file link' to Tcl}
\date{June 11, 2002}
\author{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 \#99}&\textbf{Add 'file link' to Tcl}\\\hline
Author&

Vince Darley \tipmail{vincentdarley}{users.sourceforge.net}
\\
Created&Tuesday, \(\text{11}^{\text{th}}\) June 2002\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.23 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

Tcl can read links, but cannot create them. This TIP proposes adding a \textit{file link} subcommand to allow cross-platform creation of links.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Proposal}

Add a new subcommand with the following syntax:
\begingroup\small\begin{verbatim}
      file link ?-linktype? linkName ?target?
\end{verbatim}
\endgroup

If only one argument is given, that argument is assumed to be \textit{linkName}, and this command returns the value of the link given by \textit{linkName} (i.e. the name of the file it points to). If \textit{linkName} isn't a link or its value cannot be read (as, for example, seems to be the case with hard links, which look just like ordinary files), then an error is returned.

If 2 arguments are given, then these are assumed to be \textit{linkName} and \textit{target}. If \textit{linkName} already exists, or if \textit{target} doesn't exist, an error will be returned. Otherwise, Tcl creates a new link called \textit{linkName} which points to the existing filesystem object at \textit{target}, where the type of the link is platform-specific (on Unix a symbolic link will be the default). This is useful for the case where the user wishes to create a link in a cross-platform way, and doesn't care what type of link is created.

If the user wishes to make a link of a \textit{specific type only}, (and signal an error if for some reason that is not possible), then the optional \textit{linktype} argument should be given. Accepted values for linktype are \textit{-symbolic} and \textit{-hard}.

When creating links on filesystems that either do not support any links, or do not support the specific type requested, an error message will be returned (in particular Windows 95, 98 and ME do not support any symbolic links at present, but Unix, MacOS and Windows NT/2000/XP (on NTFS drives) do).

The TIP proposes implementing:
\begingroup\small\begin{verbatim}
           Unix,MacOSX      Win-NTFS           MacOS
symbolic:      yes        directories-only      yes
hard:       files-only     files-only           no
\end{verbatim}
\endgroup

This also leaves the avenue open, in the future, for the addition of other link types (e.g. Windows shortcuts) through additions to list of acceptable \textit{linktype}s. This TIP only proposes adding the above options.

This means that a general \textit{[file link \$linkname \$target]} should always succeed on the above platforms (for both files and directories), but uses of \textit{-hard} or \textit{-symbolic} could fail, depending on the current platform, and the type of the path.

\section{Rationale}

There are many requests on comp.lang.tcl for this functionality (see \url{http://groups.google.com/groups?dq=&hl=en&lr=&ie=UTF8&oe=UTF8&threadm=4dd3bea3.0206100250.95eeb4e\%40posting.google.com&rnum=1&prev=/&frame=on} for a recent thread), and if Tcl can read links (\textit{file readlink}, \textit{file lstat}), it really ought to be able to write them.

Discussion has shown that both symbolic and hard links are desirable, and that for cross-platform use a general-purpose \textit{file link} which creates \textit{something} is useful.

Some users would prefer hard links to be the default, but on balance most people commenting seemed to prefer symbolic links as default. This has the added benefit that symbolic links will then be the default on MacOS, Unix and Windows for everything, \textit{except} files on WinTcl (where hard-links are required).

\section{Alternatives}

There is no cross-platform alternative available. TclX provides a \textit{link} command for Unix only, and Unix platforms can also use \textit{exec ln ?-s?} command to achieve the same effect.

\section{Reference Implementation}

Tcl contains a \textit{testfilelink} command in \textit{generic/tclTest.c}, which is a partial implementation used by the test suite. For a full implementation of this TIP, including the \textit{-linktype} switch, see:

\textit{ \url{http://sourceforge.net/tracker/index.php?func=detail&aid=562970&group_id=10894&atid=310894} }

which includes extensive docs and tests.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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