
 Copyright   The Regents  the University  California.
 All rights reserved.

 Permission  hereby granted, without written agreement and without
 license  royalty fees,  use, copy, modify, and distribute this
 documentation for any purpose, provided that the above copyright
 notice and the following two paragraphs appear  all copies.

   EVENT SHALL THE UNIVERSITY  CALIFORNIA  LIABLE  ANY PARTY
 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,  CONSEQUENTIAL DAMAGES
 ARISING OUT  THE USE  THIS DOCUMENTATION, EVEN  THE UNIVERSITY 
 CALIFORNIA HAS BEEN ADVISED  THE POSSIBILITY  SUCH DAMAGE.

 THE UNIVERSITY  CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES  MERCHANTABILITY
 AND FITNESS FOR  PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER 
    IS BASIS, AND THE UNIVERSITY  CALIFORNIA HAS  OBLIGATION 
 PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS,  MODIFICATIONS.
 
 The definitions below are for supplemental macros used  Tcl/Tk
 manual entries.

  name section  
	Replacement for   other man pages.  See below for valid
	section names.

  type name in/out 
	Start paragraph describing  argument   library procedure.
	type  type  argument  etc.), in/out  either in, out,
	 in/out  describe whether procedure reads  modifies arg,
	and indent  equivalent  second arg    ever 
	needed;  use  below instead)

   
	Give maximum sizes  arguments for setting tab stops.  Type and
	name are examples  largest possible arguments that will  passed
	  later.   args are omitted, default tab stops are used.

 
	Start box enclosure.  From here until next  everything will 
	enclosed  one large box.

 
	End  box enclosure.

 
	Begin vertical sidebar, for use  marking newly-changed parts
	 man pages.

 
	End  vertical sidebar.

 
	Begin  indented unfilled display.

 
	End  indented unfilled display.

	 Heading for Tcl/Tk man pages
   
      
  'cmds'              
  'lib'               
  'tcldp'               Tcl-DP Tcl-DP Commands
  'tcldpc'               Tcl-DP Tcl-DP Library Procedures
  'tcldpcmds'               Tcl-DP Tcl-DP Applications
  'tcldpintro'               Tcl-DP Introduction  Tcl-DP
    
   
 
	 Start  argument description
     
  
     
           

    
    
  	   	( )


  

    
  	   

  
    


	 define tabbing values for 
  
      
   

       
    
	   start boxed text
	   starting  location
	   

 
  
  
   
   
  
	   end boxed text  box now)

 
 
   
  
	Draw four-sided box normally, but don't draw top 
	box  the box started   earlier page.
    
     

  
     




  
	   start vertical sidebar
	   starting  location
	     troff;  for nroff this doesn't matter)
 
  'mc  
   
	   end  vertical sidebar
  'mc
  
 

 
 
    
 



  
	 Special macro  handle page bottom:  finish off current
	 box/sidebar   box/sidebar mode, then invoked standard
	 page bottom macro.
 
 

 
    
	Draw three-sided box  this  the box's first page,
	draw two sides but  top otherwise.
         
       

    
    
 x   y    




    
 
  

    
 

	   begin display



	   end display


 
 dp_filehandler tcldp

 NAME
dp_filehandler   to handle file descriptor conditions

dp_isready   Check if a socket has data pending

dp_update   Process pending events and/or when-idle handlers

dp_after   Execute a command after a certain amount of time has elapsed

dp_whenidle   Execute a command when the system is idle

dp_waitvariable   Wait for a variable to be modified
 SYNOPSIS
 dp_filehandler  sockId  ? mode   command ?

 dp_isready  sockId 

 dp_update ? idletasks ?

 dp_after ms ? arg1 arg2 arg3 ... ?

 dp_whenidle command ? arg1 arg2 arg3 ... ?

 dp_waitvariable variable 

 DESCRIPTION

The dp_isready command checks whether  sockId  is readable or
writeable using a select(2) system call.  It returns a list of up two
boolean values (i.e., 1 or 0).  The first value specifies whether
 sockId  is readable, and the second value specifies whether
 sockId  is writeable.  For example, the tcl expression

if [lindex [dp_isready file3] 1] {MyOutput file3}

calls MyOutput if file3 is writeable.
The dp_update command is equivalent to the Tk "update" command,
except that it operates even if a connection to the X server is not
present.  See the Tk documentation on "update" for an explanation of
it's usage.
The dp_after command is equivalent to the Tk "after" command,
except that it operates even if a connection to the X server is not
present.  See the Tk documentation on "after" for an explanation of
it's usage.
The dp_whenidle command arranges for the specified Tcl/Tk  command 
to be evaluated whenever the system is about to go to sleep waiting for
an event to occur.
The dp_waitvariable command is equivalent to the Tk "tkwait variable"
command, except that it operates even if a connection to the X server
is not present.  See the Tk documentation on "tkwait" for an explanation of
it's usage.
The dp_filehander command allows one to specify a Tcl/Tk
 command  which will be evaluated whenever the file descriptor
represented by  sockId  is readable, writable, and/or has an
exceptional condition pending.   Command  will be invoked with two
arguments appended: a single character indicating the  mode 
('r', 'w', or 'e'), and the  sockId .
A  sockId  is an identifier which represents a file descriptor.  It
is identical to the identifier manipulated by the Tcl-DP (Tcl
Distributed Programming) network connection management commands
(dp_connect, dp_shutdown, etc.).   SockId 's are also
manipulated by the read, eof, gets, puts, and close file management
commands of Tcl.
The  mode  argument indicates the situations when the  command 
will be evaluated.  It may be any combination of the following values:


 r 
Eval  command  whenever there is data to be read from the
 sockId .  The  command  is evaluated with two arguments
appended:  r  to indicate that data is readable on the file
descriptor, and the  sockId , which represents the file descriptor
that is readable.  The  command  should read at least some data
from the  sockId , or otherwise  command  will be called
continuously.

 w 
Eval  command  whenever data can be written to the  sockId 
without blocking.  The  command  is evaluated with two arguments
appended:  w  to indicate that the file descriptor is writable, and
the  sockId , which represents the writable file descriptor.

 e 
Eval  command  whenever there is an exceptional condition pending
on the  sockId .  The  command  is evaluated with two arguments
appended:  e  to indicate exception, and the  sockId , which
represents the file descriptor with the exceptional condition.

If the  mode  and  command  arguments are not specified, then
any previously specified  command  for the given  sockId  is
deleted.  Specifying a new  command  using the dp_filehandler
command will also delete any previously specified  command  for a
 sockId .
 EXAMPLE
The following file handlers create a telnet like interface to the
sendmail process (the smtp port) running on the local host.  The command
"say" sends the string passed to it to sendmail.  The reply is
automatically printed on stdout by the get_remote procedure.

proc get_remote {mode fid} {
    # Exit if remote connection closed on us.
    if {[gets $fid input] == -1} {
	puts stdout "Connection closed by foreign host."
	exit
    }
    puts stdout $input
}
proc say {args} {
    global remote
    puts $remote $args;
}
set remote [lindex [dp_connect localhost smtp] 0]
dp_filehandler $remote r get_remote

 SEE ALSO
Tcl-DP, select(2)
 AUTHOR
Pekka Nikander, Telecom Finland (Pekka.Nikander@ajk.tele.fi)

Extended by Tim MacKenzie (tym@dibbler.cs.monash.edu.au)

Further enhancements by Brian Smith (bsmith@cs.berkeley.edu)

and Steve Yen (syen@cs.berkeley.edu)
