Tcl_IsStandardChannel man page on Peanut

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

Tcl_OpenFileChannel(3)	    Tcl Library Procedures	Tcl_OpenFileChannel(3)

______________________________________________________________________________

NAME
       Tcl_OpenFileChannel,    Tcl_OpenCommandChannel,	  Tcl_MakeFileChannel,
       Tcl_GetChannel, Tcl_GetChannelNames, Tcl_GetChannelNamesEx,  Tcl_Regis‐
       terChannel,  Tcl_UnregisterChannel,  Tcl_DetachChannel, Tcl_IsStandard‐
       Channel, Tcl_Close,  Tcl_ReadChars,  Tcl_Read,  Tcl_GetsObj,  Tcl_Gets,
       Tcl_WriteObj, Tcl_WriteChars, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell,
       Tcl_TruncateChannel,    Tcl_GetChannelOption,	 Tcl_SetChannelOption,
       Tcl_Eof,	  Tcl_InputBlocked,   Tcl_InputBuffered,   Tcl_OutputBuffered,
       Tcl_Ungets, Tcl_ReadRaw, Tcl_WriteRaw - buffered I/O  facilities	 using
       channels

SYNOPSIS
       #include <tcl.h>

       Tcl_Channel
       Tcl_OpenFileChannel(interp, fileName, mode, permissions)

       Tcl_Channel
       Tcl_OpenCommandChannel(interp, argc, argv, flags)

       Tcl_Channel
       Tcl_MakeFileChannel(handle, readOrWrite)

       Tcl_Channel
       Tcl_GetChannel(interp, channelName, modePtr)

       int
       Tcl_GetChannelNames(interp)

       int
       Tcl_GetChannelNamesEx(interp, pattern)

       void
       Tcl_RegisterChannel(interp, channel)

       int
       Tcl_UnregisterChannel(interp, channel)

       int
       Tcl_DetachChannel(interp, channel)

       int
       Tcl_IsStandardChannel(channel)

       int
       Tcl_Close(interp, channel)

       int
       Tcl_ReadChars(channel, readObjPtr, charsToRead, appendFlag)

       int
       Tcl_Read(channel, readBuf, bytesToRead)

       int
       Tcl_GetsObj(channel, lineObjPtr)

       int
       Tcl_Gets(channel, lineRead)

       int
       Tcl_Ungets(channel, input, inputLen, addAtEnd)

       int
       Tcl_WriteObj(channel, writeObjPtr)

       int
       Tcl_WriteChars(channel, charBuf, bytesToWrite)

       int
       Tcl_Write(channel, byteBuf, bytesToWrite)

       int
       Tcl_ReadRaw(channel, readBuf, bytesToRead)

       int
       Tcl_WriteRaw(channel, byteBuf, bytesToWrite)

       int
       Tcl_Eof(channel)

       int
       Tcl_Flush(channel)

       int
       Tcl_InputBlocked(channel)

       int
       Tcl_InputBuffered(channel)

       int
       Tcl_OutputBuffered(channel)

       Tcl_WideInt
       Tcl_Seek(channel, offset, seekMode)

       Tcl_WideInt
       Tcl_Tell(channel)

       int								       │
       Tcl_TruncateChannel(channel, length)				       │

       int
       Tcl_GetChannelOption(interp, channel, optionName, optionValue)

       int
       Tcl_SetChannelOption(interp, channel, optionName, newValue)

