Tcl_Gets man page on YellowDog

Man page or keyword search:  
man Server   18644 pages
apropos Keyword Search (all sections)
Output format
YellowDog 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_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_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
						      command.

       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 construct‐
						      ing  a command pipeline.
						      These  values  have  the
						      same meaning as the non-
						      switch arguments to  the
						      Tcl exec command.

       int		 flags		    (in)      Specifies	 the  disposi‐
						      tion of the  stdio  han‐
						      dles  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	  spe‐
						      cific  handle for I/O to
						      a file. For Unix this is
						      a	 file  descriptor, for
						      Windows it is a HANDLE.

       int		 readOrWrite	    (in)      OR-ed   combination   of
						      TCL_READABLE	   and
						      TCL_WRITABLE to indicate
						      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	combi‐
						      nation  of  TCL_READABLE
						      and TCL_WRITABLE	denot‐
						      ing  whether the channel
						      is open for reading  and
						      writing.		       │

       CONST char	 *pattern	    (in)			       │
						      The pattern to match on, │
						      passed  to   Tcl_String‐ │
						      Match, or NULL.

       Tcl_Channel	 channel	    (in)      A	 Tcl channel for input
						      or  output.   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 chan‐ │
						      nel.  If	the  channel'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 │
						      contents 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 │
						      buffer.

       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
						      characters 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  output  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 seekMode.  May
						      be  either  positive  or
						      negative.

       int		 seekMode	    (in)      Relative	to which point
						      to seek; used with  off‐
						      set to calculate the new
						      access  point  for   the
						      channel.	 Legal	values
						      are SEEK_SET,  SEEK_CUR,
						      and SEEK_END.

       CONST char	 *optionName	    (in)      The  name	 of  an option
						      applicable to this chan‐
						      nel,  such as -blocking.
						      May have any of the val‐
						      ues   accepted   by  the
						      fconfigure command.

       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 call‐
						      er.

       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 doesn't 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 doesn't 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 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_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.	On the Macintosh platform, the handle is a file refer‐
       ence number as returned from HOpenDF.

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 YellowDog

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