11.1. Commands Presented in This Chapter

This chapter describes the following commands for manipulating files and directories. Most of these commands also work with interprocess pipes and network sockets, covered in Chapter 12. In Tcl terminology, files, pipes, and network sockets are considered channels. All of the I/O-related commands work on any channel.

• cd ?dirName?

  Changes the current working directory to dirName, or to the home directory (as given by the HOME environment variable) if dirName isn’t given. Returns an empty string.

• glob ?option ...? ?--? pattern ?pattern ...?

  Returns a list of the names of all files that match any of the pattern arguments (special characters ?, *, [], {}, and \). The optional -- argument signals the end of options. See the reference documentation for more information on allowed options.

• pwd

  Returns the full path name of the current working directory.

• chan close channelID
  close channelID

  Closes the channel given by channelID. Returns an empty string. The chan close command, introduced in Tcl 8.5, simply incorporates the close functionality into the chan ensemble.

• chan eof channelID
  eof channelID

  Returns 1 if an end-of-file condition has occurred during the most recent read from channelID, 0 otherwise. Starting with Tcl 8.5, eof is deprecated in favor of chan eof.

• file option name ?arg arg ...?

  Performs one of several operations on the file name given by name or on the file to which it refers, depending on option. See this chapter and the reference documentation for more information.

• chan flush channelID
  flush channelID

  Writes out any buffered output that has been generated for channelID. Returns an empty string. Starting with Tcl 8.5, flush is deprecated in favor of chan flush.

• chan gets channelID ?varName?
  gets channelID ?varName?

  Reads the next line from channelID and discards its terminating end-of-line character(s). If varName is specified, it places the line in that variable and returns a count of characters in the line (or -1 for end of file). If varName isn’t specified, it returns the line of characters read (or an empty string for end of file). The chan gets command, introduced in Tcl 8.5, simply incorporates the gets functionality into the chan ensemble.

• open name ?access?

  Opens the file name in the mode given by access. access may be r, r+, w, w+, a, or a+ or a list of flags such as RDONLY; it defaults to r. Returns a file identifier for use in other commands like gets and close. If the first character of name is |, a command pipeline is invoked instead of a file being opened (see Section 12.4 for more information).

• chan puts ?-nonewline? ?channelID? string
  puts ?-nonewline? ?channelID? string

  Writes string to channelID, appending a newline character unless -nonewline is specified. channelID defaults to stdout. Returns an empty string. The chan puts command, introduced in Tcl 8.5, simply incorporates the puts functionality into the chan ensemble.

• chan read ?-nonewline? channelID
  chan read channelID numChars
  read ?-nonewline? channelID
  read channelID numChars

  Reads and returns the next numChars characters from channelID (or up to the end of the file, if fewer than numChars characters are left). If numChars is omitted, it reads and returns the remaining characters of the file; when combined with -nonewline, the final newline, if any, is dropped. The chan read command, introduced in Tcl 8.5, simply incorporates the read functionality into the chan ensemble.

• chan seek channelID offset ?origin?
  seek channelID offset ?origin?

  Positions channelID so that the next access starts at offset bytes from origin. origin may be start, current, or end and defaults to start. Returns an empty string. Starting with Tcl 8.5, seek is deprecated in favor of chan seek.

• chan tell channelID
  tell channelID

  Returns the byte offset from the start of the file of the current access position for channelID. Starting with Tcl 8.5, tell is deprecated in favor of chan tell.

• chan configure channelID ?optionName? ?value?
          ?optionName value ...?
  fconfigure channelID ?optionName? ?value?
          ?optionName value ...?

  Queries or sets the configuration options of the channel channelID. If no optionName or value arguments are supplied, the command returns a dictionary of all configuration options and their values. If optionName is supplied but no value, the command returns the current value of the given option. If one or more pairs of optionName and value are supplied, the command sets each of the named options to the corresponding value; in this case the return value is an empty string. See the text and the reference documentation for a description of the supported options. Starting with Tcl 8.5, fconfigure is deprecated in favor of chan configure.

• chan copy inputChan outputChan ?-size size?
          ?-command callback?
  fcopy inputChan outputChan ?-size size?
          ?-command callback?