1fileutil(n) file utilities fileutil(n)
2______________________________________________________________________________
6
8 fileutil - Procedures implementing some file utilities
9
11 package require Tcl 8
12 package require fileutil ?1.16?
14 ::fileutil::lexnormalize path
16 ::fileutil::fullnormalize path
18 ::fileutil::test path codes ?msgvar? ?label?
20 ::fileutil::cat (?options? file)...
22 ::fileutil::writeFile ?options? file data
24 ::fileutil::appendToFile ?options? file data
26 ::fileutil::insertIntoFile ?options? file at data
28 ::fileutil::removeFromFile ?options? file at n
30 ::fileutil::replaceInFile ?options? file at n data
32 ::fileutil::updateInPlace ?options? file cmd
34 ::fileutil::fileType filename
36 ::fileutil::find ?basedir ?filtercmd??
38 ::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
40 ::fileutil::foreachLine var filename cmd
42 ::fileutil::grep pattern ?files?
44 ::fileutil::install ?-m mode? source destination
46 ::fileutil::stripN path n
48 ::fileutil::stripPwd path
50 ::fileutil::stripPath prefix path
52 ::fileutil::jail jail path
54 ::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
56 ::fileutil::tempdir
58 ::fileutil::tempdir path
60 ::fileutil::tempdirReset
62 ::fileutil::tempfile ?prefix?
64 ::fileutil::maketempdir ?-prefix str? ?-suffix str? ?-dir str?
66 ::fileutil::relative base dst
68 ::fileutil::relativeUrl base dst
70______________________________________________________________________________
72
74 This package provides implementations of standard unix utilities.
75 ::fileutil::lexnormalize path
77 This command performs purely lexical normalization on the path
78 and returns the changed path as its result. Symbolic links in
79 the path are not resolved.
80 Examples:
82 fileutil::lexnormalize /foo/./bar
85 => /foo/bar
86 fileutil::lexnormalize /foo/../bar
88 => /bar
89 ::fileutil::fullnormalize path
92 This command resolves all symbolic links in the path and returns
93 the changed path as its result. In contrast to the builtin file
94 normalize this command resolves a symbolic link in the last ele‐
95 ment of the path as well.
96 ::fileutil::test path codes ?msgvar? ?label?
98 A command for the testing of several properties of a path. The
99 properties to test for are specified in codes, either as a list
100 of keywords describing the properties, or as a string where each
101 letter is a shorthand for a property to test. The recognized
102 keywords, shorthands, and associated properties are shown in the
103 list below. The tests are executed in the order given to the
104 command.
105 The result of the command is a boolean value. It will be true if
107 and only if the path passes all the specified tests. In the
108 case of the path not passing one or more test the first failing
109 test will leave a message in the variable referenced by msgvar,
110 if such is specified. The message will be prefixed with label,
111 if it is specified. Note that the variabled referenced by msg‐
112 var is not touched at all if all the tests pass.
113 read file readable
116 write file writable
118 exists file exists
120 exec file executable
122 file file isfile
124 dir file isdirectory
126 ::fileutil::cat (?options? file)...
128 A tcl implementation of the UNIX cat command. Returns the con‐
129 tents of the specified file(s). The arguments are files to read,
130 with interspersed options configuring the process. If there are
131 problems reading any of the files, an error will occur, and no
132 data will be returned.
133 The options accepted are -encoding, -translation, -eofchar, and
135 --. With the exception of the last all options take a single
136 value as argument, as specified by the tcl builtin command fcon‐
137 figure. The -- has to be used to terminate option processing be‐
138 fore a file if that file's name begins with a dash.
139 Each file can have its own set of options coming before it, and
141 for anything not specified directly the defaults are inherited
142 from the options of the previous file. The first file inherits
143 the system default for unspecified options.
144 ::fileutil::writeFile ?options? file data
146 The command replaces the current contents of the specified file
147 with data, with the process configured by the options. The com‐
148 mand accepts the same options as ::fileutil::cat. The specifica‐
149 tion of a non-existent file is legal and causes the command to
150 create the file (and all required but missing directories).
151 ::fileutil::appendToFile ?options? file data
153 This command is like ::fileutil::writeFile, except that the pre‐
154 vious contents of file are not replaced, but appended to. The
155 command accepts the same options as ::fileutil::cat
156 ::fileutil::insertIntoFile ?options? file at data
158 This comment is similar to ::fileutil::appendToFile, except that
159 the new data is not appended at the end, but inserted at a spec‐
160 ified location within the file. In further contrast this command
161 has to be given the path to an existing file. It will not create
162 a missing file, but throw an error instead.
163 The specified location at has to be an integer number in the
165 range 0 ... [file size file]. 0 will cause insertion of the new
166 data before the first character of the existing content, whereas
167 [file size file] causes insertion after the last character of
168 the existing content, i.e. appending.
169 The command accepts the same options as ::fileutil::cat.
171 ::fileutil::removeFromFile ?options? file at n
173 This command is the complement to ::fileutil::insertIntoFile,
174 removing n characters from the file, starting at location at.
175 The specified location at has to be an integer number in the
176 range 0 ... [file size file] - n. 0 will cause the removal of
177 the new data to start with the first character of the existing
178 content, whereas [file size file] - n causes the removal of the
179 tail of the existing content, i.e. the truncation of the file.
180 The command accepts the same options as ::fileutil::cat.
182 ::fileutil::replaceInFile ?options? file at n data
184 This command is a combination of ::fileutil::removeFromFile and
185 ::fileutil::insertIntoFile. It first removes the part of the
186 contents specified by the arguments at and n, and then inserts
187 data at the given location, effectively replacing the removed by
188 content with data. All constraints imposed on at and n by
189 ::fileutil::removeFromFile and ::fileutil::insertIntoFile are
190 obeyed.
191 The command accepts the same options as ::fileutil::cat.
193 ::fileutil::updateInPlace ?options? file cmd
195 This command can be seen as the generic core functionality of
196 ::fileutil::replaceInFile. It first reads the contents of the
197 specified file, then runs the command prefix cmd with that data
198 appended to it, and at last writes the result of that invokation
199 back as the new contents of the file.
200 If the executed command throws an error the file is not changed.
202 The command accepts the same options as ::fileutil::cat.
204 ::fileutil::fileType filename
206 An implementation of the UNIX file command, which uses various
207 heuristics to guess the type of a file. Returns a list specify‐
208 ing as much type information as can be determined about the
209 file, from most general (eg, "binary" or "text") to most spe‐
210 cific (eg, "gif"). For example, the return value for a GIF file
211 would be "binary graphic gif". The command will detect the fol‐
212 lowing types of files: directory, empty, binary, text, script
213 (with interpreter), executable elf, executable dos, executable
214 ne, executable pe, graphic gif, graphic jpeg, graphic png,
215 graphic tiff, graphic bitmap, html, xml (with doctype if avail‐
216 able), message pgp, binary pdf, text ps, text eps, binary grav‐
217 ity_wave_data_frame, compressed bzip, compressed gzip, com‐
218 pressed zip, compressed tar, audio wave, audio mpeg, and link.
219 It further detects doctools, doctoc, and docidx documentation
220 files, and tklib diagrams.
221 ::fileutil::find ?basedir ?filtercmd??
223 An implementation of the unix command find. Adapted from the
224 Tcler's Wiki. Takes at most two arguments, the path to the di‐
225 rectory to start searching from and a command to use to evaluate
226 interest in each file. The path defaults to ".", i.e. the cur‐
227 rent directory. The command defaults to the empty string, which
228 means that all files are of interest. The command takes care not
229 to lose itself in infinite loops upon encountering circular link
230 structures. The result of the command is a list containing the
231 paths to the interesting files.
232 The filtercmd, if specified, is interpreted as a command prefix
234 and one argument is added to it, the name of the file or direc‐
235 tory find is currently looking at. Note that this name is not
236 fully qualified. It has to be joined it with the result of pwd
237 to get an absolute filename.
238 The result of filtercmd is a boolean value that indicates if the
240 current file should be included in the list of interesting
241 files.
242 Example:
244 # find .tcl files
248 package require fileutil
249 proc is_tcl {name} {return [string match *.tcl $name]}
250 set tcl_files [fileutil::find . is_tcl]
251 ::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
254 This command is based upon the TclX command recursive_glob, ex‐
255 cept that it doesn't allow recursion over more than one direc‐
256 tory at a time. It uses ::fileutil::find internally and is thus
257 able to and does follow symbolic links, something the TclX com‐
258 mand does not do. First argument is the directory to start the
259 search in, second argument is a list of patterns. The command
260 returns a list of all files reachable through basedir whose
261 names match at least one of the patterns. The options before the
262 pattern-list determine the style of matching, either regexp or
263 glob. glob-style matching is the default if no options are
264 given. Usage of the option -- stops option processing. This al‐
265 lows the use of a leading '-' in the patterns.
266 ::fileutil::foreachLine var filename cmd
268 The command reads the file filename and executes the script cmd
269 for every line in the file. During the execution of the script
270 the variable var is set to the contents of the current line. The
271 return value of this command is the result of the last invoca‐
272 tion of the script cmd or the empty string if the file was
273 empty.
274 ::fileutil::grep pattern ?files?
276 Implementation of grep. Adapted from the Tcler's Wiki. The first
277 argument defines the pattern to search for. This is followed by
278 a list of files to search through. The list is optional and
279 stdin will be used if it is missing. The result of the proce‐
280 dures is a list containing the matches. Each match is a single
281 element of the list and contains filename, number and contents
282 of the matching line, separated by a colons.
283 ::fileutil::install ?-m mode? source destination
285 The install command is similar in functionality to the install
286 command found on many unix systems, or the shell script distrib‐
287 uted with many source distributions (unix/install-sh in the Tcl
288 sources, for example). It copies source, which can be either a
289 file or directory to destination, which should be a directory,
290 unless source is also a single file. The ?-m? option lets the
291 user specify a unix-style mode (either octal or symbolic - see
292 file attributes.
293 ::fileutil::stripN path n
295 Removes the first n elements from the specified path and returns
296 the modified path. If n is greater than the number of components
297 in path an empty string is returned. The number of components in
298 a given path may be determined by performing llength on the list
299 returned by file split.
300 ::fileutil::stripPwd path
302 If, and only if the path is inside of the directory returned by
303 [pwd] (or the current working directory itself) it is made rela‐
304 tive to that directory. In other words, the current working di‐
305 rectory is stripped from the path. The possibly modified path
306 is returned as the result of the command. If the current working
307 directory itself was specified for path the result is the string
308 ".".
309 ::fileutil::stripPath prefix path
311 If, and only of the path is inside of the directory "prefix" (or
312 the prefix directory itself) it is made relative to that direc‐
313 tory. In other words, the prefix directory is stripped from the
314 path. The possibly modified path is returned as the result of
315 the command. If the prefix directory itself was specified for
316 path the result is the string ".".
317 ::fileutil::jail jail path
319 This command ensures that the path is not escaping the directory
320 jail. It always returns an absolute path derived from path which
321 is within jail.
322 If path is an absolute path and already within jail it is re‐
324 turned unmodified.
325 An absolute path outside of jail is stripped of its root element
327 and then put into the jail by prefixing it with it. The same
328 happens if path is relative, except that nothing is stripped of
329 it. Before adding the jail prefix the path is lexically normal‐
330 ized to prevent the caller from using .. segments in path to es‐
331 cape the jail.
332 ::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
334 Implementation of touch. Alter the atime and mtime of the speci‐
335 fied files. If -c, do not create files if they do not already
336 exist. If -r, use the atime and mtime from ref_file. If -t, use
337 the integer clock value time. It is illegal to specify both -r
338 and -t. If -a, only change the atime. If -m, only change the
339 mtime.
340 This command is not available for Tcl versions less than 8.3.
342 ::fileutil::tempdir
344 The command returns the path of a directory where the caller can
345 place temporary files, such as "/tmp" on Unix systems. The algo‐
346 rithm we use to find the correct directory is as follows:
347 [1] The directory set by an invokation of ::fileutil::tempdir
349 with an argument. If this is present it is tried exclu‐
350 sively and none of the following item are tried.
351 [2] The directory named in the TMPDIR environment variable.
353 [3] The directory named in the TEMP environment variable.
355 [4] The directory named in the TMP environment variable.
357 [5] A platform specific location:
359 Windows
361 "C:\TEMP", "C:\TMP", "\TEMP", and "\TMP" are tried
362 in that order.
363 (classic) Macintosh
365 The TRASH_FOLDER environment variable is used.
366 This is most likely not correct.
367 Unix The directories "/tmp", "/var/tmp", and "/usr/tmp"
369 are tried in that order.
370 The algorithm utilized is mainly that used in the Python standard li‐
372 brary. The exception is the first item, the ability to have the search
373 overridden by a user-specified directory.
374 ::fileutil::tempdir path
376 In this mode the command sets the path as the first and only di‐
377 rectory to try as a temp. directory. See the previous item for
378 the use of the set directory. The command returns the empty
379 string.
380 ::fileutil::tempdirReset
382 Invoking this command clears the information set by the last
383 call of [::fileutil::tempdir path]. See the last item too.
384 ::fileutil::tempfile ?prefix?
386 The command generates a temporary file name suitable for writing
387 to, and the associated file. The file name will be unique, and
388 the file will be writable and contained in the appropriate sys‐
389 tem specific temp directory. The name of the file will be re‐
390 turned as the result of the command.
391 The code was taken from http://wiki.tcl.tk/772, attributed to
393 Igor Volobouev and anon.
394 ::fileutil::maketempdir ?-prefix str? ?-suffix str? ?-dir str?
396 The command generates a temporary directory suitable for writing
397 to. The directory name will be unique, and the directory will
398 be writable and contained in the appropriate system specific
399 temp directory. The name of the directory will be returned as
400 the result of the command.
401 The three options can used to tweak the behaviour of the com‐
403 mand:
404 -prefix str
406 The initial, fixed part of the directory name. Defaults
407 to tmp if not specified.
408 -suffix str
410 The fixed tail of the directory. Defaults to the empty
411 string if not specified.
412 -dir str
414 The directory to place the new directory into. Defaults
415 to the result of fileutil::tempdir if not specified.
416 The initial code for this was supplied by Miguel Martinez Lopez
418 [mailto:aplicacionamedida@gmail.com].
419 ::fileutil::relative base dst
421 This command takes two directory paths, both either absolute or
422 relative and computes the path of dst relative to base. This
423 relative path is returned as the result of the command. As im‐
424 plied in the previous sentence, the command is not able to com‐
425 pute this relationship between the arguments if one of the paths
426 is absolute and the other relative.
427 Note: The processing done by this command is purely lexical.
429 Symbolic links are not taken into account.
430 ::fileutil::relativeUrl base dst
432 This command takes two file paths, both either absolute or rela‐
433 tive and computes the path of dst relative to base, as seen from
434 inside of the base. This is the algorithm how a browser resolves
435 a relative link found in the currently shown file.
436 The computed relative path is returned as the result of the com‐
438 mand. As implied in the previous sentence, the command is not
439 able to compute this relationship between the arguments if one
440 of the paths is absolute and the other relative.
441 Note: The processing done by this command is purely lexical.
443 Symbolic links are not taken into account.
444
446 1.14.9 In this version fileutil::find's broken system for handling sym‐
447 links was replaced with one working correctly and properly enu‐
448 merating all the legal non-cyclic paths under a base directory.
449 While correct this means that certain pathological directory hi‐
451 erarchies with cross-linked sym-links will now take about
452 O(n**2) time to enumerate whereas the original broken code man‐
453 aged O(n) due to its brokenness.
454 A concrete example and extreme case is the "/sys" hierarchy un‐
456 der Linux where some hundred devices exist under both "/sys/de‐
457 vices" and "/sys/class" with the two sub-hierarchies linking to
458 the other, generating millions of legal paths to enumerate. The
459 structure, reduced to three devices, roughly looks like
460 /sys/class/tty/tty0 --> ../../dev/tty0
463 /sys/class/tty/tty1 --> ../../dev/tty1
464 /sys/class/tty/tty2 --> ../../dev/tty1
465 /sys/dev/tty0/bus
467 /sys/dev/tty0/subsystem --> ../../class/tty
468 /sys/dev/tty1/bus
469 /sys/dev/tty1/subsystem --> ../../class/tty
470 /sys/dev/tty2/bus
471 /sys/dev/tty2/subsystem --> ../../class/tty
472 The command fileutil::find currently has no way to escape this. When
475 having to handle such a pathological hierarchy It is recommended to
476 switch to package fileutil::traverse and the same-named command it pro‐
477 vides, and then use the -prefilter option to prevent the traverser from
478 following symbolic links, like so:
479 package require fileutil::traverse
482 proc NoLinks {fileName} {
484 if {[string equal [file type $fileName] link]} {
485 return 0
486 }
487 return 1
488 }
489 fileutil::traverse T /sys/devices -prefilter NoLinks
491 T foreach p {
492 puts $p
493 }
494 T destroy
495
498 This document, and the package it describes, will undoubtedly contain
499 bugs and other problems. Please report such in the category fileutil
500 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
501 also report any ideas for enhancements you may have for either package
502 and/or documentation.
503 When proposing code changes, please provide unified diffs, i.e the out‐
505 put of diff -u.
506 Note further that attachments are strongly preferred over inlined
508 patches. Attachments can be made by going to the Edit form of the
509 ticket immediately after its creation, and then using the left-most
510 button in the secondary navigation bar.
511
513 cat, file utilities, grep, temp file, test, touch, type
514
516 Programming tools
517tcllib 1.16 fileutil(n)