1fileutil(n)                     file utilities                     fileutil(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       fileutil - Procedures implementing some file utilities
9

SYNOPSIS

11       package require Tcl  8
12
13       package require fileutil  ?1.16?
14
15       ::fileutil::lexnormalize path
16
17       ::fileutil::fullnormalize path
18
19       ::fileutil::test path codes ?msgvar? ?label?
20
21       ::fileutil::cat (?options? file)...
22
23       ::fileutil::writeFile ?options? file data
24
25       ::fileutil::appendToFile ?options? file data
26
27       ::fileutil::insertIntoFile ?options? file at data
28
29       ::fileutil::removeFromFile ?options? file at n
30
31       ::fileutil::replaceInFile ?options? file at n data
32
33       ::fileutil::updateInPlace ?options? file cmd
34
35       ::fileutil::fileType filename
36
37       ::fileutil::find ?basedir ?filtercmd??
38
39       ::fileutil::findByPattern basedir ?-regexp|-glob? ?--? patterns
40
41       ::fileutil::foreachLine var filename cmd
42
43       ::fileutil::grep pattern ?files?
44
45       ::fileutil::install ?-m mode? source destination
46
47       ::fileutil::stripN path n
48
49       ::fileutil::stripPwd path
50
51       ::fileutil::stripPath prefix path
52
53       ::fileutil::jail jail path
54
55       ::fileutil::touch ?-a? ?-c? ?-m? ?-r ref_file? ?-t time? filename ?...?
56
57       ::fileutil::tempdir
58
59       ::fileutil::tempdir path
60
61       ::fileutil::tempdirReset
62
63       ::fileutil::tempfile ?prefix?
64
65       ::fileutil::maketempdir ?-prefix str? ?-suffix str? ?-dir str?
66
67       ::fileutil::relative base dst
68
69       ::fileutil::relativeUrl base dst
70
71______________________________________________________________________________
72

DESCRIPTION

74       This package provides implementations of standard unix utilities.
75
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.
80
81              Examples:
82
83
84                  fileutil::lexnormalize /foo/./bar
85                  => /foo/bar
86
87                  fileutil::lexnormalize /foo/../bar
88                  => /bar
89
90
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.
96
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.
105
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.
113
114
115              read   file readable
116
117              write  file writable
118
119              exists file exists
120
121              exec   file executable
122
123              file   file isfile
124
125              dir    file isdirectory
126
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.
133
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 be‐
138              fore a file if that file's name begins with a dash.
139
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.
144
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).
151
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
156
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.
163
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.
169
170              The command accepts the same options as ::fileutil::cat.
171
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.
180
181              The command accepts the same options as ::fileutil::cat.
182
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.
191
192              The command accepts the same options as ::fileutil::cat.
193
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.
200
201              If the executed command throws an error the file is not changed.
202
203              The command accepts the same options as ::fileutil::cat.
204
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.
221
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  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
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.
238
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.
242
243              Example:
244
245
246
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]
251
252
253       ::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
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.
274
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.
283
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.
293
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.
300
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  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
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 ".".
317
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.
322
323              If  path  is  an absolute path and already within jail it is re‐
324              turned unmodified.
325
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 es‐
331              cape the jail.
332
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.
340
341              This command is not available for Tcl versions less than 8.3.
342
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:
347
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.
351
352              [2]    The directory named in the TMPDIR environment variable.
353
354              [3]    The directory named in the TEMP environment variable.
355
356              [4]    The directory named in the TMP environment variable.
357
358              [5]    A platform specific location:
359
360                     Windows
361                            "C:\TEMP", "C:\TMP", "\TEMP", and "\TMP" are tried
362                            in that order.
363
364                     (classic) Macintosh
365                            The  TRASH_FOLDER  environment  variable  is used.
366                            This is most likely not correct.
367
368                     Unix   The directories "/tmp", "/var/tmp", and "/usr/tmp"
369                            are tried in that order.
370
371       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
375       ::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
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.
384
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  re‐
390              turned as the result of the command.
391
392              The  code  was  taken from http://wiki.tcl.tk/772, attributed to
393              Igor Volobouev and anon.
394
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.
401
402              The three options can used to tweak the behaviour  of  the  com‐
403              mand:
404
405              -prefix str
406                     The  initial,  fixed part of the directory name. Defaults
407                     to tmp if not specified.
408
409              -suffix str
410                     The fixed tail of the directory. Defaults  to  the  empty
411                     string if not specified.
412
413              -dir str
414                     The  directory  to place the new directory into. Defaults
415                     to the result of fileutil::tempdir if not specified.
416
417       The initial code  for  this  was  supplied  by  Miguel  Martinez  Lopez
418       [mailto:aplicacionamedida@gmail.com].
419
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 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
428              Note: The processing done by this  command  is  purely  lexical.
429              Symbolic links are not taken into account.
430
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.
436
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.
441
442              Note:  The  processing  done  by this command is purely lexical.
443              Symbolic links are not taken into account.
444

WARNINGS AND INCOMPATIBILITIES

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
450              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
455              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
461
462                /sys/class/tty/tty0 --> ../../dev/tty0
463                /sys/class/tty/tty1 --> ../../dev/tty1
464                /sys/class/tty/tty2 --> ../../dev/tty1
465
466                /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
473
474       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
480
481                  package require fileutil::traverse
482
483                  proc NoLinks {fileName} {
484                      if {[string equal [file type $fileName] link]} {
485                          return 0
486                      }
487                      return 1
488                  }
489
490                  fileutil::traverse T /sys/devices -prefilter NoLinks
491                  T foreach p {
492                      puts $p
493                  }
494                  T destroy
495
496

BUGS, IDEAS, FEEDBACK

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
504       When proposing code changes, please provide unified diffs, i.e the out‐
505       put of diff -u.
506
507       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

KEYWORDS

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

CATEGORY

516       Programming tools
517
518
519
520tcllib                               1.16                          fileutil(n)
Impressum