ARGUMENTS
       Tcl_Interp *interp (in)		      Used  for error reporting and to
					      look up a channel registered  in
					      it.

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

       const 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.

       int permissions (in)		      POSIX-style   permission	 flags
					      such  as 0644.  If a new file is
					      created, these permissions  will
					      be set on the created file.

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

       const char **argv (in)		      Arguments	  for  constructing  a
					      command pipeline.	 These	values
					      have  the	 same  meaning	as the
					      non-switch arguments to the  Tcl
					      exec command.

       int flags (in)			      Specifies the disposition of the
					      stdio handles in pipeline: OR-ed
					      combination     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  standard input of
					      the invoking  process;  likewise
					      for  TCL_STDOUT  and TCL_STDERR.
					      If TCL_ENFORCE_MODE is not  set,
					      then the pipe can redirect stdio
					      handles to  override  the	 stdio
					      handles	for  which  TCL_STDIN,
					      TCL_STDOUT and  TCL_STDERR  have
					      been  set.   If  it is set, then
					      such   redirections   cause   an
					      error.

       ClientData handle (in)		      Operating system specific handle
					      for I/O to a file. For Unix this
					      is  a  file descriptor, for Win‐
					      dows it is a HANDLE.

       int readOrWrite (in)		      OR-ed combination	 of  TCL_READ‐
					      ABLE  and	 TCL_WRITABLE to indi‐
					      cate what operations  are	 valid
					      on handle.

       const char *channelName (in)	      The name of the channel.

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

       const char *pattern (in)		      The pattern to match on,	passed
					      to Tcl_StringMatch, or NULL.

       Tcl_Channel channel (in)		      A	 Tcl channel for input or out‐
					      put.  Must have been the	return
					      value  from  a procedure such as
					      Tcl_OpenFileChannel.

       Tcl_Obj *readObjPtr (in/out)	      A pointer to  a  Tcl  Object  in
					      which  to	 store	the characters
					      read from the channel.

       int charsToRead (in)		      The number of characters to read
					      from  the channel.  If the chan‐
					      nel's encoding is	 binary,  this
					      is  equivalent  to the number of
					      bytes to read from the channel.

       int appendFlag (in)		      If non-zero, data read from  the
					      channel  will be appended to the
					      object.	Otherwise,  the	  data
					      will  replace  the existing con‐
					      tents of the object.

       char *readBuf (out)		      A buffer in which to  store  the
					      bytes read from the channel.

       int bytesToRead (in)		      The number of bytes to read from
					      the channel.  The buffer readBuf
					      must  be	large  enough  to hold
					      this many bytes.

       Tcl_Obj *lineObjPtr (in/out)	      A pointer to  a  Tcl  object  in
					      which  to	 store	the  line read
					      from the channel.	 The line read
					      will  be appended to the current
					      value of the object.

       Tcl_DString *lineRead (in/out)	      A	 pointer  to  a	 Tcl   dynamic
					      string  in  which	 to  store the
					      line  read  from	the   channel.
					      Must  have  been	initialized by
					      the caller.  The line read  will
					      be  appended to any data already
					      in the dynamic string.

       const char *input (in)		      The input to add	to  a  channel
					      buffer.

       int inputLen (in)		      Length of the input

       int addAtEnd (in)		      Flag   indicating	  whether  the
					      input should be added to the end
					      or beginning of the channel buf‐
					      fer.

       Tcl_Obj *writeObjPtr (in)	      A pointer to a Tcl Object	 whose
					      contents	will  be output to the
					      channel.

       const char *charBuf (in)		      A buffer containing the  charac‐
					      ters to output to the channel.

       const char *byteBuf (in)		      A buffer containing the bytes to
					      output to the channel.

       int bytesToWrite (in)		      The number of bytes  to  consume
					      from charBuf or byteBuf and out‐
					      put to the channel.

       Tcl_WideInt offset (in)		      How far to move the access point
					      in the channel at which the next
					      input or output  operation  will
					      be  applied,  measured  in bytes
					      from the position 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
					      channel.	  Legal	  values   are
					      SEEK_SET,	    SEEK_CUR,	   and
					      SEEK_END.

       Tcl_WideInt length (in)		      The   (non-negative)  length  to
					      truncate the channel the channel
					      to.

       const char *optionName (in)	      The name of an option applicable
					      to this channel, such as -block‐
					      ing.  May have any of the values
					      accepted by the fconfigure  com‐
					      mand.

       Tcl_DString *optionValue (in)	      Where  to	 store the value of an
					      option or a list of all  options
					      and their values. Must have been
					      initialized by the caller.

       const 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	opera‐
       tions  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 mecha‐
       nism provides a buffering scheme modeled after Unix's standard I/O, and
       it also allows for nonblocking 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 channels, 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 modeled after the fopen procedure of the Unix stan‐
       dard 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_OpenFileChannel  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's result after any error.  As of Tcl
       8.4, the object-based API Tcl_FSOpenFileChannel should be used in pref‐
       erence to Tcl_OpenFileChannel wherever possible.

       The  newly  created  channel  is	 not registered in the supplied inter‐
       preter; to register it, use Tcl_RegisterChannel, 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 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 communicate with these  subprocesses.	  The  flags  argument
       indicates  what sort of communication will exist with the command pipe‐
       line.

       If the TCL_STDIN flag is set then the standard input for the first sub‐
       process	will  be tied to the channel: writing to the channel will pro‐
       vide 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 applica‐
       tion'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 channels for which TCL_STDIN, TCL_STDOUT, and TCL_STDERR
       have been set.

       If  an  error  occurs while opening the channel, Tcl_OpenCommandChannel
       returns NULL and records a POSIX error code that can be retrieved  with
       Tcl_GetErrno.  In addition, Tcl_OpenCommandChannel leaves an error mes‐
       sage in the interpreter's result if interp is not NULL.

       The newly created channel is not	 registered  in	 the  supplied	inter‐
       preter;	to  register it, use Tcl_RegisterChannel, 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-spe‐
       cific, 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 previously 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 NULL. If the modePtr 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  channel  is  open
       for reading and writing.

       Tcl_GetChannelNames  and	 Tcl_GetChannelNamesEx	write the names of the
       registered channels to the  interpreter's  result  as  a	 list  object.
       Tcl_GetChannelNamesEx will filter these names according to the pattern.
       If pattern is NULL, then it will not  do	 any  filtering.   The	return
       value  is TCL_OK if no errors occurred writing to the result, otherwise
       it is TCL_ERROR, and the error message is  left	in  the	 interpreter's
       result.

