Tcl_Tell man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

_________________________________________________________________

NAME
       Tcl_OpenFileChannel,   Tcl_OpenCommandChannel,  Tcl_Close,
       Tcl_Read,  Tcl_Gets,   Tcl_Write,   Tcl_Flush,	Tcl_Seek,
       Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_GetChannelOption,
       Tcl_SetChannelOption - buffered I/O facilities using chan-
       nels

SYNOPSIS
       #include <tcl.h>

       typedef ... Tcl_Channel;

       Tcl_Channel
       Tcl_OpenFileChannel(interp, fileName, mode, permissions)

       Tcl_Channel
       Tcl_OpenCommandChannel(interp, argc, argv, flags)

       Tcl_Channel
       Tcl_MakeFileChannel(inOsFile, outOsFile, readOrWrite)

       Tcl_Channel
       Tcl_GetChannel(interp, channelName, modePtr)

       void
       Tcl_RegisterChannel(interp, channel)

       int
       Tcl_UnregisterChannel(interp, channel)

       int
       Tcl_Close(interp, channel)

       int
       Tcl_Read(channel, buf, toRead)

       int
       Tcl_Gets(channel, lineRead)

       int
       Tcl_Write(channel, buf, toWrite)

       int
       Tcl_Flush(channel)

       int
       Tcl_Seek(channel, offset, seekMode)

       int
       Tcl_Tell(channel)

       int

Tcl			       7.5				1

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

       Tcl_GetChannelOption(channel, optionName, optionValue)

       int
       Tcl_SetChannelOption(interp, channel, optionName, newValue)

       int
       Tcl_Eof(channel)

       int
       Tcl_InputBlocked(channel)

       int
       Tcl_InputBuffered(channel)

ARGUMENTS
       Tcl_Interp	 *interp	    (in)      Used    for
						      error
						      reporting
						      and to look
						      up  a chan-
						      nel  regis-
						      tered    in
						      it.

       char		 *fileName	    (in)      The name of
						      a	 local or
						      network
						      file.

       char		 *mode		    (in)      Specifies
						      how     the
						      file  is to
						      be
						      accessed.
						      May    have
						      any  of the
						      values
						      allowed for
						      the    mode
						      argument to
						      the     Tcl
						      open   com-
						      mand.   For
						      Tcl_Open-
						      Command-
						      Channel,
						      may      be
						      NULL.

       int		 permissions	    (in)      POSIX-style
						      permission
						      flags  such
						      as    0644.

Tcl			       7.5				2

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

						      If   a  new
						      file     is
						      created,
						      these  per-
						      missions
						      will be set
						      on the cre-
						      ated  file.

       int		 argc		    (in)      The  number
						      of elements
						      in argv.

       char		 **argv		    (in)      Arguments
						      for    con-
						      structing a
						      command
						      pipeline.
						      These  val-
						      ues    have
						      the    same
						      meaning  as
						      the    non-
						      switch
						      arguments
						      to  the Tcl
						      exec   com-
						      mand.

       int		 flags		    (in)      Specifies
						      the  dispo-
						      sition   of
						      the   stdio
						      handles  in
						      pipeline:
						      OR-ed  com-
						      bination of
						      TCL_STDIN,
						      TCL_STDOUT,
						      TCL_STDERR,
						      and
						      TCL_ENFORCE_MODE.
						      If
						      TCL_STDIN
						      is     set,
						      stdin   for
						      the   first
						      child    in
						      the pipe is
						      the    pipe
						      channel,
						      otherwise
						      it  is  the
						      same as the

