2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 '\" RCS: @(#) $Id: filename.n,v 1.7 2001/09/04 18:06:34 vincentdarley Exp $
9 '\" The definitions below are for supplemental macros used in Tcl/Tk
12 '\" .AP type name in/out ?indent?
13 '\" Start paragraph describing an argument to a library procedure.
14 '\" type is type of argument (int, etc.), in/out is either "in", "out",
15 '\" or "in/out" to describe whether procedure reads or modifies arg,
16 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 '\" needed; use .AS below instead)
20 '\" Give maximum sizes of arguments for setting tab stops. Type and
21 '\" name are examples of largest possible arguments that will be passed
22 '\" to .AP later. If args are omitted, default tab stops are used.
25 '\" Start box enclosure. From here until next .BE, everything will be
26 '\" enclosed in one large box.
29 '\" End of box enclosure.
32 '\" Begin code excerpt.
37 '\" .VS ?version? ?br?
38 '\" Begin vertical sidebar, for use in marking newly-changed parts
39 '\" of man pages. The first argument is ignored and used for recording
40 '\" the version when the .VS was added, so that the sidebars can be
41 '\" found and removed when they reach a certain age. If another argument
42 '\" is present, then a line break is forced before starting the sidebar.
45 '\" End of vertical sidebar.
48 '\" Begin an indented unfilled display.
51 '\" End of indented unfilled display.
54 '\" Start of list of standard options for a Tk widget. The
55 '\" options follow on successive lines, in four columns separated
59 '\" End of list of standard options for a Tk widget.
61 '\" .OP cmdName dbName dbClass
62 '\" Start of description of a specific option. cmdName gives the
63 '\" option's name as specified in the class command, dbName gives
64 '\" the option's name in the option database, and dbClass gives
65 '\" the option's class in the option database.
68 '\" Print arg1 underlined, then print arg2 normally.
70 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
72 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
76 '\" # Start an argument description
80 . ie !"\\$2"" .TP \\n()Cu
85 \&\\$1 \\fI\\$2\\fP (\\$3)
98 '\" # define tabbing values for .AP
101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
107 .AS Tcl_Interp Tcl_CreateInterp in/out
108 '\" # BS - start boxed text
109 '\" # ^y = starting y location
117 .if n \l'\\n(.lu\(ul'
120 '\" # BE - end boxed text (draw box now)
125 .ie n \l'\\n(^lu\(ul'
127 .\" Draw four-sided box normally, but don't draw top of
128 .\" box if the box started on an earlier page.
130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 '\" # VS - start vertical sidebar
141 '\" # ^Y = starting y location
142 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
146 .ie n 'mc \s12\(br\s0
149 '\" # VE - end of vertical sidebar
157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
164 '\" # Special macro to handle page bottom: finish off current
165 '\" # box/sidebar if in box/sidebar mode, then invoked standard
166 '\" # page bottom macro.
173 .\" Draw three-sided box if this is the box's first page,
174 .\" draw two sides but no top otherwise.
175 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
179 .nr ^x \\n(^tu+1v-\\n(^Yu
180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
193 '\" # DS - begin display
199 '\" # DE - end display
205 '\" # SO - start of list of standard options
207 .SH "STANDARD OPTIONS"
213 '\" # SE - end of list of standard options
218 See the \\fBoptions\\fR manual entry for details on the standard options.
220 '\" # OP - start of full description for a single option
225 Command-Line Name: \\fB\\$1\\fR
226 Database Name: \\fB\\$2\\fR
227 Database Class: \\fB\\$3\\fR
231 '\" # CS - begin code excerpt
237 '\" # CE - end code excerpt
245 .TH filename n 7.5 Tcl "Tcl Built-In Commands"
247 '\" Note: do not modify the .SH NAME line immediately below!
249 filename \- File name conventions supported by Tcl commands
253 All Tcl commands and C procedures that take file names as arguments
254 expect the file names to be in one of three forms, depending on the
255 current platform. On each platform, Tcl supports file names in the
256 standard forms(s) for that platform. In addition, on all platforms,
257 Tcl supports a Unix-like syntax intended to provide a convenient way
258 of constructing simple file names. However, scripts that are intended
259 to be portable should not assume a particular form for file names.
260 Instead, portable scripts must use the \fBfile split\fR and \fBfile
261 join\fR commands to manipulate file names (see the \fBfile\fR manual
262 entry for more details).
266 File names are grouped into three general types based on the starting point
267 for the path used to specify the file: absolute, relative, and
268 volume-relative. Absolute names are completely qualified, giving a path to
269 the file relative to a particular volume and the root directory on that
270 volume. Relative names are unqualified, giving a path to the file relative
271 to the current working directory. Volume-relative names are partially
272 qualified, either giving the path relative to the root directory on the
273 current volume, or relative to the current directory of the specified
274 volume. The \fBfile pathtype\fR command can be used to determine the
275 type of a given path.
279 The rules for native names depend on the value reported in the Tcl
280 array element \fBtcl_platform(platform)\fR:
283 On Apple Macintosh systems, Tcl supports two forms of path names. The
284 normal Mac style names use colons as path separators. Paths may be
285 relative or absolute, and file names may contain any character other
286 than colon. A leading colon causes the rest of the path to be
287 interpreted relative to the current directory. If a path contains a
288 colon that is not at the beginning, then the path is interpreted as an
289 absolute path. Sequences of two or more colons anywhere in the path
290 are used to construct relative paths where \fB::\fR refers to the
291 parent of the current directory, \fB:::\fR refers to the parent of the
292 parent, and so forth.
295 In addition to Macintosh style names, Tcl also supports a subset of
296 Unix-like names. If a path contains no colons, then it is interpreted
297 like a Unix path. Slash is used as the path separator. The file name
298 \fB\&.\fR refers to the current directory, and \fB\&..\fR refers to the
299 parent of the current directory. However, some names like \fB/\fR or
300 \fB/..\fR have no mapping, and are interpreted as Macintosh names. In
301 general, commands that generate file names will return Macintosh style
302 names, but commands that accept file names will take both Macintosh
303 and Unix-style names.
305 The following examples illustrate various forms of path names:
308 Relative path to the current folder.
311 Relative path to a file named \fBMyFile\fR in the current folder.
314 Absolute path to a file named \fBMyFile\fR on the device named \fBMyDisk\fR.
317 Relative path to a file name \fBMyFile\fR in a folder named
318 \fBMyDir\fR in the current folder.
321 Relative path to a file named \fBMyFile\fR in the folder above the
325 Relative path to a file named \fBMyFile\fR in the folder two levels above the
329 Absolute path to a file named \fBMyFile\fR on the device named
333 Relative path to a file named \fBMyFile\fR in the folder above the
338 On Unix platforms, Tcl uses path names where the components are
339 separated by slashes. Path names may be relative or absolute, and
340 file names may contain any character other than slash. The file names
341 \fB\&.\fR and \fB\&..\fR are special and refer to the current directory
342 and the parent of the current directory respectively. Multiple
343 adjacent slash characters are interpreted as a single separator.
344 The following examples illustrate various forms of path names:
348 Absolute path to the root directory.
351 Absolute path to the file named \fBpasswd\fR in the directory
352 \fBetc\fR in the root directory.
355 Relative path to the current directory.
358 Relative path to the file \fBfoo\fR in the current directory.
361 Relative path to the file \fBbar\fR in the directory \fBfoo\fR in the
365 Relative path to the file \fBfoo\fR in the directory above the current
370 On Microsoft Windows platforms, Tcl supports both drive-relative and UNC
371 style names. Both \fB/\fR and \fB\e\fR may be used as directory separators
372 in either type of name. Drive-relative names consist of an optional drive
373 specifier followed by an absolute or relative path. UNC paths follow the
374 general form \fB\e\eservername\esharename\epath\efile\fR, but must at
375 the very least contain the server and share components, i.e.
376 \fB\e\eservername\esharename\fR. In both forms,
377 the file names \fB.\fR and \fB..\fR are special and refer to the current
378 directory and the parent of the current directory respectively. The
379 following examples illustrate various forms of path names:
382 \fB\&\e\eHost\eshare/file\fR
383 Absolute UNC path to a file called \fBfile\fR in the root directory of
384 the export point \fBshare\fR on the host \fBHost\fR. Note that
385 repeated use of \fBfile dirname\fR on this path will give
386 \fB//Host/share\fR, and will never give just /fB//Host/fR.
389 Volume-relative path to a file \fBfoo\fR in the current directory on drive
393 Absolute path to a file \fBfoo\fR in the root directory of drive
397 Relative path to a file \fBbar\fR in the \fBfoo\fR directory in the current
398 directory on the current volume.
401 Volume-relative path to a file \fBfoo\fR in the root directory of the current
405 Volume-relative path to a file \fBfoo\fR in the root directory of the current
406 volume. This is not a valid UNC path, so the assumption is that the
407 extra backslashes are superfluous.
410 .SH "TILDE SUBSTITUTION"
412 In addition to the file name rules described above, Tcl also supports
413 \fIcsh\fR-style tilde substitution. If a file name starts with a
414 tilde, then the file name will be interpreted as if the first element
415 is replaced with the location of the home directory for the given
416 user. If the tilde is followed immediately by a separator, then the
417 \fB$HOME\fR environment variable is substituted. Otherwise the
418 characters between the tilde and the next separator are taken as a
419 user name, which is used to retrieve the user's home directory for
422 The Macintosh and Windows platforms do not support tilde substitution
423 when a user name follows the tilde. On these platforms, attempts to
424 use a tilde followed by a user name will generate an error that the
425 user does not exist when Tcl attempts to interpret that part of the
426 path or otherwise access the file. The behaviour of these paths
427 when not trying to interpret them is the same as on Unix. File
428 names that have a tilde without a user name will be correctly
429 substituted using the \fB$HOME\fR environment variable, just like
432 .SH "PORTABILITY ISSUES"
434 Not all file systems are case sensitive, so scripts should avoid code
435 that depends on the case of characters in a file name. In addition,
436 the character sets allowed on different devices may differ, so scripts
437 should choose file names that do not contain special characters like:
438 \fB<>:"/\e|\fR. The safest approach is to use names consisting of
439 alphanumeric characters only. Also Windows 3.1 only supports file
440 names with a root of no more than 8 characters and an extension of no
441 more than 3 characters.
443 On Windows platforms there are file and path length restrictions.
444 Complete paths or filenames longer than about 260 characters will lead
445 to errors in most file operations.
448 current directory, absolute file name, relative file name,
449 volume-relative file name, portability