TCL_REGISTERCHANNEL
       Tcl_RegisterChannel adds a channel to the set of channels accessible in
       interp. After this call, Tcl programs executing 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_Register‐
       Channel with interp as NULL, to indicate that it wishes to hold a  ref‐
       erence  to this channel. Subsequently, the channel can be registered in
       a Tcl interpreter 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.

       This  procedure interacts with the code managing the standard channels.
       If no standard channels were  initialized  before  the  first  call  to
       Tcl_RegisterChannel,  they  will	 get  initialized  by  that  call. See
       Tcl_StandardChannels for a general treatise about standard channels and
       the behaviour of the Tcl library with regard to them.

TCL_UNREGISTERCHANNEL
       Tcl_UnregisterChannel removes a channel from the set of channels acces‐
       sible in interp. After this call, Tcl programs will no longer  be  able
       to  use the channel's name to refer to the channel in that interpreter.
       If this operation 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_UnregisterChan‐
       nel 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 chan‐
       nel, it will now be closed.  Tcl_UnregisterChannel is very  similar  to
       Tcl_DetachChannel except that it will also close the channel if no fur‐
       ther references to it exist.

TCL_DETACHCHANNEL
       Tcl_DetachChannel removes a channel from the set of channels accessible
       in  interp. After this call, Tcl programs will no longer be able to use
       the channel's name to refer to the channel in that interpreter.	Beyond
       that,  this  command  has  no further effect.  It cannot be used on the
       standard channels (stdout, stderr, stdin), and will return TCL_ERROR if
       passed one of those channels.

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

TCL_ISSTANDARDCHANNEL
       Tcl_IsStandardChannel tests whether a channel is one of the three stan‐
       dard channels, stdin, stdout or stderr.	If so, it returns 1, otherwise
       0.

       No attempt is made to check whether the given channel or	 the  standard
       channels are initialized or otherwise valid.