Tcl			       7.5				3

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

						      standard
						      input    of
						      the  invok-
						      ing    pro-
						      cess; like-
						      wise    for
						      TCL_STDOUT
						      and
						      TCL_STDERR.
						      If
						      TCL_ENFORCE_MODE
						      is not set,
						      then    the
						      pipe    can
						      redirect
						      stdio  han-
						      dles     to
						      override
						      the   stdio
						      handles for
						      which
						      TCL_STDIN,
						      TCL_STDOUT
						      and
						      TCL_STDERR
						      have   been
						      set.  If it
						      is     set,
						      then   such
						      redirec-
						      tions cause
						      an error.

       ClientData	 inOsFile	    (in)      Operating
						      system spe-
						      cific  han-
						      dle     for
						      input  from
						      a file. For
						      Unix   this
						      is  a  file
						      descriptor,
						      for Windows
						      it   is	a
						      HANDLE,
						      etc.

       ClientData	 outOsFile	    (in)      Operating
						      system spe-
						      cific  han-
						      dle     for
						      output to a
						      file.

Tcl			       7.5				4

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

       int		 readOrWrite	    (in)      OR-ed  com-
						      bination of
						      TCL_READ-
						      ABLE    and
						      TCL_WRITABLE
						      to indicate
						      which    of
						      inOsFile
						      and  outOs-
						      File   con-
						      tains	a
						      valid
						      value.

       int		 *modePtr	    (out)     Points   at
						      an  integer
						      variable
						      that   will
						      receive  an
						      OR-ed  com-
						      bination of
						      TCL_READ-
						      ABLE    and
						      TCL_WRITABLE
						      denoting
						      whether the
						      channel  is
						      open    for
						      reading and
						      writing.

       Tcl_Channel	 channel	    (in)      A Tcl chan-
						      nel     for
						      input    or
						      output.
						      Must   have
						      been    the
						      return
						      value  from
						      a procedure
						      such     as
						      Tcl_Open-
						      FileChan-
						      nel.

       char		 *buf		    (in)      An array of
						      bytes    in
						      which    to
						      store chan-
						      nel  input,
						      or     from
						      which    to
						      read  chan-
						      nel output.

Tcl			       7.5				5

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

       int		 len		    (in)      The  length
						      of      the
						      input    or
						      output.

       int		 atEnd		    (in)      If nonzero,
						      store   the
						      input    at
						      the end  of
						      the   input
						      queue, oth-
						      erwise
						      store it at
						      the head of
						      the   input
						      queue.

       int		 toRead		    (in)      The  number
						      of bytes to
						      read   from
						      the   chan-
						      nel.

       Tcl_DString	 *lineRead	    (in)      A	  pointer
						      to  a   Tcl
						      dynamic
						      string   in
						      which    to
						      store   the
						      line   read
						      from    the
						      channel.
						      Must   have
						      been   ini-
						      tialized by
						      the caller.

       int		 toWrite	    (in)      The  number
						      of bytes to
						      read   from
						      buf     and
						      output   to
						      the   chan-
						      nel.

       int		 offset		    (in)      How far  to
						      move    the
						      access
						      point    in
						      the channel
						      at    which
						      the    next
						      input    or
						      output

Tcl			       7.5				6

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

						      operation
						      will     be
						      applied,
						      measured in
						      bytes  from
						      the   posi-
						      tion  given
						      by    seek-
						      Mode.   May
						      be   either
						      positive or
						      negative.

       int		 seekMode	    (in)      Relative to
						      which point
						      to    seek;
						      used   with
						      offset   to
						      calculate
						      the     new
						      access
						      point   for
						      the   chan-
						      nel.  Legal
						      values  are
						      SEEK_SET,
						      SEEK_CUR,
						      and
						      SEEK_END.

       char		 *optionName	    (in)      The name of
						      an   option
						      applicable
						      to     this
						      channel,
						      such     as
						      -blocking.
						      May    have
						      any  of the
						      values
						      accepted by
						      the   fcon-
						      figure com-
						      mand.

       Tcl_DString	 *optionValue	    (in)      Where    to
						      store   the
						      value of an
						      option or a
						      list of all
						      options and
						      their  val-
						      ues.   Must
						      have   been

