1fileutil(n)                     file utilities                     fileutil(n)


8       fileutil - Procedures implementing some file utilities


11       package require Tcl  8
13       package require fileutil  ?1.16?
15       ::fileutil::lexnormalize path
17       ::fileutil::fullnormalize path
19       ::fileutil::test path codes ?msgvar? ?label?
21       ::fileutil::cat (?options? file)...
23       ::fileutil::writeFile ?options? file data
25       ::fileutil::appendToFile ?options? file data
27       ::fileutil::insertIntoFile ?options? file at data
29       ::fileutil::removeFromFile ?options? file at n
31       ::fileutil::replaceInFile ?options? file at n data
33       ::fileutil::updateInPlace ?options? file cmd
35       ::fileutil::fileType filename
37       ::fileutil::find ?basedir ?filtercmd??
39       ::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
41       ::fileutil::foreachLine var filename cmd
43       ::fileutil::grep pattern ?files?
45       ::fileutil::install ?-m mode? source destination
47       ::fileutil::stripN path n
49       ::fileutil::stripPwd path
51       ::fileutil::stripPath prefix path
53       ::fileutil::jail jail path
55       ::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
57       ::fileutil::tempdir
59       ::fileutil::tempdir path
61       ::fileutil::tempdirReset
63       ::fileutil::tempfile ?prefix?
65       ::fileutil::maketempdir ?-prefix str? ?-suffix str? ?-dir str?
67       ::fileutil::relative base dst
69       ::fileutil::relativeUrl base dst