TCL_CLOSE
       Tcl_Close  destroys  the channel channel, which must denote a currently
       open channel. The channel should not be registered 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 written without blocking, the call returns  immediately;
       output 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 synchronously and an error occurs during closing of the  channel
       and  interp  is not NULL, an error message is left in the interpreter's
       result.

       Note: it is not safe to call Tcl_Close on a channel that has been  reg‐
       istered using Tcl_RegisterChannel; see the documentation for Tcl_Regis‐
       terChannel, 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_READCHARS AND TCL_READ
       Tcl_ReadChars consumes bytes from  channel,  converting	the  bytes  to
       UTF-8  based on the channel's encoding and storing the produced data in
       readObjPtr's string representation.  The return value of	 Tcl_ReadChars
       is  the	number	of  characters, up to charsToRead, that were stored in
       readObjPtr.  If an error occurs while reading, the return value	is  -1
       and Tcl_ReadChars records a POSIX error code that can be retrieved with
       Tcl_GetErrno.

       Setting charsToRead to -1 will cause the command to read all characters
       currently  available  (non-blocking)  or everything until eof (blocking
       mode).

       The return value may be smaller than the value to read, indicating that
       less  data  than requested was available.  This is called a short read.
       In blocking mode, this can only happen on an end-of-file.  In nonblock‐
       ing mode, a short read can also occur if there is not enough input cur‐
       rently available:  Tcl_ReadChars 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_ReadChars  translates  the various end-of-line representations 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
       fconfigure command.

       As  a  performance  optimization,  when reading from a channel with the
       encoding binary, the bytes are not converted to UTF-8 as they are read.
       Instead,	 they  are stored in readObjPtr's internal representation as a
       byte-array object.  The string representation of this object will  only
       be  constructed	if  it	is needed (e.g., because of a call to Tcl_Get‐
       StringFromObj).	In this way, byte-oriented data can  be	 read  from  a
       channel,	 manipulated  by  calling  Tcl_GetByteArrayFromObj and related
       functions, and then written to a channel without the  expense  of  ever
       converting to or from UTF-8.

       Tcl_Read is similar to Tcl_ReadChars, except that it does not do encod‐
       ing conversions, regardless of the channel's encoding.	It  is	depre‐
       cated and exists for backwards compatibility with non-internationalized
       Tcl extensions.	It consumes bytes from	channel	 and  stores  them  in
       readBuf,	 performing  end-of-line  translations on the way.  The return
       value of Tcl_Read is the number of bytes, up to bytesToRead, written in
       readBuf.	  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.

       Tcl_ReadRaw  is the same as Tcl_Read but does not compensate for stack‐
       ing. While Tcl_Read (and the other functions in	the  API)  always  get
       their  data  from the topmost channel in the stack the supplied channel
       is part of, Tcl_ReadRaw does not. Thus this function is only usable for
       transformational	 channel drivers, i.e. drivers used in the middle of a
       stack of channels, to move data from the channel below into the	trans‐
       formation.

TCL_GETSOBJ AND TCL_GETS
       Tcl_GetsObj  consumes bytes from channel, converting the bytes to UTF-8
       based on the channel's encoding, until a full line of  input  has  been
       seen.   If  the	channel's  encoding is binary, each byte read from the
       channel is treated as an individual  Unicode  character.	  All  of  the
       characters  of  the line except for the terminating end-of-line charac‐
       ter(s) are appended to lineObjPtr's string representation.  The end-of-
       line character(s) are read and discarded.

       If  a  line  was successfully read, the return value is greater than or
       equal to zero and indicates the number of bytes stored  in  lineObjPtr.
       If  an  error  occurs, Tcl_GetsObj returns -1 and records a POSIX error
       code that can be retrieved with Tcl_GetErrno.  Tcl_GetsObj 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_Gets is the same as Tcl_GetsObj except the resulting characters are
       appended	 to  the  dynamic  string  given by lineRead rather than a Tcl
       object.

TCL_UNGETS
       Tcl_Ungets is used to add data to the input  queue  of  a  channel,  at
       either  the head or tail of the queue.  The pointer input points to the
       data that is to be added.  The length of the input to add is  given  by
       inputLen.   A  non-zero value of addAtEnd indicates that the data is to
       be added at the end of queue; otherwise it will be added at the head of
       the queue.  If channel has a “sticky” EOF set, no data will be added to
       the input queue.	 Tcl_Ungets returns inputLen or -1 if an error occurs.

TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE
       Tcl_WriteChars accepts bytesToWrite bytes of character data at charBuf.
       The  UTF-8  characters  in  the	buffer	are converted to the channel's
       encoding and queued for output to channel.  If  bytesToWrite  is	 nega‐
       tive,  Tcl_WriteChars expects charBuf to be null-terminated and it out‐
       puts everything up to the null.

       Data queued for output may not appear on the output device immediately,
       due to internal buffering.  If the data should appear immediately, call
       Tcl_Flush after the call	 to  Tcl_WriteChars,  or  set  the  -buffering
       option  on the channel to none.	If you wish the data to appear as soon
       as a complete line is accepted for output, set the -buffering option on
       the channel to line mode.

       The  return  value  of Tcl_WriteChars is a count of how many bytes were
       accepted for output to the channel.  This is either greater  than  zero
       to  indicate  success  or -1 to indicate that an error occurred.	 If an
       error occurs, Tcl_WriteChars records a POSIX error  code	 that  may  be
       retrieved with Tcl_GetErrno.

       Newline	characters  in the output data are translated to platform-spe‐
       cific end-of-line sequences according to the  -translation  option  for
       the channel.  This is done even if the channel has no encoding.

       Tcl_WriteObj  is	 similar  to  Tcl_WriteChars  except  it accepts a Tcl
       object whose contents will be output to the channel.  The UTF-8 charac‐
       ters  in writeObjPtr's string representation are converted to the chan‐
       nel's encoding and queued for output  to	 channel.   As	a  performance
       optimization, when writing to a channel with the encoding binary, UTF-8
       characters are not converted as they are written.  Instead,  the	 bytes
       in  writeObjPtr's  internal  representation  as a byte-array object are
       written to the channel.	The byte-array representation  of  the	object
       will  be	 constructed if it is needed.  In this way, byte-oriented data
       can be read from a channel, manipulated by calling Tcl_GetByteArrayFro‐
       mObj  and  related functions, and then written to a channel without the
       expense of ever converting to or from UTF-8.

       Tcl_Write is similar to Tcl_WriteChars  except  that  it	 does  not  do
       encoding conversions, regardless of the channel's encoding.  It is dep‐
       recated and exists for backwards compatibility with  non-international‐
       ized  Tcl extensions.  It accepts bytesToWrite bytes of data at byteBuf
       and queues them for output to channel.  If  bytesToWrite	 is  negative,
       Tcl_Write  expects  byteBuf to be null-terminated and it outputs every‐
       thing up to the null.

       Tcl_WriteRaw is the same as  Tcl_Write  but  does  not  compensate  for
       stacking.  While	 Tcl_Write (and the other functions in the API) always
       feed their input to the topmost channel in the stack the supplied chan‐
       nel  is	part  of,  Tcl_WriteRaw	 does  not. Thus this function is only
       usable for transformational channel drivers, i.e. drivers used  in  the
       middle  of  a  stack  of channels, to move data from the transformation
       into the channel below it.

TCL_FLUSH
       Tcl_Flush causes all of the buffered output  data  for  channel	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 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 even‐
       tually, 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 subsequent  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_TRUNCATECHANNEL
       Tcl_TruncateChannel truncates the file underlying channel  to  a	 given │
       length  of  bytes.  It  returns	TCL_OK if the operation succeeded, and │
       TCL_ERROR otherwise.

TCL_GETCHANNELOPTION
       Tcl_GetChannelOption retrieves, in optionValue, the value of one of the
       options currently in effect for a channel, or a list of all options and
       their values.  The channel argument identifies the channel for which to
       query  an  option or retrieve all options and their values.  If option‐
       Name 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_DStringAppendElement. The various  preexisting  options  and	 their
       possible	 values are described in the manual entry for the Tcl fconfig‐
       ure 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_SETCHANNELOPTION
       Tcl_SetChannelOption sets a new value newValue for an option optionName
       on  channel.   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  the interpreter's
       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 channel 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.

TCL_OUTPUTBUFFERED
       Tcl_OutputBuffered returns the number  of  bytes	 of  output  currently
       buffered	 in  the internal buffers for a channel. If the channel is not
       open for writing, this function always returns zero.

PLATFORM ISSUES
       The handles returned from Tcl_GetChannelHandle depend on	 the  platform
       and  the	 channel type.	On Unix platforms, the handle is always a Unix
       file descriptor as returned from the  open  system  call.   On  Windows
       platforms,  the	handle	is  a file HANDLE when the channel was created
       with Tcl_OpenFileChannel, Tcl_OpenCommandChannel, or  Tcl_MakeFileChan‐
       nel.  Other channel types may return a different type of handle on Win‐
       dows platforms.

SEE ALSO
       DString(3), fconfigure(n), filename(n), fopen(3), Tcl_CreateChannel(3)

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

Tcl				      8.3		Tcl_OpenFileChannel(3)
[top]

List of man pages available for Peanut

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