Tcl			       7.5				7

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

						      initialized
						      by      the
						      caller.

       char		 *newValue	    (in)      New   value
						      for     the
						      option
						      given    by
						      optionName.
_________________________________________________________________

DESCRIPTION
       The Tcl channel mechanism  provides  a  device-independent
       and platform-independent mechanism for performing buffered
       input and output operations on a variety of file,  socket,
       and  device types.  The channel mechanism is extensible to
       new channel types, by providing a low level channel driver
       for   the  new  type;  the  channel  driver  interface  is
       described in the manual entry for  Tcl_CreateChannel.  The
       channel	mechanism  provides  a	buffering scheme modelled
       after Unix's standard I/O, and it  also	allows	for  non-
       blocking I/O on channels.

       The procedures described in this manual entry comprise the
       C APIs of the generic layer of the  channel  architecture.
       For  a  description of the channel driver architecture and
       how to implement channel drivers for new	 types	of  chan-
       nels, see the manual entry for Tcl_CreateChannel.

TCL_OPENFILECHANNEL
       Tcl_OpenFileChannel opens a file specified by fileName and
       returns a channel handle that can be used to perform input
       and  output  on	the  file. This API is modelled after the
       fopen procedure of the Unix  standard  I/O  library.   The
       syntax  and  meaning  of all arguments is similar to those
       given in the Tcl open command when opening a file.  If  an
       error  occurs while opening the channel, Tcl_OpenFileChan-
       nel returns NULL and records a POSIX error code	that  can
       be retrieved with Tcl_GetErrno.	In addition, if interp is
       non-NULL, Tcl_OpenFileChannel leaves an error  message  in
       interp->result after any error.

       The  newly  created  channel is not registered in the sup-
       plied interpreter; to register it,  use	Tcl_RegisterChan-
       nel,  described	below.	 If one of the standard channels,
       stdin, stdout or stderr was previously closed, the act  of
       creating	 the new channel also assigns it as a replacement
       for the standard channel.

TCL_OPENCOMMANDCHANNEL
       Tcl_OpenCommandChannel provides a C-level interface to the

Tcl			       7.5				8

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

       functions  of  the  exec	 and open commands.  It creates a
       sequence of subprocesses specified by the  argv	and  argc
       arguments and returns a channel that can be used to commu-
       nicate with these subprocesses.	The flags argument  indi-
       cates  what sort of communication will exist with the com-
       mand pipeline.

       If the TCL_STDIN flag is set then the standard  input  for
       the  first subprocess will be tied to the channel: writing
       to the channel will provide input to the	 subprocess.   If
       TCL_STDIN  is  not  set, then standard input for the first
       subprocess will be the same as this application's standard
       input.  If TCL_STDOUT is set then standard output from the
       last subprocess can be read from the channel; otherwise it
       goes to this application's standard output.  If TCL_STDERR
       is set, standard error  output  for  all	 subprocesses  is
       returned	 to  the channel and results in an error when the
       channel is closed; otherwise it goes to this application's
       standard error.	If TCL_ENFORCE_MODE is not set, then argc
       and argv	 can  redirect	the  stdio  handles  to	 override
       TCL_STDIN,  TCL_STDOUT, and TCL_STDERR; if it is set, then
       it is an error for argc and argv to override  stdio  chan-
       nels  for which TCL_STDIN, TCL_STDOUT, and TCL_STDERR have
       been set.

       If an error occurs while opening the channel, Tcl_OpenCom-
       mandChannel  returns  NULL  and records a POSIX error code
       that can be retrieved  with  Tcl_GetErrno.   In	addition,
       Tcl_OpenCommandChannel	leaves	 an   error   message  in
       interp->result if interp is not NULL.

       The newly created channel is not registered  in	the  sup-
       plied  interpreter;  to register it, use Tcl_RegisterChan-
       nel, described below.  If one of	 the  standard	channels,
       stdin,  stdout or stderr was previously closed, the act of
       creating the new channel also assigns it as a  replacement
       for the standard channel.