74       This package provides implementations of standard unix utilities.
76       ::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.
81              Examples:
84                  fileutil::lexnormalize /foo/./bar
85                  => /foo/bar
87                  fileutil::lexnormalize /foo/../bar
88                  => /bar
91       ::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.
97       ::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.
106              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.
115              read   file readable
117              write  file writable
119              exists file exists
121              exec   file executable
123              file   file isfile
125              dir    file isdirectory
127       ::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.
134              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
138              before a file if that file's name begins with a dash.
140              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.
145       ::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).
152       ::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
157       ::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.
164              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.
170              The command accepts the same options as ::fileutil::cat.
172       ::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.
181              The command accepts the same options as ::fileutil::cat.
183       ::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.
192              The command accepts the same options as ::fileutil::cat.
194       ::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.
201              If the executed command throws an error the file is not changed.
203              The command accepts the same options as ::fileutil::cat.
205       ::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.
222       ::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
225              directory to start searching from and a command to use to evalu‐
226              ate interest in each file. The path defaults to  ".",  i.e.  the
227              current  directory.  The  command  defaults to the empty string,
228              which means that all files are of interest.  The  command  takes
229              care not to lose itself in infinite loops upon encountering cir‐
230              cular link structures. The result of the command is a list  con‐
231              taining the paths to the interesting files.
233              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.
239              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.
243              Example:
247                  # 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]
253       ::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
254              This  command  is  based  upon  the TclX command recursive_glob,
255              except 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
265              allows the use of a leading '-' in the patterns.
267       ::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.
275       ::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.
284       ::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.
294       ::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.
301       ::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
305              directory 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              ".".
310       ::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 ".".
318       ::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.
323              If  path  is  an  absolute  path  and  already within jail it is
324              returned unmodified.
326              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
331              escape the jail.
333       ::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.
341              This command is not available for Tcl versions less than 8.3.
343       ::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:
348              [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.
352              [2]    The directory named in the TMPDIR environment variable.
354              [3]    The directory named in the TEMP environment variable.
356              [4]    The directory named in the TMP environment variable.
358              [5]    A platform specific location:
360                     Windows
361                            "C:\TEMP", "C:\TMP", "\TEMP", and "\TMP" are tried
362                            in that order.
364                     (classic) Macintosh
365                            The  TRASH_FOLDER  environment  variable  is used.
366                            This is most likely not correct.
368                     Unix   The directories "/tmp", "/var/tmp", and "/usr/tmp"
369                            are tried in that order.
371       The  algorithm  utilized  is  mainly  that  used in the Python standard
372       library. The exception is the first  item,  the  ability  to  have  the
373       search overridden by a user-specified directory.
375       ::fileutil::tempdir path
376              In  this  mode  the  command sets the path as the first and only
377              directory 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.
381       ::fileutil::tempdirReset
382              Invoking this command clears the information  set  by  the  last
383              call of [::fileutil::tempdir path].  See the last item too.
385       ::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
390              returned as the result of the command.
392              The  code  was  taken from http://wiki.tcl.tk/772, attributed to
393              Igor Volobouev and anon.
395       ::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.
402              The three options can used to tweak the behaviour  of  the  com‐
403              mand:
405              -prefix str
406                     The  initial,  fixed part of the directory name. Defaults
407                     to tmp if not specified.
409              -suffix str
410                     The fixed tail of the directory. Defaults  to  the  empty
411                     string if not specified.
413              -dir str
414                     The  directory  to place the new directory into. Defaults
415                     to the result of fileutil::tempdir if not specified.
417       The initial code  for  this  was  supplied  by  Miguel  Martinez  Lopez
418       [mailto:aplicacionamedida@gmail.com].
420       ::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
424              implied in the previous sentence, the command  is  not  able  to
425              compute  this  relationship  between the arguments if one of the
426              paths is absolute and the other relative.
428              Note: The processing done by this  command  is  purely  lexical.
429              Symbolic links are not taken into account.
431       ::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.
437              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.
442              Note:  The  processing  done  by this command is purely lexical.
443              Symbolic links are not taken into account.


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.
450              While correct this means  that  certain  pathological  directory
451              hierarchies  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.
455              A  concrete  example  and  extreme  case is the "/sys" hierarchy
456              under  Linux  where  some  hundred  devices  exist  under   both
457              "/sys/devices"  and  "/sys/class"  with  the two sub-hierarchies
458              linking to the other, generating millions of legal paths to enu‐
459              merate.   The structure, reduced to three devices, roughly looks
460              like
463                /sys/class/tty/tty0 --> ../../dev/tty0
464                /sys/class/tty/tty1 --> ../../dev/tty1
465                /sys/class/tty/tty2 --> ../../dev/tty1
467                /sys/dev/tty0/bus
468                /sys/dev/tty0/subsystem --> ../../class/tty
469                /sys/dev/tty1/bus
470                /sys/dev/tty1/subsystem --> ../../class/tty
471                /sys/dev/tty2/bus
472                /sys/dev/tty2/subsystem --> ../../class/tty
475       The command fileutil::find currently has no way to  escape  this.  When
476       having  to  handle  such  a pathological hierarchy It is recommended to
477       switch to package fileutil::traverse and the same-named command it pro‐
478       vides, and then use the -prefilter option to prevent the traverser from
479       following symbolic links, like so:
482                  package require fileutil::traverse
484                  proc NoLinks {fileName} {
485                      if {[string equal [file type $fileName] link]} {
486                          return 0
487                      }
488                      return 1
489                  }
491                  fileutil::traverse T /sys/devices -prefilter NoLinks
492                  T foreach p {
493                      puts $p
494                  }
495                  T destroy


499       This document, and the package it describes, will  undoubtedly  contain
500       bugs  and  other problems.  Please report such in the category fileutil
501       of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].   Please
502       also  report any ideas for enhancements you may have for either package
503       and/or documentation.
505       When proposing code changes, please provide unified diffs, i.e the out‐
506       put of diff -u.
508       Note  further  that  attachments  are  strongly  preferred over inlined
509       patches. Attachments can be made by going  to  the  Edit  form  of  the
510       ticket  immediately  after  its  creation, and then using the left-most
511       button in the secondary navigation bar.


514       cat, file utilities, grep, temp file, test, touch, type


517       Programming tools
521tcllib                               1.16                          fileutil(n)