distrib/share/tcl/help/tcl/files/read

   1 NAME
   2        read - Read from a channel
   3
   4 SYNOPSIS
   5        read ?-nonewline? channelId
   6
   7        read channelId numChars
   8
   9
  10 DESCRIPTION
  11        In  the  first  form, the read command reads all of the data from chan-
  12        nelId up to the end of the file.  If the -nonewline switch is specified
  13        then  the  last  character of the file is discarded if it is a newline.
  14        In the second form, the extra argument specifies how many characters to
  15        read.   Exactly  that many characters will be read and returned, unless
  16        there are fewer than numChars left in the file; in this  case  all  the
  17        remaining characters are returned.  If the channel is configured to use
  18        a multi-byte encoding, then the number of characters read  may  not  be
  19        the same as the number of bytes read.
  20
  21        ChannelId  must  be  an  identifier for an open channel such as the Tcl
  22        standard input channel (stdin), the return value from an invocation  of
  23        open or socket, or the result of a channel creation command provided by
  24        a Tcl extension. The channel must have been opened for input.
  25
  26        If channelId is in nonblocking mode, the command may not read  as  many
  27        characters  as  requested:  once all available input has been read, the
  28        command will return the data that is available rather than blocking for
  29        more input.  If the channel is configured to use a multi-byte encoding,
  30        then there may actually be some bytes remaining in the internal buffers
  31        that  do  not  form  a  complete  character.   These  bytes will not be
  32        returned until a complete character  is  available  or  end-of-file  is
  33        reached.   The  -nonewline  switch  is  ignored  if the command returns
  34        before reaching the end of the file.
  35
  36        Read translates end-of-line sequences in the input into newline charac-
  37        ters  according  to  the  -translation option for the channel.  See the
  38        fconfigure manual entry for a discussion on ways  in  which  fconfigure
  39        will alter input.
  40
  41
  42 USE WITH SERIAL PORTS
  43        For  most  applications  a channel connected to a serial port should be
  44        configured to be nonblocking: fconfigure channelId -blocking  0.   Then
  45        read  behaves much like described above.  Care must be taken when using
  46        read on blocking serial ports:
  47
  48        read channelId numChars
  49               In this form read blocks until numChars have been received  from
  50               the serial port.
  51
  52        read channelId
  53               In  this form read blocks until the reception of the end-of-file
  54               character, see fconfigure  -eofchar.  If  there  no  end-of-file
  55               character  has  been  configured for the channel, then read will
  56               block forever.
  57
  58 EXAMPLE
  59        This example code reads a file all at once, and splits it into a  list,
  60        with each line in the file corresponding to an element in the list:
  61               set fl [open /proc/meminfo]
  62               set data [read $fl]
  63               close $fl
  64               set lines [split $data \n]
  65
  66
  67 SEE ALSO
  68        file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)
  69
  70
  71 KEYWORDS
  72        blocking,  channel, end of line, end of file, nonblocking, read, trans-