summaryrefslogtreecommitdiffstats
path: root/generic/tclIO.h
diff options
context:
space:
mode:
Diffstat (limited to 'generic/tclIO.h')
-rw-r--r--generic/tclIO.h360
1 files changed, 178 insertions, 182 deletions
diff --git a/generic/tclIO.h b/generic/tclIO.h
index 9ec4abc..f7afdc5 100644
--- a/generic/tclIO.h
+++ b/generic/tclIO.h
@@ -1,4 +1,4 @@
-/*
+/*
* tclIO.h --
*
* This file provides the generic portions (those that are the same on
@@ -7,18 +7,18 @@
* Copyright (c) 1998-2000 Ajuba Solutions
* Copyright (c) 1995-1997 Sun Microsystems, Inc.
*
- * See the file "license.terms" for information on usage and redistribution
- * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+ * See the file "license.terms" for information on usage and redistribution of
+ * this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclIO.h,v 1.8 2005/08/24 17:56:23 andreas_kupries Exp $
+ * RCS: @(#) $Id: tclIO.h,v 1.9 2005/10/13 00:56:59 dkf Exp $
*/
/*
* Make sure that both EAGAIN and EWOULDBLOCK are defined. This does not
- * compile on systems where neither is defined. We want both defined so
- * that we can test safely for both. In the code we still have to test for
- * both because there may be systems on which both are defined and have
- * different values.
+ * compile on systems where neither is defined. We want both defined so that
+ * we can test safely for both. In the code we still have to test for both
+ * because there may be systems on which both are defined and have different
+ * values.
*/
#if ((!defined(EWOULDBLOCK)) && (defined(EAGAIN)))
@@ -28,12 +28,12 @@
# define EAGAIN EWOULDBLOCK
#endif
#if ((!defined(EAGAIN)) && (!defined(EWOULDBLOCK)))
-error one of EWOULDBLOCK or EAGAIN must be defined
+#error one of EWOULDBLOCK or EAGAIN must be defined
#endif
/*
* The following structure encapsulates the state for a background channel
- * copy. Note that the data buffer for the copy will be appended to this
+ * copy. Note that the data buffer for the copy will be appended to this
* structure.
*/
@@ -59,28 +59,28 @@ typedef struct CopyState {
typedef struct ChannelBuffer {
int nextAdded; /* The next position into which a character
- * will be put in the buffer. */
- int nextRemoved; /* Position of next byte to be removed
- * from the buffer. */
+ * will be put in the buffer. */
+ int nextRemoved; /* Position of next byte to be removed from
+ * the buffer. */
int bufLength; /* How big is the buffer? */
struct ChannelBuffer *nextPtr;
/* Next buffer in chain. */
char buf[4]; /* Placeholder for real buffer. The real
- * buffer occuppies this space + bufSize-4
- * bytes. This must be the last field in
- * the structure. */
+ * buffer occuppies this space + bufSize-4
+ * bytes. This must be the last field in the
+ * structure. */
} ChannelBuffer;
#define CHANNELBUFFER_HEADER_SIZE (sizeof(ChannelBuffer) - 4)
/*
* How much extra space to allocate in buffer to hold bytes from previous
- * buffer (when converting to UTF-8) or to hold bytes that will go to
- * next buffer (when converting from UTF-8).
+ * buffer (when converting to UTF-8) or to hold bytes that will go to next
+ * buffer (when converting from UTF-8).
*/
-
-#define BUFFER_PADDING 16
-
+
+#define BUFFER_PADDING 16
+
/*
* The following defines the *default* buffer size for channels.
*/
@@ -88,28 +88,29 @@ typedef struct ChannelBuffer {
#define CHANNELBUFFER_DEFAULT_SIZE (1024 * 4)
/*
- * Structure to record a close callback. One such record exists for
- * each close callback registered for a channel.
+ * Structure to record a close callback. One such record exists for each close
+ * callback registered for a channel.
*/
typedef struct CloseCallback {
- Tcl_CloseProc *proc; /* The procedure to call. */
- ClientData clientData; /* Arbitrary one-word data to pass
- * to the callback. */
- struct CloseCallback *nextPtr; /* For chaining close callbacks. */
+ Tcl_CloseProc *proc; /* The procedure to call. */
+ ClientData clientData; /* Arbitrary one-word data to pass to the
+ * callback. */
+ struct CloseCallback *nextPtr;
+ /* For chaining close callbacks. */
} CloseCallback;
/*
* The following structure describes the information saved from a call to
- * "fileevent". This is used later when the event being waited for to
- * invoke the saved script in the interpreter designed in this record.
+ * "fileevent". This is used later when the event being waited for to invoke
+ * the saved script in the interpreter designed in this record.
*/
typedef struct EventScriptRecord {
struct Channel *chanPtr; /* The channel for which this script is
- * registered. This is used only when an
- * error occurs during evaluation of the
- * script, to delete the handler. */
+ * registered. This is used only when an error
+ * occurs during evaluation of the script, to
+ * delete the handler. */
Tcl_Obj *scriptPtr; /* Script to invoke. */
Tcl_Interp *interp; /* In what interpreter to invoke script? */
int mask; /* Events must overlap current mask for the
@@ -121,29 +122,28 @@ typedef struct EventScriptRecord {
/*
* struct Channel:
*
- * One of these structures is allocated for each open channel. It contains data
- * specific to the channel but which belongs to the generic part of the Tcl
- * channel mechanism, and it points at an instance specific (and type
- * specific) * instance data, and at a channel type structure.
+ * One of these structures is allocated for each open channel. It contains
+ * data specific to the channel but which belongs to the generic part of the
+ * Tcl channel mechanism, and it points at an instance specific (and type
+ * specific) instance data, and at a channel type structure.
*/
typedef struct Channel {
struct ChannelState *state; /* Split out state information */
-
- ClientData instanceData; /* Instance-specific data provided by
- * creator of channel. */
+ ClientData instanceData; /* Instance-specific data provided by creator
+ * of channel. */
Tcl_ChannelType *typePtr; /* Pointer to channel type structure. */
-
struct Channel *downChanPtr;/* Refers to channel this one was stacked
- * upon. This reference is NULL for normal
- * channels. See Tcl_StackChannel. */
+ * upon. This reference is NULL for normal
+ * channels. See Tcl_StackChannel. */
struct Channel *upChanPtr; /* Refers to the channel above stacked this
* one. NULL for the top most channel. */
/*
- * Intermediate buffers to hold pre-read data for consumption by a
- * newly stacked transformation. See 'Tcl_StackChannel'.
+ * Intermediate buffers to hold pre-read data for consumption by a newly
+ * stacked transformation. See 'Tcl_StackChannel'.
*/
+
ChannelBuffer *inQueueHead; /* Points at first buffer in input queue. */
ChannelBuffer *inQueueTail; /* Points at last buffer in input queue. */
} Channel;
@@ -151,54 +151,52 @@ typedef struct Channel {
/*
* struct ChannelState:
*
- * One of these structures is allocated for each open channel. It contains data
- * specific to the channel but which belongs to the generic part of the Tcl
- * channel mechanism, and it points at an instance specific (and type
- * specific) * instance data, and at a channel type structure.
+ * One of these structures is allocated for each open channel. It contains
+ * data specific to the channel but which belongs to the generic part of the
+ * Tcl channel mechanism, and it points at an instance specific (and type
+ * specific) instance data, and at a channel type structure.
*/
typedef struct ChannelState {
CONST char *channelName; /* The name of the channel instance in Tcl
- * commands. Storage is owned by the generic IO
- * code, is dynamically allocated. */
+ * commands. Storage is owned by the generic
+ * IO code, is dynamically allocated. */
int flags; /* ORed combination of the flags defined
* below. */
Tcl_Encoding encoding; /* Encoding to apply when reading or writing
- * data on this channel. NULL means no
+ * data on this channel. NULL means no
* encoding is applied to data. */
Tcl_EncodingState inputEncodingState;
- /* Current encoding state, used when converting
- * input data bytes to UTF-8. */
+ /* Current encoding state, used when
+ * converting input data bytes to UTF-8. */
int inputEncodingFlags; /* Encoding flags to pass to conversion
* routine when converting input data bytes to
- * UTF-8. May be TCL_ENCODING_START before
+ * UTF-8. May be TCL_ENCODING_START before
* converting first byte and TCL_ENCODING_END
* when EOF is seen. */
Tcl_EncodingState outputEncodingState;
- /* Current encoding state, used when converting
- * UTF-8 to output data bytes. */
+ /* Current encoding state, used when
+ * converting UTF-8 to output data bytes. */
int outputEncodingFlags; /* Encoding flags to pass to conversion
* routine when converting UTF-8 to output
- * data bytes. May be TCL_ENCODING_START
+ * data bytes. May be TCL_ENCODING_START
* before converting first byte and
* TCL_ENCODING_END when EOF is seen. */
TclEolTranslation inputTranslation;
/* What translation to apply for end of line
- * sequences on input? */
+ * sequences on input? */
TclEolTranslation outputTranslation;
- /* What translation to use for generating
- * end of line sequences in output? */
- int inEofChar; /* If nonzero, use this as a signal of EOF
- * on input. */
- int outEofChar; /* If nonzero, append this to the channel
- * when it is closed if it is open for
- * writing. */
+ /* What translation to use for generating end
+ * of line sequences in output? */
+ int inEofChar; /* If nonzero, use this as a signal of EOF on
+ * input. */
+ int outEofChar; /* If nonzero, append this to the channel when
+ * it is closed if it is open for writing. */
int unreportedError; /* Non-zero if an error report was deferred
* because it happened in the background. The
* value is the POSIX error code. */
int refCount; /* How many interpreters hold references to
* this IO channel? */
-
CloseCallback *closeCbPtr; /* Callbacks registered to be called when the
* channel is closed. */
char *outputStage; /* Temporary staging buffer used when
@@ -207,50 +205,45 @@ typedef struct ChannelState {
ChannelBuffer *curOutPtr; /* Current output buffer being filled. */
ChannelBuffer *outQueueHead;/* Points at first buffer in output queue. */
ChannelBuffer *outQueueTail;/* Points at last buffer in output queue. */
-
ChannelBuffer *saveInBufPtr;/* Buffer saved for input queue - eliminates
* need to allocate a new buffer for "gets"
* that crosses buffer boundaries. */
ChannelBuffer *inQueueHead; /* Points at first buffer in input queue. */
ChannelBuffer *inQueueTail; /* Points at last buffer in input queue. */
-
- struct ChannelHandler *chPtr;/* List of channel handlers registered
- * for this channel. */
+ struct ChannelHandler *chPtr;/* List of channel handlers registered for
+ * this channel. */
int interestMask; /* Mask of all events this channel has
* handlers for. */
EventScriptRecord *scriptRecordPtr;
- /* Chain of all scripts registered for
- * event handlers ("fileevent") on this
- * channel. */
-
+ /* Chain of all scripts registered for event
+ * handlers ("fileevent") on this channel. */
int bufSize; /* What size buffers to allocate? */
Tcl_TimerToken timer; /* Handle to wakeup timer for this channel. */
CopyState *csPtr; /* State of background copy, or NULL. */
- Channel *topChanPtr; /* Refers to topmost channel in a stack.
- * Never NULL. */
+ Channel *topChanPtr; /* Refers to topmost channel in a stack. Never
+ * NULL. */
Channel *bottomChanPtr; /* Refers to bottommost channel in a stack.
* This channel can be relied on to live as
* long as the channel state. Never NULL. */
struct ChannelState *nextCSPtr;
/* Next in list of channels currently open. */
- Tcl_ThreadId managingThread; /* TIP #10: Id of the thread managing
- * this stack of channels. */
-
- /* TIP #219 ... Info for the I/O system ...
- * Error message set by channel drivers, for the propagation of
- * arbitrary Tcl errors. This information, if present (chanMsg not
- * NULL), takes precedence over a posix error code returned by a
- * channel operation.
+ Tcl_ThreadId managingThread;/* TIP #10: Id of the thread managing this
+ * stack of channels. */
+
+ /*
+ * TIP #219 ... Info for the I/O system ...
+ * Error message set by channel drivers, for the propagation of arbitrary
+ * Tcl errors. This information, if present (chanMsg not NULL), takes
+ * precedence over a posix error code returned by a channel operation.
*/
Tcl_Obj* chanMsg;
- Tcl_Obj* unreportedMsg; /* Non-NULL if an error report was
- * deferred because it happened in the
- * background. The value is the
- * chanMg, if any. #219's companion to
- * 'unreportedError'. */
+ Tcl_Obj* unreportedMsg; /* Non-NULL if an error report was deferred
+ * because it happened in the background. The
+ * value is the chanMg, if any. #219's
+ * companion to 'unreportedError'. */
} ChannelState;
-
+
/*
* Values for the flags field in Channel. Any ORed combination of the
* following flags can be stored in the field. These flags record various
@@ -258,107 +251,102 @@ typedef struct ChannelState {
* the channel can also have TCL_READABLE (1<<1) and TCL_WRITABLE (1<<2) set.
*/
-#define CHANNEL_NONBLOCKING (1<<3) /* Channel is currently in
- * nonblocking mode. */
+#define CHANNEL_NONBLOCKING (1<<3) /* Channel is currently in nonblocking
+ * mode. */
#define CHANNEL_LINEBUFFERED (1<<4) /* Output to the channel must be
* flushed after every newline. */
#define CHANNEL_UNBUFFERED (1<<5) /* Output to the channel must always
* be flushed immediately. */
#define BUFFER_READY (1<<6) /* Current output buffer (the
- * curOutPtr field in the
- * channel structure) should be
- * output as soon as possible even
- * though it may not be full. */
-#define BG_FLUSH_SCHEDULED (1<<7) /* A background flush of the
- * queued output buffers has been
- * scheduled. */
-#define CHANNEL_CLOSED (1<<8) /* Channel has been closed. No
- * further Tcl-level IO on the
- * channel is allowed. */
-#define CHANNEL_EOF (1<<9) /* EOF occurred on this channel.
- * This bit is cleared before every
- * input operation. */
-#define CHANNEL_STICKY_EOF (1<<10) /* EOF occurred on this channel because
- * we saw the input eofChar. This bit
- * prevents clearing of the EOF bit
- * before every input operation. */
-#define CHANNEL_BLOCKED (1<<11) /* EWOULDBLOCK or EAGAIN occurred
- * on this channel. This bit is
- * cleared before every input or
- * output operation. */
+ * curOutPtr field in the channel
+ * structure) should be output as soon
+ * as possible even though it may not
+ * be full. */
+#define BG_FLUSH_SCHEDULED (1<<7) /* A background flush of the queued
+ * output buffers has been
+ * scheduled. */
+#define CHANNEL_CLOSED (1<<8) /* Channel has been closed. No further
+ * Tcl-level IO on the channel is
+ * allowed. */
+#define CHANNEL_EOF (1<<9) /* EOF occurred on this channel. This
+ * bit is cleared before every input
+ * operation. */
+#define CHANNEL_STICKY_EOF (1<<10) /* EOF occurred on this channel
+ * because we saw the input
+ * eofChar. This bit prevents clearing
+ * of the EOF bit before every input
+ * operation. */
+#define CHANNEL_BLOCKED (1<<11) /* EWOULDBLOCK or EAGAIN occurred on
+ * this channel. This bit is cleared
+ * before every input or output
+ * operation. */
#define INPUT_SAW_CR (1<<12) /* Channel is in CRLF eol input
- * translation mode and the last
- * byte seen was a "\r". */
+ * translation mode and the last byte
+ * seen was a "\r". */
#define INPUT_NEED_NL (1<<15) /* Saw a '\r' at end of last buffer,
* and there should be a '\n' at
* beginning of next buffer. */
-#define CHANNEL_DEAD (1<<13) /* The channel has been closed by
- * the exit handler (on exit) but
- * not deallocated. When any IO
- * operation sees this flag on a
- * channel, it does not call driver
- * level functions to avoid referring
- * to deallocated data. */
+#define CHANNEL_DEAD (1<<13) /* The channel has been closed by the
+ * exit handler (on exit) but not
+ * deallocated. When any IO operation
+ * sees this flag on a channel, it
+ * does not call driver level
+ * functions to avoid referring to
+ * deallocated data. */
#define CHANNEL_NEED_MORE_DATA (1<<14) /* The last input operation failed
* because there was not enough data
- * to complete the operation. This
- * flag is set when gets fails to
- * get a complete line or when read
- * fails to get a complete character.
- * When set, file events will not be
+ * to complete the operation. This
+ * flag is set when gets fails to get
+ * a complete line or when read fails
+ * to get a complete character. When
+ * set, file events will not be
* delivered for buffered data until
- * the state of the channel changes. */
+ * the state of the channel
+ * changes. */
#define CHANNEL_RAW_MODE (1<<16) /* When set, notes that the Raw API is
* being used. */
#ifdef TCL_IO_TRACK_OS_FOR_DRIVER_WITH_BAD_BLOCKING
-#define CHANNEL_TIMER_FEV (1<<17) /* When set the event we are
- * notified by is a fileevent
- * generated by a timer. We
- * don't know if the driver
- * has more data and should
- * not try to read from it. If
- * the system needs more than
- * is in the buffers out read
- * routines will simulate a
- * short read (0 characters
- * read) */
-#define CHANNEL_HAS_MORE_DATA (1<<18) /* Set by NotifyChannel for a
- * channel if and only if the
- * channel is configured
- * non-blocking, the driver
+#define CHANNEL_TIMER_FEV (1<<17) /* When set the event we are notified
+ * by is a fileevent generated by a
+ * timer. We don't know if the driver
+ * has more data and should not try to
+ * read from it. If the system needs
+ * more than is in the buffers out
+ * read routines will simulate a short
+ * read (0 characters read) */
+#define CHANNEL_HAS_MORE_DATA (1<<18) /* Set by NotifyChannel for a channel
+ * if and only if the channel is
+ * configured non-blocking, the driver
* for said channel has no
- * blockmodeproc, and data has
- * arrived for reading at the
- * OS level). A GetInput will
- * pass reading from the
+ * blockmodeproc, and data has arrived
+ * for reading at the OS level). A
+ * GetInput will pass reading from the
* driver if the channel is
- * non-blocking, without
- * blockmode proc and the flag
- * has not been set. A read
- * will be performed if the
- * flag is set. This will
- * reset the flag as well. */
+ * non-blocking, without blockmode
+ * proc and the flag has not been set.
+ * A read will be performed if the
+ * flag is set. This will reset the
+ * flag as well. */
#endif /* TCL_IO_TRACK_OS_FOR_DRIVER_WITH_BAD_BLOCKING */
-#define CHANNEL_INCLOSE (1<<19) /* Channel is currently being
- * closed. Its structures are
- * still live and usable, but
- * it may not be closed again
- * from within the close handler.
- */
+#define CHANNEL_INCLOSE (1<<19) /* Channel is currently being closed.
+ * Its structures are still live and
+ * usable, but it may not be closed
+ * again from within the close
+ * handler. */
/*
* For each channel handler registered in a call to Tcl_CreateChannelHandler,
* there is one record of the following type. All of records for a specific
- * channel are chained together in a singly linked list which is stored in
- * the channel structure.
+ * channel are chained together in a singly linked list which is stored in the
+ * channel structure.
*/
typedef struct ChannelHandler {
Channel *chanPtr; /* The channel structure for this channel. */
int mask; /* Mask of desired events. */
Tcl_ChannelProc *proc; /* Procedure to call in the type of
- * Tcl_CreateChannelHandler. */
+ * Tcl_CreateChannelHandler. */
ClientData clientData; /* Argument to pass to procedure. */
struct ChannelHandler *nextPtr;
/* Next one in list of registered handlers. */
@@ -381,17 +369,17 @@ typedef struct ChannelHandler {
*/
typedef struct NextChannelHandler {
- ChannelHandler *nextHandlerPtr; /* The next handler to be invoked in
- * this invocation. */
+ ChannelHandler *nextHandlerPtr;
+ /* The next handler to be invoked in this
+ * invocation. */
struct NextChannelHandler *nestedHandlerPtr;
- /* Next nested invocation of
- * ChannelHandlerEventProc. */
+ /* Next nested invocation of
+ * ChannelHandlerEventProc. */
} NextChannelHandler;
-
/*
- * The following structure describes the event that is added to the Tcl
- * event queue by the channel handler check procedure.
+ * The following structure describes the event that is added to the Tcl event
+ * queue by the channel handler check procedure.
*/
typedef struct ChannelHandlerEvent {
@@ -401,26 +389,26 @@ typedef struct ChannelHandlerEvent {
} ChannelHandlerEvent;
/*
- * The following structure is used by Tcl_GetsObj() to encapsulates the
- * state for a "gets" operation.
+ * The following structure is used by Tcl_GetsObj() to encapsulates the state
+ * for a "gets" operation.
*/
-
+
typedef struct GetsState {
- Tcl_Obj *objPtr; /* The object to which UTF-8 characters
- * will be appended. */
- char **dstPtr; /* Pointer into objPtr's string rep where
- * next character should be stored. */
- Tcl_Encoding encoding; /* The encoding to use to convert raw bytes
- * to UTF-8. */
+ Tcl_Obj *objPtr; /* The object to which UTF-8 characters will
+ * be appended. */
+ char **dstPtr; /* Pointer into objPtr's string rep where next
+ * character should be stored. */
+ Tcl_Encoding encoding; /* The encoding to use to convert raw bytes to
+ * UTF-8. */
ChannelBuffer *bufPtr; /* The current buffer of raw bytes being
* emptied. */
Tcl_EncodingState state; /* The encoding state just before the last
* external to UTF-8 conversion in
* FilterInputBytes(). */
- int rawRead; /* The number of bytes removed from bufPtr
- * in the last call to FilterInputBytes(). */
- int bytesWrote; /* The number of bytes of UTF-8 data
- * appended to objPtr during the last call to
+ int rawRead; /* The number of bytes removed from bufPtr in
+ * the last call to FilterInputBytes(). */
+ int bytesWrote; /* The number of bytes of UTF-8 data appended
+ * to objPtr during the last call to
* FilterInputBytes(). */
int charsWrote; /* The corresponding number of UTF-8
* characters appended to objPtr during the
@@ -429,3 +417,11 @@ typedef struct GetsState {
* appended to objPtr so far, just before the
* last call to FilterInputBytes(). */
} GetsState;
+
+/*
+ * Local Variables:
+ * mode: c
+ * c-basic-offset: 4
+ * fill-column: 78
+ * End:
+ */