home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tcl2-73c.zip / tcl7.3 / doc / file.n < prev    next >
Text File  |  1993-05-03  |  6KB  |  147 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/file.n,v 1.1 93/05/03 17:09:38 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS file tcl
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. file \- Manipulate file names and attributes
  29. .SH SYNOPSIS
  30. \fBfile \fIoption\fR \fIname\fR ?\fIarg arg ...\fR?
  31. .BE
  32.  
  33. .SH DESCRIPTION
  34. .PP
  35. This command provides several operations on a file's name or attributes.
  36. \fIName\fR is the name of a file;
  37. if it starts with a tilde, then tilde substitution is done before
  38. executing the command (see the manual entry for \fBTcl_TildeSubst\fR
  39. for details).
  40. \fIOption\fR indicates what to do with the file name.  Any unique
  41. abbreviation for \fIoption\fR is acceptable.  The valid options are:
  42. .TP
  43. \fBfile \fBatime \fIname\fR
  44. Returns a decimal string giving the time at which file \fIname\fR
  45. was last accessed.  The time is measured in the standard POSIX
  46. fashion as seconds from a fixed starting time (often January 1, 1970).
  47. If the file doesn't exist or its access time cannot be queried then an
  48. error is generated.
  49. .TP
  50. \fBfile \fBdirname \fIname\fR
  51. Returns all of the characters in \fIname\fR up to but not including
  52. the last slash character.  If there are no slashes in \fIname\fR
  53. then returns ``.''.  If the last slash in \fIname\fR is its first
  54. character, then return ``/''.
  55. .TP
  56. \fBfile \fBexecutable \fIname\fR
  57. Returns \fB1\fR if file \fIname\fR is executable by
  58. the current user, \fB0\fR otherwise.
  59. .TP
  60. \fBfile \fBexists \fIname\fR
  61. Returns \fB1\fR if file \fIname\fR exists and the current user has
  62. search privileges for the directories leading to it, \fB0\fR otherwise.
  63. .TP
  64. \fBfile \fBextension \fIname\fR
  65. Returns all of the characters in \fIname\fR after and including the
  66. last dot in \fIname\fR.  If there is no dot in \fIname\fR then returns
  67. the empty string.
  68. .TP
  69. \fBfile \fBisdirectory \fIname\fR
  70. Returns \fB1\fR if file \fIname\fR is a directory,
  71. \fB0\fR otherwise.
  72. .TP
  73. \fBfile \fBisfile \fIname\fR
  74. Returns \fB1\fR if file \fIname\fR is a regular file,
  75. \fB0\fR otherwise.
  76. .TP
  77. \fBfile lstat \fIname varName\fR
  78. Same as \fBstat\fR option (see below) except uses the \fIlstat\fR
  79. kernel call instead of \fIstat\fR.  This means that if \fIname\fR
  80. refers to a symbolic link the information returned in \fIvarName\fR
  81. is for the link rather than the file it refers to.  On systems that
  82. don't support symbolic links this option behaves exactly the same
  83. as the \fBstat\fR option.
  84. .TP
  85. \fBfile \fBmtime \fIname\fR
  86. Returns a decimal string giving the time at which file \fIname\fR
  87. was last modified.  The time is measured in the standard POSIX
  88. fashion as seconds from a fixed starting time (often January 1, 1970).
  89. If the file doesn't exist or its modified time cannot be queried then an
  90. error is generated.
  91. .TP
  92. \fBfile \fBowned \fIname\fR
  93. Returns \fB1\fR if file \fIname\fR is owned by the current user,
  94. \fB0\fR otherwise.
  95. .TP
  96. \fBfile \fBreadable \fIname\fR
  97. Returns \fB1\fR if file \fIname\fR is readable by
  98. the current user, \fB0\fR otherwise.
  99. .TP
  100. \fBfile readlink \fIname\fR
  101. Returns the value of the symbolic link given by \fIname\fR (i.e. the
  102. name of the file it points to).  If
  103. \fIname\fR isn't a symbolic link or its value cannot be read, then
  104. an error is returned.  On systems that don't support symbolic links
  105. this option is undefined.
  106. .TP
  107. \fBfile \fBrootname \fIname\fR
  108. Returns all of the characters in \fIname\fR up to but not including
  109. the last ``.'' character in the name.  If \fIname\fR doesn't contain
  110. a dot, then returns \fIname\fR.
  111. .TP
  112. \fBfile \fBsize \fIname\fR
  113. Returns a decimal string giving the size of file \fIname\fR in bytes.
  114. If the file doesn't exist or its size cannot be queried then an
  115. error is generated.
  116. .TP
  117. \fBfile \fBstat  \fIname varName\fR
  118. Invokes the \fBstat\fR kernel call on \fIname\fR, and uses the
  119. variable given by \fIvarName\fR to hold information returned from
  120. the kernel call.
  121. \fIVarName\fR is treated as an array variable,
  122. and the following elements of that variable are set: \fBatime\fR,
  123. \fBctime\fR, \fBdev\fR, \fBgid\fR, \fBino\fR, \fBmode\fR, \fBmtime\fR,
  124. \fBnlink\fR, \fBsize\fR, \fBtype\fR, \fBuid\fR.
  125. Each element except \fBtype\fR is a decimal string with the value of
  126. the corresponding field from the \fBstat\fR return structure; see the
  127. manual entry for \fBstat\fR for details on the meanings of the values.
  128. The \fBtype\fR element gives the type of the file in the same form
  129. returned by the command \fBfile type\fR.
  130. This command returns an empty string.
  131. .TP
  132. \fBfile \fBtail \fIname\fR
  133. Returns all of the characters in \fIname\fR after the last slash.
  134. If \fIname\fR contains no slashes then returns \fIname\fR.
  135. .TP
  136. \fBfile \fBtype \fIname\fR
  137. Returns a string giving the type of file \fIname\fR, which will be
  138. one of \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR,
  139. \fBblockSpecial\fR, \fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
  140. .TP
  141. \fBfile \fBwritable \fIname\fR
  142. Returns \fB1\fR if file \fIname\fR is writable by
  143. the current user, \fB0\fR otherwise.
  144.  
  145. .SH KEYWORDS
  146. attributes, directory, file, name, stat
  147.