Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  ar-
					      gument 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  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 er-
					      ror.

       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  in-
					      put  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  de-
       scribed	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  er-
       ror  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	preference  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 re-
       placement 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 in-
       dicates 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  re-
       placement 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, de-
       scribed 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 re-
       sult.

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 ex-
       ecuting	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 en-
       coding  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 po-
       sition 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  ob-
       ject.

TCL_UNGETS
       Tcl_Ungets  is used to add data to the input queue of a channel,	at ei-
       ther 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  en-
       coding  and queued for output to	channel.  If bytesToWrite is negative,
       Tcl_WriteChars expects charBuf to be null-terminated and	it outputs ev-
       erything	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 op-
       tion 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 re-
       trieved 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  ob-
       ject  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 op-
       timization, 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 en-
       coding 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  us-
       able  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 re-
       turns 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  re-
       trieved 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  oc-
       curs,  it  returns  TCL_ERROR;	in  addition,  if  interp is non-NULL,
       Tcl_SetChannelOption leaves an error message in the  interpreter's  re-
       sult.

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 be-
       cause 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)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | TCL_OPENFILECHANNEL | TCL_OPENCOMMANDCHANNEL | TCL_MAKEFILECHANNEL | TCL_GETCHANNEL | TCL_REGISTERCHANNEL | TCL_UNREGISTERCHANNEL | TCL_DETACHCHANNEL | TCL_ISSTANDARDCHANNEL | TCL_CLOSE | TCL_READCHARS AND TCL_READ | TCL_GETSOBJ AND TCL_GETS | TCL_UNGETS | TCL_WRITECHARS, TCL_WRITEOBJ, AND TCL_WRITE | TCL_FLUSH | TCL_SEEK | TCL_TELL | TCL_TRUNCATECHANNEL | TCL_GETCHANNELOPTION | TCL_SETCHANNELOPTION | TCL_EOF | TCL_INPUTBLOCKED | TCL_INPUTBUFFERED | TCL_OUTPUTBUFFERED | PLATFORM ISSUES | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_Close.tcl85&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help