TCL_MAKEFILECHANNEL
       Tcl_MakeFileChannel  makes a Tcl_Channel from an existing,
       platform-specific, file handle.	The newly created channel
       is not registered in the supplied interpreter; to register
       it, use Tcl_RegisterChannel, described below.  If  one  of
       the  standard channels, stdin, stdout or stderr was previ-
       ously closed, the act of creating  the  new  channel  also
       assigns it as a replacement for the standard channel.

TCL_GETCHANNEL
       Tcl_GetChannel  returns	a  channel  given the channelName
       used to create it with Tcl_CreateChannel and a pointer  to
       a  Tcl interpreter in interp. If a channel by that name is
       not registered in that interpreter, the procedure  returns

Tcl			       7.5				9

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

       NULL.  If  the  mode argument is not NULL, it points at an
       integer variable that will receive an OR-ed combination of
       TCL_READABLE and TCL_WRITABLE describing whether the chan-
       nel is open for reading and writing.

TCL_REGISTERCHANNEL
       Tcl_RegisterChannel adds a channel to the set of	 channels
       accessible  in  interp. After this call, Tcl programs exe-
       cuting in that interpreter can refer  to	 the  channel  in
       input  or  output  operations  using the name given in the
       call to Tcl_CreateChannel.  After this call,  the  channel
       becomes	the  property  of the interpreter, and the caller
       should not call Tcl_Close for  the  channel;  the  channel
       will  be closed automatically when it is unregistered from
       the interpreter.

       Code executing outside of any  Tcl  interpreter	can  call
       Tcl_RegisterChannel  with interp as NULL, to indicate that
       it wishes to hold a  reference  to  this	 channel.  Subse-
       quently,	 the  channel  can  be registered in a Tcl inter-
       preter and it will only be closed when the matching number
       of  calls  to  Tcl_UnregisterChannel have been made.  This
       allows code executing outside of any interpreter to safely
       hold a reference to a channel that is also registered in a
       Tcl interpreter.

TCL_UNREGISTERCHANNEL
       Tcl_UnregisterChannel removes a channel from  the  set  of
       channels	 accessible  in interp. After this call, Tcl pro-
       grams will no longer be able to use the channel's name  to
       refer  to the channel in that interpreter.  If this opera-
       tion removed the last registration of the channel  in  any
       interpreter, the channel is also closed and destroyed.

       Code  not  associated  with  a  Tcl  interpreter	 can call
       Tcl_UnregisterChannel with interp as NULL, to indicate  to
       Tcl  that  it no longer holds a reference to that channel.
       If this is the last reference to the channel, it will  now
       be closed.

TCL_CLOSE
       Tcl_Close  destroys the channel channel, which must denote
       a currently open channel. The channel should not be regis-
       tered   in  any	interpreter  when  Tcl_Close  is  called.
       Buffered output is flushed to the channel's output  device
       prior to destroying the channel, and any buffered input is
       discarded.  If this is a blocking channel, the  call  does
       not return until all buffered data is successfully sent to
       the channel's output device.  If	 this  is  a  nonblocking
       channel	and there is buffered output that cannot be writ-
       ten without blocking, the call returns immediately; output

Tcl			       7.5			       10

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

       is  flushed  in	the  background	 and  the channel will be
       closed once all of the buffered data has been output.   In
       this case errors during flushing are not reported.

       If  the channel was closed successfully, Tcl_Close returns
       TCL_OK.	If an error occurs, Tcl_Close  returns	TCL_ERROR
       and  records a POSIX error code that can be retrieved with
       Tcl_GetErrno.   If  the	channel	 is  being  closed   syn-
       chronously and an error occurs during closing of the chan-
       nel and interp is not NULL, an error message  is	 left  in
       interp->result.

       Note:  it  is not safe to call Tcl_Close on a channel that
       has been registered  using  Tcl_RegisterChannel;	 see  the
       documentation for Tcl_RegisterChannel, above, for details.
       If the channel has ever been given as the chan argument in
       a  call	to  Tcl_RegisterChannel,  you  should instead use
       Tcl_UnregisterChannel,	which	will   internally    call
       Tcl_Close  when all calls to Tcl_RegisterChannel have been
       matched by corresponding calls to Tcl_UnregisterChannel.

