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.1 2003/12/20 03:31:54 bbbush 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: filename.n,v 1.1 2003/12/20 03:31:54 bbbush 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. In both forms,
375 the file names \fB.\fR and \fB..\fR are special and refer to the current
376 directory and the parent of the current directory respectively. The
377 following examples illustrate various forms of path names:
380 \fB\&\e\eHost\eshare/file\fR
381 Absolute UNC path to a file called \fBfile\fR in the root directory of
382 the export point \fBshare\fR on the host \fBHost\fR.
385 Volume-relative path to a file \fBfoo\fR in the current directory on drive
389 Absolute path to a file \fBfoo\fR in the root directory of drive
393 Relative path to a file \fBbar\fR in the \fBfoo\fR directory in the current
394 directory on the current volume.
397 Volume-relative path to a file \fBfoo\fR in the root directory of the current
401 .SH "TILDE SUBSTITUTION"
403 In addition to the file name rules described above, Tcl also supports
404 \fIcsh\fR-style tilde substitution. If a file name starts with a
405 tilde, then the file name will be interpreted as if the first element
406 is replaced with the location of the home directory for the given
407 user. If the tilde is followed immediately by a separator, then the
408 \fB$HOME\fR environment variable is substituted. Otherwise the
409 characters between the tilde and the next separator are taken as a
410 user name, which is used to retrieve the user's home directory
for
413 The Macintosh
and Windows platforms
do not support tilde substitution
414 when a user name follows the tilde
. On these platforms
, attempts to
415 use a tilde followed by a user name will generate an error
. File
416 names that have a tilde without a user name will be substituted
using
417 the
\fB$HOME
\fR environment variable
, just like
for Unix
.
419 .SH
"PORTABILITY ISSUES"
421 Not all file systems are case sensitive
, so scripts should avoid code
422 that depends on the case of characters
in a file name
. In addition
,
423 the character sets allowed on different devices may differ
, so scripts
424 should choose file names that
do not contain special characters like
:
425 \fB
<>:"/\e|\fR. The safest approach is to use names consisting of
426 alphanumeric characters only. Also Windows 3.1 only supports file
427 names with a root of no more than 8 characters and an extension of no
428 more than 3 characters.
431 current directory, absolute file name, relative file name,
432 volume-relative file name, portability