Tcl_InputBlocked man page on DigitalUNIX

Printed from http://www.polarhome.com/service/man/?qf=Tcl_InputBlocked&af=0&tf=2&of=DigitalUNIX

Tcl_OpenFileChannel(3)	    Tcl Library Procedures	Tcl_OpenFileChannel(3)

______________________________________________________________________________

NAME
       Tcl_OpenFileChannel,    Tcl_OpenCommandChannel,	  Tcl_MakeFileChannel,
       Tcl_GetChannel, Tcl_RegisterChannel, Tcl_UnregisterChannel,  Tcl_Close,
       Tcl_Read,  Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof,
       Tcl_InputBlocked, Tcl_InputBuffered, Tcl_GetChannelOption, Tcl_SetChan‐
       nelOption - buffered I/O facilities using channels

SYNOPSIS
       #include <tcl.h>

       typedef ... Tcl_Channel;

       Tcl_Channel
       Tcl_OpenFileChannel(interp, fileName, mode, permissions)

       Tcl_Channel
       Tcl_OpenCommandChannel(interp, argc, argv, flags)

       Tcl_Channel							       │
       Tcl_MakeFileChannel(handle, readOrWrite)				       │

       Tcl_Channel
       Tcl_GetChannel(interp, channelName, modePtr)

       void
       Tcl_RegisterChannel(interp, channel)

       int
       Tcl_UnregisterChannel(interp, channel)

       int
       Tcl_Close(interp, channel)

       int
       Tcl_Read(channel, buf, toRead)

       int
       Tcl_Gets(channel, lineRead)

       int
       Tcl_GetsObj(channel, lineObjPtr)

       int
       Tcl_Write(channel, buf, toWrite)

       int
       Tcl_Flush(channel)

       int
       Tcl_Seek(channel, offset, seekMode)

       int
       Tcl_Tell(channel)

       int
       Tcl_GetChannelOption(interp, channel, optionName, optionValue)

       int
       Tcl_SetChannelOption(interp, channel, optionName, newValue)

       int
       Tcl_Eof(channel)

       int
       Tcl_InputBlocked(channel)

       int
       Tcl_InputBuffered(channel)

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

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

       char		 *mode		    (in)      Specifies how  the  file
						      is  to be accessed.  May
						      have any of  the	values
						      allowed	for  the  mode
						      argument to the Tcl open
						      command.	 For Tcl_Open‐
						      CommandChannel,  may  be
						      NULL.

       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.

       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.

       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.

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

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

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

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

       int		 toRead		    (in)      The number of  bytes  to
						      read from the channel.

       Tcl_DString	 *lineRead	    (in)      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.

       Tcl_Obj		 *linePtrObj	    (in)      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.

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

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

       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.

       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 modelled 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 modelled 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->result after any error.

       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 interp->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 mode argument is not NULL, it points  at
       an integer variable that will receive an OR-ed combination of TCL_READ‐
       ABLE and TCL_WRITABLE describing whether the channel is open for	 read‐
       ing and writing.

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.

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_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 interp->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_READ
       Tcl_Read consumes up to toRead bytes of data from channel and stores it
       at buf.	The return value of Tcl_Read is the number of characters writ‐
       ten at buf.  The buffer produced by Tcl_Read is	not  NULL  terminated.
       Its contents are valid from the zeroth position up to and excluding the
       position indicated by the return value.	If an error occurs, the return
       value  is  -1  and  Tcl_Read  records  a	 POSIX	error code that can be
       retrieved with Tcl_GetErrno.

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

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

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

TCL_GETS AND TCL_GETSOBJ
       Tcl_Gets	 reads	a  line of input from a channel and appends all of the
       characters of the line except for the terminating  end-of-line  charac‐
       ter(s)  to  the dynamic string given by dsPtr.  The end-of-line charac‐
       ter(s) are read and discarded.

       If a line was successfully read, the return value is  greater  than  or
       equal  to zero, and it indicates the number of characters stored in the
       dynamic string.	If an error occurs, Tcl_Gets returns -1 and records  a
       POSIX  error  code  that	 can be retrieved with Tcl_GetErrno.  Tcl_Gets
       also returns -1 if the end of the file is reached; the  Tcl_Eof	proce‐
       dure 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_GetsObj is the same as Tcl_Gets except the resulting characters are
       appended to a Tcl object lineObjPtr rather than a dynamic string.

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

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

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

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

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  dsPtr,  the  value	 of one of the
       options currently in effect for a channel, or a list of all options and
       their values.  The channel 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  for  an  option  on channel.
       OptionName is the option to set and newValue is the value to set.   The
       procedure  normally  returns  TCL_OK.   If  an error occurs, it returns
       TCL_ERROR;  in addition, if interp  is  non-NULL,  Tcl_SetChannelOption
       leaves an error message in interp->result.

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

TCL_INPUTBLOCKED
       Tcl_InputBlocked returns a nonzero value if channel is  in  nonblocking
       mode  and  the  last  input operation returned less data than requested
       because there was insufficient data available.  The call always returns
       zero if the 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.

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(2), 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.0		Tcl_OpenFileChannel(3)
[top]

List of man pages available for DigitalUNIX

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