TCL_READ
       Tcl_Read consumes up to toRead bytes of data from  channel
       and stores it at buf.  The return value of Tcl_Read is the
       number of characters written at buf.  The buffer	 produced
       by Tcl_Read is not NULL terminated. Its contents are valid
       from the zeroth position up to and excluding the	 position
       indicated  by  the  return value.  If an error occurs, the
       return value is -1 and Tcl_Read records a POSIX error code
       that can be retrieved with Tcl_GetErrno.

       The  return value may be smaller than the value of toRead,
       indicating that less data than  requested  was  available,
       also called a short read.  In blocking mode, this can only
       happen on an end-of-file.  In nonblocking  mode,	 a  short
       read can also occur if there is not enough input currently
       available:  Tcl_Read returns a  short  count  rather  than
       waiting for more data.

       If the channel is in blocking mode, a return value of zero
       indicates an end of file condition. If the channel  is  in
       nonblocking  mode, a return value of zero indicates either
       that no input is currently available or	an  end	 of  file
       condition.  Use Tcl_Eof and Tcl_InputBlocked to tell which
       of these conditions actually occurred.

       Tcl_Read translates platform-specific  end-of-line  repre-
       sentations  into	 the canonical \n internal representation
       according to the	 current  end-of-line  recognition  mode.
       End-of-line  recognition and the various platform-specific
       modes are described in the manual entry for the Tcl  fcon-
       figure command.

Tcl			       7.5			       11

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

TCL_GETS
       Tcl_Gets	 reads a line of input from a channel and appends
       all of the characters of the line except for the terminat-
       ing  end-of-line	 character(s) to the dynamic string given
       by dsPtr.  The end-of-line character(s) are read and  dis-
       carded.

       If  a  line  was	 successfully  read,  the return value is
       greater than or equal to zero, and it indicates the number
       of  characters  stored in the dynamic string.  If an error
       occurs, Tcl_Gets returns -1 and records a POSIX error code
       that  can  be  retrieved with Tcl_GetErrno.  Tcl_Gets also
       returns -1 if the end of the file is reached; the  Tcl_Eof
       procedure can be used to distinguish an error from an end-
       of-file condition.

       If the channel is in nonblocking mode,  the  return  value
       can  also  be -1 if no data was available or the data that
       was available did not contain  an  end-of-line  character.
       When -1 is returned, the Tcl_InputBlocked procedure may be
       invoked to determine if the channel is blocked because  of
       input unavailability.

TCL_WRITE
       Tcl_Write  accepts toWrite bytes of data at buf for output
       on channel. This data may not appear on the output  device
       immediately.  If	 the data should appear immediately, call
       Tcl_Flush after the call to Tcl_Write, or set the -buffer-
       ing option on the channel to none. If you wish the data to
       appear as soon as an end of line is accepted  for  output,
       set the -buffering option on the channel to line mode.

       The  toWrite argument specifies how many bytes of data are
       provided in the buf argument. If it is negative, Tcl_Write
       expects	the  data  to  be  NULL terminated and it outputs
       everything up to the NULL.

       The return value of Tcl_Write is a count of how many char-
       acters  were  accepted  for output to the channel. This is
       either equal to toWrite or -1 to indicate  that	an  error
       occurred.   If  an  error occurs, Tcl_Write also records a
       POSIX error code that may be retrieved with  Tcl_GetErrno.

       Newline	characters  in	the output data are translated to
       platform-specific end-of-line sequences according  to  the
       -translation option for the channel.

