1 /* 2 * tclIO.h -- 3 * 4 * This file provides the generic portions (those that are the same on 5 * all platforms and for all channel types) of Tcl's IO facilities. 6 * 7 * Copyright (c) 1998-2000 Ajuba Solutions 8 * Copyright (c) 1995-1997 Sun Microsystems, Inc. 9 * 10 * See the file "license.terms" for information on usage and redistribution of 11 * this file, and for a DISCLAIMER OF ALL WARRANTIES. 12 */ 13 14 /* 15 * Make sure that both EAGAIN and EWOULDBLOCK are defined. This does not 16 * compile on systems where neither is defined. We want both defined so that 17 * we can test safely for both. In the code we still have to test for both 18 * because there may be systems on which both are defined and have different 19 * values. 20 */ 21 22 #if ((!defined(EWOULDBLOCK)) && (defined(EAGAIN))) 23 # define EWOULDBLOCK EAGAIN 24 #endif 25 #if ((!defined(EAGAIN)) && (defined(EWOULDBLOCK))) 26 # define EAGAIN EWOULDBLOCK 27 #endif 28 #if ((!defined(EAGAIN)) && (!defined(EWOULDBLOCK))) 29 #error one of EWOULDBLOCK or EAGAIN must be defined 30 #endif 31 32 /* 33 * struct ChannelBuffer: 34 * 35 * Buffers data being sent to or from a channel. 36 */ 37 38 typedef struct ChannelBuffer { 39 int refCount; /* Current uses count */ 40 int nextAdded; /* The next position into which a character 41 * will be put in the buffer. */ 42 int nextRemoved; /* Position of next byte to be removed from 43 * the buffer. */ 44 int bufLength; /* How big is the buffer? */ 45 struct ChannelBuffer *nextPtr; 46 /* Next buffer in chain. */ 47 char buf[4]; /* Placeholder for real buffer. The real 48 * buffer occuppies this space + bufSize-4 49 * bytes. This must be the last field in the 50 * structure. */ 51 } ChannelBuffer; 52 53 #define CHANNELBUFFER_HEADER_SIZE (sizeof(ChannelBuffer) - 4) 54 55 /* 56 * How much extra space to allocate in buffer to hold bytes from previous 57 * buffer (when converting to UTF-8) or to hold bytes that will go to next 58 * buffer (when converting from UTF-8). 59 */ 60 61 #define BUFFER_PADDING 16 62 63 /* 64 * The following defines the *default* buffer size for channels. 65 */ 66 67 #define CHANNELBUFFER_DEFAULT_SIZE (1024 * 4) 68 69 /* 70 * The following structure describes the information saved from a call to 71 * "fileevent". This is used later when the event being waited for to invoke 72 * the saved script in the interpreter designed in this record. 73 */ 74 75 typedef struct EventScriptRecord { 76 struct Channel *chanPtr; /* The channel for which this script is 77 * registered. This is used only when an error 78 * occurs during evaluation of the script, to 79 * delete the handler. */ 80 Tcl_Obj *scriptPtr; /* Script to invoke. */ 81 Tcl_Interp *interp; /* In what interpreter to invoke script? */ 82 int mask; /* Events must overlap current mask for the 83 * stored script to be invoked. */ 84 struct EventScriptRecord *nextPtr; 85 /* Next in chain of records. */ 86 } EventScriptRecord; 87 88 /* 89 * struct Channel: 90 * 91 * One of these structures is allocated for each open channel. It contains 92 * data specific to the channel but which belongs to the generic part of the 93 * Tcl channel mechanism, and it points at an instance specific (and type 94 * specific) instance data, and at a channel type structure. 95 */ 96 97 typedef struct Channel { 98 struct ChannelState *state; /* Split out state information */ 99 ClientData instanceData; /* Instance-specific data provided by creator 100 * of channel. */ 101 Tcl_ChannelType *typePtr; /* Pointer to channel type structure. */ 102 struct Channel *downChanPtr;/* Refers to channel this one was stacked 103 * upon. This reference is NULL for normal 104 * channels. See Tcl_StackChannel. */ 105 struct Channel *upChanPtr; /* Refers to the channel above stacked this 106 * one. NULL for the top most channel. */ 107 108 /* 109 * Intermediate buffers to hold pre-read data for consumption by a newly 110 * stacked transformation. See 'Tcl_StackChannel'. 111 */ 112 113 ChannelBuffer *inQueueHead; /* Points at first buffer in input queue. */ 114 ChannelBuffer *inQueueTail; /* Points at last buffer in input queue. */ 115 116 int refCount; 117 } Channel; 118 119 /* 120 * struct ChannelState: 121 * 122 * One of these structures is allocated for each open channel. It contains 123 * data specific to the channel but which belongs to the generic part of the 124 * Tcl channel mechanism, and it points at an instance specific (and type 125 * specific) instance data, and at a channel type structure. 126 */ 127 128 typedef struct ChannelState { 129 char *channelName; /* The name of the channel instance in Tcl 130 * commands. Storage is owned by the generic 131 * IO code, is dynamically allocated. */ 132 int flags; /* ORed combination of the flags defined 133 * below. */ 134 Tcl_Encoding encoding; /* Encoding to apply when reading or writing 135 * data on this channel. NULL means no 136 * encoding is applied to data. */ 137 Tcl_EncodingState inputEncodingState; 138 /* Current encoding state, used when 139 * converting input data bytes to UTF-8. */ 140 int inputEncodingFlags; /* Encoding flags to pass to conversion 141 * routine when converting input data bytes to 142 * UTF-8. May be TCL_ENCODING_START before 143 * converting first byte and TCL_ENCODING_END 144 * when EOF is seen. */ 145 Tcl_EncodingState outputEncodingState; 146 /* Current encoding state, used when 147 * converting UTF-8 to output data bytes. */ 148 int outputEncodingFlags; /* Encoding flags to pass to conversion 149 * routine when converting UTF-8 to output 150 * data bytes. May be TCL_ENCODING_START 151 * before converting first byte and 152 * TCL_ENCODING_END when EOF is seen. */ 153 TclEolTranslation inputTranslation; 154 /* What translation to apply for end of line 155 * sequences on input? */ 156 TclEolTranslation outputTranslation; 157 /* What translation to use for generating end 158 * of line sequences in output? */ 159 int inEofChar; /* If nonzero, use this as a signal of EOF on 160 * input. */ 161 int outEofChar; /* If nonzero, append this to the channel when 162 * it is closed if it is open for writing. */ 163 int unreportedError; /* Non-zero if an error report was deferred 164 * because it happened in the background. The 165 * value is the POSIX error code. */ 166 int refCount; /* How many interpreters hold references to 167 * this IO channel? */ 168 struct CloseCallback *closeCbPtr; 169 /* Callbacks registered to be called when the 170 * channel is closed. */ 171 char *outputStage; /* Temporary staging buffer used when 172 * translating EOL before converting from 173 * UTF-8 to external form. */ 174 ChannelBuffer *curOutPtr; /* Current output buffer being filled. */ 175 ChannelBuffer *outQueueHead;/* Points at first buffer in output queue. */ 176 ChannelBuffer *outQueueTail;/* Points at last buffer in output queue. */ 177 ChannelBuffer *saveInBufPtr;/* Buffer saved for input queue - eliminates 178 * need to allocate a new buffer for "gets" 179 * that crosses buffer boundaries. */ 180 ChannelBuffer *inQueueHead; /* Points at first buffer in input queue. */ 181 ChannelBuffer *inQueueTail; /* Points at last buffer in input queue. */ 182 struct ChannelHandler *chPtr;/* List of channel handlers registered for 183 * this channel. */ 184 int interestMask; /* Mask of all events this channel has 185 * handlers for. */ 186 EventScriptRecord *scriptRecordPtr; 187 /* Chain of all scripts registered for event 188 * handlers ("fileevent") on this channel. */ 189 int bufSize; /* What size buffers to allocate? */ 190 Tcl_TimerToken timer; /* Handle to wakeup timer for this channel. */ 191 struct CopyState *csPtrR; /* State of background copy for which channel 192 * is input, or NULL. */ 193 struct CopyState *csPtrW; /* State of background copy for which channel 194 * is output, or NULL. */ 195 Channel *topChanPtr; /* Refers to topmost channel in a stack. Never 196 * NULL. */ 197 Channel *bottomChanPtr; /* Refers to bottommost channel in a stack. 198 * This channel can be relied on to live as 199 * long as the channel state. Never NULL. */ 200 struct ChannelState *nextCSPtr; 201 /* Next in list of channels currently open. */ 202 Tcl_ThreadId managingThread;/* TIP #10: Id of the thread managing this 203 * stack of channels. */ 204 205 /* 206 * TIP #219 ... Info for the I/O system ... 207 * Error message set by channel drivers, for the propagation of arbitrary 208 * Tcl errors. This information, if present (chanMsg not NULL), takes 209 * precedence over a posix error code returned by a channel operation. 210 */ 211 212 Tcl_Obj* chanMsg; 213 Tcl_Obj* unreportedMsg; /* Non-NULL if an error report was deferred 214 * because it happened in the background. The 215 * value is the chanMg, if any. #219's 216 * companion to 'unreportedError'. */ 217 } ChannelState; 218 219 /* 220 * Values for the flags field in Channel. Any ORed combination of the 221 * following flags can be stored in the field. These flags record various 222 * options and state bits about the channel. In addition to the flags below, 223 * the channel can also have TCL_READABLE (1<<1) and TCL_WRITABLE (1<<2) set. 224 */ 225 226 #define CHANNEL_NONBLOCKING (1<<3) /* Channel is currently in nonblocking 227 * mode. */ 228 #define CHANNEL_LINEBUFFERED (1<<4) /* Output to the channel must be 229 * flushed after every newline. */ 230 #define CHANNEL_UNBUFFERED (1<<5) /* Output to the channel must always 231 * be flushed immediately. */ 232 #define BG_FLUSH_SCHEDULED (1<<7) /* A background flush of the queued 233 * output buffers has been 234 * scheduled. */ 235 #define CHANNEL_CLOSED (1<<8) /* Channel has been closed. No further 236 * Tcl-level IO on the channel is 237 * allowed. */ 238 #define CHANNEL_EOF (1<<9) /* EOF occurred on this channel. This 239 * bit is cleared before every input 240 * operation. */ 241 #define CHANNEL_STICKY_EOF (1<<10) /* EOF occurred on this channel 242 * because we saw the input 243 * eofChar. This bit prevents clearing 244 * of the EOF bit before every input 245 * operation. */ 246 #define CHANNEL_BLOCKED (1<<11) /* EWOULDBLOCK or EAGAIN occurred on 247 * this channel. This bit is cleared 248 * before every input or output 249 * operation. */ 250 #define INPUT_SAW_CR (1<<12) /* Channel is in CRLF eol input 251 * translation mode and the last byte 252 * seen was a "\r". */ 253 #define CHANNEL_DEAD (1<<13) /* The channel has been closed by the 254 * exit handler (on exit) but not 255 * deallocated. When any IO operation 256 * sees this flag on a channel, it 257 * does not call driver level 258 * functions to avoid referring to 259 * deallocated data. */ 260 #define CHANNEL_NEED_MORE_DATA (1<<14) /* The last input operation failed 261 * because there was not enough data 262 * to complete the operation. This 263 * flag is set when gets fails to get 264 * a complete line or when read fails 265 * to get a complete character. When 266 * set, file events will not be 267 * delivered for buffered data until 268 * the state of the channel 269 * changes. */ 270 #define CHANNEL_RAW_MODE (1<<16) /* When set, notes that the Raw API is 271 * being used. */ 272 273 #define CHANNEL_INCLOSE (1<<19) /* Channel is currently being closed. 274 * Its structures are still live and 275 * usable, but it may not be closed 276 * again from within the close 277 * handler. */ 278 #define CHANNEL_TAINTED (1<<20) /* Channel stack structure has changed. 279 * Used by Channel Tcl_Obj type to 280 * determine if we have to revalidate 281 * the channel. */ 282 283 /* 284 * Local Variables: 285 * mode: c 286 * c-basic-offset: 4 287 * fill-column: 78 288 * End: 289 */ 290