raw/mann/filename.n

   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.1 2003/12/20 03:31:54 bbbush 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: filename.n,v 1.1 2003/12/20 03:31:54 bbbush 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.  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:
 378 .RS
 379 .TP 15
 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.
 383 .TP 15
 384 \fBc:foo\fR
 385 Volume-relative path to a file \fBfoo\fR in the current directory on drive
 386 \fBc\fR.
 387 .TP 15
 388 \fBc:/foo\fR
 389 Absolute path to a file \fBfoo\fR in the root directory of drive
 390 \fBc\fR.
 391 .TP 15
 392 \fBfoo\ebar\fR
 393 Relative path to a file \fBbar\fR in the \fBfoo\fR directory in the current
 394 directory on the current volume.
 395 .TP 15
 396 \fB\&\efoo\fR
 397 Volume-relative path to a file \fBfoo\fR in the root directory of the current
 398 volume.
 399 .RE
 400
 401 .SH "TILDE SUBSTITUTION"
 402 .PP
 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
 411 substitution.
 412 .PP
 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.
 418
 419 .SH "PORTABILITY ISSUES"
 420 .PP
 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.
 429
 430 .SH KEYWORDS
 431 current directory, absolute file name, relative file name,
 432 volume-relative file name, portability
 433
 434 .SH "SEE ALSO"
 435 file(n), glob(n)