Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | '\" |
2 | '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. | |
3 | '\" | |
4 | '\" See the file "license.terms" for information on usage and redistribution | |
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
6 | '\" | |
7 | '\" RCS: @(#) $Id: filename.n,v 1.7.12.1 2004/10/27 12:52:40 dkf Exp $ | |
8 | '\" | |
9 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
10 | '\" manual entries. | |
11 | '\" | |
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) | |
18 | '\" | |
19 | '\" .AS ?type? ?name? | |
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. | |
23 | '\" | |
24 | '\" .BS | |
25 | '\" Start box enclosure. From here until next .BE, everything will be | |
26 | '\" enclosed in one large box. | |
27 | '\" | |
28 | '\" .BE | |
29 | '\" End of box enclosure. | |
30 | '\" | |
31 | '\" .CS | |
32 | '\" Begin code excerpt. | |
33 | '\" | |
34 | '\" .CE | |
35 | '\" End code excerpt. | |
36 | '\" | |
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. | |
43 | '\" | |
44 | '\" .VE | |
45 | '\" End of vertical sidebar. | |
46 | '\" | |
47 | '\" .DS | |
48 | '\" Begin an indented unfilled display. | |
49 | '\" | |
50 | '\" .DE | |
51 | '\" End of indented unfilled display. | |
52 | '\" | |
53 | '\" .SO | |
54 | '\" Start of list of standard options for a Tk widget. The | |
55 | '\" options follow on successive lines, in four columns separated | |
56 | '\" by tabs. | |
57 | '\" | |
58 | '\" .SE | |
59 | '\" End of list of standard options for a Tk widget. | |
60 | '\" | |
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. | |
66 | '\" | |
67 | '\" .UL arg1 arg2 | |
68 | '\" Print arg1 underlined, then print arg2 normally. | |
69 | '\" | |
70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
71 | '\" | |
72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
73 | .if t .wh -1.3i ^B | |
74 | .nr ^l \n(.l | |
75 | .ad b | |
76 | '\" # Start an argument description | |
77 | .de AP | |
78 | .ie !"\\$4"" .TP \\$4 | |
79 | .el \{\ | |
80 | . ie !"\\$2"" .TP \\n()Cu | |
81 | . el .TP 15 | |
82 | .\} | |
83 | .ta \\n()Au \\n()Bu | |
84 | .ie !"\\$3"" \{\ | |
85 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
86 | .\".b | |
87 | .\} | |
88 | .el \{\ | |
89 | .br | |
90 | .ie !"\\$2"" \{\ | |
91 | \&\\$1 \\fI\\$2\\fP | |
92 | .\} | |
93 | .el \{\ | |
94 | \&\\fI\\$1\\fP | |
95 | .\} | |
96 | .\} | |
97 | .. | |
98 | '\" # define tabbing values for .AP | |
99 | .de AS | |
100 | .nr )A 10n | |
101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
102 | .nr )B \\n()Au+15n | |
103 | .\" | |
104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
106 | .. | |
107 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
108 | '\" # BS - start boxed text | |
109 | '\" # ^y = starting y location | |
110 | '\" # ^b = 1 | |
111 | .de BS | |
112 | .br | |
113 | .mk ^y | |
114 | .nr ^b 1u | |
115 | .if n .nf | |
116 | .if n .ti 0 | |
117 | .if n \l'\\n(.lu\(ul' | |
118 | .if n .fi | |
119 | .. | |
120 | '\" # BE - end boxed text (draw box now) | |
121 | .de BE | |
122 | .nf | |
123 | .ti 0 | |
124 | .mk ^t | |
125 | .ie n \l'\\n(^lu\(ul' | |
126 | .el \{\ | |
127 | .\" Draw four-sided box normally, but don't draw top of | |
128 | .\" box if the box started on an earlier page. | |
129 | .ie !\\n(^b-1 \{\ | |
130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
131 | .\} | |
132 | .el \}\ | |
133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
134 | .\} | |
135 | .\} | |
136 | .fi | |
137 | .br | |
138 | .nr ^b 0 | |
139 | .. | |
140 | '\" # VS - start vertical sidebar | |
141 | '\" # ^Y = starting y location | |
142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
143 | .de VS | |
144 | .if !"\\$2"" .br | |
145 | .mk ^Y | |
146 | .ie n 'mc \s12\(br\s0 | |
147 | .el .nr ^v 1u | |
148 | .. | |
149 | '\" # VE - end of vertical sidebar | |
150 | .de VE | |
151 | .ie n 'mc | |
152 | .el \{\ | |
153 | .ev 2 | |
154 | .nf | |
155 | .ti 0 | |
156 | .mk ^t | |
157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
158 | .sp -1 | |
159 | .fi | |
160 | .ev | |
161 | .\} | |
162 | .nr ^v 0 | |
163 | .. | |
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. | |
167 | .de ^B | |
168 | .ev 2 | |
169 | 'ti 0 | |
170 | 'nf | |
171 | .mk ^t | |
172 | .if \\n(^b \{\ | |
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 | |
177 | .\} | |
178 | .if \\n(^v \{\ | |
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 | |
181 | .\} | |
182 | .bp | |
183 | 'fi | |
184 | .ev | |
185 | .if \\n(^b \{\ | |
186 | .mk ^y | |
187 | .nr ^b 2 | |
188 | .\} | |
189 | .if \\n(^v \{\ | |
190 | .mk ^Y | |
191 | .\} | |
192 | .. | |
193 | '\" # DS - begin display | |
194 | .de DS | |
195 | .RS | |
196 | .nf | |
197 | .sp | |
198 | .. | |
199 | '\" # DE - end display | |
200 | .de DE | |
201 | .fi | |
202 | .RE | |
203 | .sp | |
204 | .. | |
205 | '\" # SO - start of list of standard options | |
206 | .de SO | |
207 | .SH "STANDARD OPTIONS" | |
208 | .LP | |
209 | .nf | |
210 | .ta 5.5c 11c | |
211 | .ft B | |
212 | .. | |
213 | '\" # SE - end of list of standard options | |
214 | .de SE | |
215 | .fi | |
216 | .ft R | |
217 | .LP | |
218 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
219 | .. | |
220 | '\" # OP - start of full description for a single option | |
221 | .de OP | |
222 | .LP | |
223 | .nf | |
224 | .ta 4c | |
225 | Command-Line Name: \\fB\\$1\\fR | |
226 | Database Name: \\fB\\$2\\fR | |
227 | Database Class: \\fB\\$3\\fR | |
228 | .fi | |
229 | .IP | |
230 | .. | |
231 | '\" # CS - begin code excerpt | |
232 | .de CS | |
233 | .RS | |
234 | .nf | |
235 | .ta .25i .5i .75i 1i | |
236 | .. | |
237 | '\" # CE - end code excerpt | |
238 | .de CE | |
239 | .fi | |
240 | .RE | |
241 | .. | |
242 | .de UL | |
243 | \\$1\l'|0\(ul'\\$2 | |
244 | .. | |
245 | .TH filename n 7.5 Tcl "Tcl Built-In Commands" | |
246 | .BS | |
247 | '\" Note: do not modify the .SH NAME line immediately below! | |
248 | .SH NAME | |
249 | filename \- File name conventions supported by Tcl commands | |
250 | .BE | |
251 | .SH INTRODUCTION | |
252 | .PP | |
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). | |
263 | ||
264 | .SH "PATH TYPES" | |
265 | .PP | |
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. | |
276 | ||
277 | .SH "PATH SYNTAX" | |
278 | .PP | |
279 | The rules for native names depend on the value reported in the Tcl | |
280 | array element \fBtcl_platform(platform)\fR: | |
281 | .TP 10 | |
282 | \fBmac\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. | |
293 | .RS | |
294 | .PP | |
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. | |
304 | .PP | |
305 | The following examples illustrate various forms of path names: | |
306 | .TP 15 | |
307 | \fB:\fR | |
308 | Relative path to the current folder. | |
309 | .TP 15 | |
310 | \fBMyFile\fR | |
311 | Relative path to a file named \fBMyFile\fR in the current folder. | |
312 | .TP 15 | |
313 | \fBMyDisk:MyFile\fR | |
314 | Absolute path to a file named \fBMyFile\fR on the device named \fBMyDisk\fR. | |
315 | .TP 15 | |
316 | \fB:MyDir:MyFile\fR | |
317 | Relative path to a file name \fBMyFile\fR in a folder named | |
318 | \fBMyDir\fR in the current folder. | |
319 | .TP 15 | |
320 | \fB::MyFile\fR | |
321 | Relative path to a file named \fBMyFile\fR in the folder above the | |
322 | current folder. | |
323 | .TP 15 | |
324 | \fB:::MyFile\fR | |
325 | Relative path to a file named \fBMyFile\fR in the folder two levels above the | |
326 | current folder. | |
327 | .TP 15 | |
328 | \fB/MyDisk/MyFile\fR | |
329 | Absolute path to a file named \fBMyFile\fR on the device named | |
330 | \fBMyDisk\fR. | |
331 | .TP 15 | |
332 | \fB\&../MyFile\fR | |
333 | Relative path to a file named \fBMyFile\fR in the folder above the | |
334 | current folder. | |
335 | .RE | |
336 | .TP | |
337 | \fBunix\fR | |
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: | |
345 | .RS | |
346 | .TP 15 | |
347 | \fB/\fR | |
348 | Absolute path to the root directory. | |
349 | .TP 15 | |
350 | \fB/etc/passwd\fR | |
351 | Absolute path to the file named \fBpasswd\fR in the directory | |
352 | \fBetc\fR in the root directory. | |
353 | .TP 15 | |
354 | \fB\&.\fR | |
355 | Relative path to the current directory. | |
356 | .TP 15 | |
357 | \fBfoo\fR | |
358 | Relative path to the file \fBfoo\fR in the current directory. | |
359 | .TP 15 | |
360 | \fBfoo/bar\fR | |
361 | Relative path to the file \fBbar\fR in the directory \fBfoo\fR in the | |
362 | current directory. | |
363 | .TP 15 | |
364 | \fB\&../foo\fR | |
365 | Relative path to the file \fBfoo\fR in the directory above the current | |
366 | directory. | |
367 | .RE | |
368 | .TP | |
369 | \fBwindows\fR | |
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: | |
380 | .RS | |
381 | .TP 15 | |
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. | |
387 | .TP 15 | |
388 | \fBc:foo\fR | |
389 | Volume-relative path to a file \fBfoo\fR in the current directory on drive | |
390 | \fBc\fR. | |
391 | .TP 15 | |
392 | \fBc:/foo\fR | |
393 | Absolute path to a file \fBfoo\fR in the root directory of drive | |
394 | \fBc\fR. | |
395 | .TP 15 | |
396 | \fBfoo\ebar\fR | |
397 | Relative path to a file \fBbar\fR in the \fBfoo\fR directory in the current | |
398 | directory on the current volume. | |
399 | .TP 15 | |
400 | \fB\&\efoo\fR | |
401 | Volume-relative path to a file \fBfoo\fR in the root directory of the current | |
402 | volume. | |
403 | .TP 15 | |
404 | \fB\&\e\efoo\fR | |
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. | |
408 | .RE | |
409 | ||
410 | .SH "TILDE SUBSTITUTION" | |
411 | .PP | |
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 | |
420 | substitution. | |
421 | .PP | |
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 | |
430 | for Unix. | |
431 | ||
432 | .SH "PORTABILITY ISSUES" | |
433 | .PP | |
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. | |
442 | .PP | |
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. | |
446 | .PP | |
447 | Another Windows peculiarity is that any number of trailing dots '.' in | |
448 | filenames are totally ignored, so, for example, attempts to create a | |
449 | file or directory with a name "foo." will result in the creation of a | |
450 | file/directory with name "foo". This fact is reflected in the | |
451 | results of 'file normalize'. Furthermore, a file name consisting only | |
452 | of dots '.........' or dots with trailing characters '.....abc' is | |
453 | illegal. | |
454 | .SH KEYWORDS | |
455 | current directory, absolute file name, relative file name, | |
456 | volume-relative file name, portability | |
457 | ||
458 | .SH "SEE ALSO" | |
459 | file(n), glob(n) |