TCL_FLUSH
       Tcl_Flush causes all of the buffered output data for chan-
       nel to be written to its underlying file or device as soon
       as possible.  If the channel is in blocking mode, the call
       does not return until all the buffered data has been  sent

Tcl			       7.5			       12

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

       to  the	channel or some error occurred.	 The call returns
       immediately if the channel is  nonblocking;  it	starts	a
       background  flush that will write the buffered data to the
       channel eventually, as fast as  the  channel  is	 able  to
       absorb it.

       The  return value is normally TCL_OK.  If an error occurs,
       Tcl_Flush returns TCL_ERROR and records a POSIX error code
       that can be retrieved with Tcl_GetErrno.

TCL_SEEK
       Tcl_Seek	 moves	the  access point in channel where subse-
       quent data will be read or  written.  Buffered  output  is
       flushed	to  the	 channel and buffered input is discarded,
       prior to the seek operation.

       Tcl_Seek normally returns the new  access  point.   If  an
       error  occurs,  Tcl_Seek	 returns  -1  and records a POSIX
       error code that can be retrieved with Tcl_GetErrno.  After
       an error, the access point may or may not have been moved.

TCL_TELL
       Tcl_Tell returns the current access point for  a	 channel.
       The  returned  value is -1 if the channel does not support
       seeking.

TCL_GETCHANNELOPTION
       Tcl_GetChannelOption retrieves, in dsPtr, the value of one
       of  the	options	 currently  in effect for a channel, or a
       list of all options and their values.  The  channel  argu-
       ment  identifies	 the channel for which to query an option
       or retrieve all options and their values.   If  optionName
       is  not	NULL,  it is the name of the option to query; the
       option's value is copied to the Tcl dynamic string denoted
       by optionValue. If optionName is NULL, the function stores
       an alternating list of option names and	their  values  in
       optionValue,  using a series of calls to Tcl_DStringAppen-
       dElement. The various preexisting options and their possi-
       ble  values  are described in the manual entry for the Tcl
       fconfigure command. Other options can  be  added	 by  each
       channel	type.	These  channel	type specific options are
       described in the manual entry for  the  Tcl  command  that
       creates	a  channel  of	that type; for example, the addi-
       tional options for TCP based channels are described in the
       manual  entry  for  the Tcl socket command.  The procedure
       normally returns TCL_OK. If an error  occurs,  it  returns
       TCL_ERROR  and  calls Tcl_SetErrno to store an appropriate
       POSIX error code.

Tcl			       7.5			       13

Tcl_OpenFileChannel(3)Tcl Library ProcedureTcl_OpenFileChannel(3)

TCL_SETCHANNELOPTION
       Tcl_SetChannelOption sets a new value  for  an  option  on
       channel.	  OptionName is the option to set and newValue is
       the value to set.  The procedure normally returns  TCL_OK.
       If an error occurs, it returns TCL_ERROR;  in addition, if
       interp is non-NULL, Tcl_SetChannelOption leaves	an  error
       message in interp->result.

TCL_EOF
       Tcl_Eof	returns a nonzero value if channel encountered an
       end of file during the last input operation.

TCL_INPUTBLOCKED
       Tcl_InputBlocked returns a nonzero value if channel is  in
       nonblocking  mode  and  the  last input operation returned
       less data than requested because	 there	was  insufficient
       data available.	The call always returns zero if the chan-
       nel is in blocking mode.

TCL_INPUTBUFFERED
       Tcl_InputBuffered returns the number  of	 bytes	of  input
       currently  buffered in the internal buffers for a channel.
       If the channel is not  open  for	 reading,  this	 function
       always returns zero.

SEE ALSO
       DString(3), fconfigure(n), filename(n), fopen(2), Tcl_Cre-
       ateChannel(3)

KEYWORDS
       access point, blocking,	buffered  I/O,	channel,  channel
       driver,	end  of	 file, flush, input, nonblocking, output,
       read, seek, write

Tcl			       7.5			       14

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net