tcl.h

是初学者升入中级必看的书籍

/*
 * The following declarations either map ckalloc and ckfree to
 * malloc and free, or they map them to procedures with all sorts
 * of debugging hooks defined in tclCkalloc.c.
 */
#ifdef TCL_MEM_DEBUG

#   define ckalloc(x) Tcl_DbCkalloc(x, __FILE__, __LINE__)
#   define ckfree(x)  Tcl_DbCkfree(x, __FILE__, __LINE__)
#   define ckrealloc(x,y) Tcl_DbCkrealloc((x), (y),__FILE__, __LINE__)
#   define attemptckalloc(x) Tcl_AttemptDbCkalloc(x, __FILE__, __LINE__)
#   define attemptckrealloc(x,y) Tcl_AttemptDbCkrealloc((x), (y), __FILE__, __LINE__)
#else /* !TCL_MEM_DEBUG */

/*
 * If we are not using the debugging allocator, we should call the 
 * Tcl_Alloc, et al. routines in order to guarantee that every module
 * is using the same memory allocator both inside and outside of the
 * Tcl library.
 */
#   define ckalloc(x) Tcl_Alloc(x)
#   define ckfree(x) Tcl_Free(x)
#   define ckrealloc(x,y) Tcl_Realloc(x,y)
#   define attemptckalloc(x) Tcl_AttemptAlloc(x)
#   define attemptckrealloc(x,y) Tcl_AttemptRealloc(x,y)
#   define Tcl_InitMemory(x)
#   define Tcl_DumpActiveMemory(x)
#   define Tcl_ValidateAllMemory(x,y)

#endif /* !TCL_MEM_DEBUG */

/*
 * struct Tcl_ChannelType:
 *
 * One such structure exists for each type (kind) of channel.
 * It collects together in one place all the functions that are
 * part of the specific channel type.
 *
 * It is recommend that the Tcl_Channel* functions are used to access
 * elements of this structure, instead of direct accessing.
 */
typedef struct Tcl_ChannelType {
    char *typeName;			/* The name of the channel type in Tcl
                                         * commands. This storage is owned by
                                         * channel type. */
    Tcl_ChannelTypeVersion version;	/* Version of the channel type. */
    Tcl_DriverCloseProc *closeProc;	/* Procedure to call to close the
					 * channel, or TCL_CLOSE2PROC if the
					 * close2Proc should be used
					 * instead. */
    Tcl_DriverInputProc *inputProc;	/* Procedure to call for input
					 * on channel. */
    Tcl_DriverOutputProc *outputProc;	/* Procedure to call for output
					 * on channel. */
    Tcl_DriverSeekProc *seekProc;	/* Procedure to call to seek
					 * on the channel. May be NULL. */
    Tcl_DriverSetOptionProc *setOptionProc;
					/* Set an option on a channel. */
    Tcl_DriverGetOptionProc *getOptionProc;
					/* Get an option from a channel. */
    Tcl_DriverWatchProc *watchProc;	/* Set up the notifier to watch
					 * for events on this channel. */
    Tcl_DriverGetHandleProc *getHandleProc;
					/* Get an OS handle from the channel
					 * or NULL if not supported. */
    Tcl_DriverClose2Proc *close2Proc;	/* Procedure to call to close the
					 * channel if the device supports
					 * closing the read & write sides
					 * independently. */
    Tcl_DriverBlockModeProc *blockModeProc;
					/* Set blocking mode for the
					 * raw channel. May be NULL. */
    /*
     * Only valid in TCL_CHANNEL_VERSION_2 channels or later
     */
    Tcl_DriverFlushProc *flushProc;	/* Procedure to call to flush a
					 * channel. May be NULL. */
    Tcl_DriverHandlerProc *handlerProc;	/* Procedure to call to handle a
					 * channel event.  This will be passed
					 * up the stacked channel chain. */
    /*
     * Only valid in TCL_CHANNEL_VERSION_3 channels or later
     */
    Tcl_DriverWideSeekProc *wideSeekProc;
					/* Procedure to call to seek
					 * on the channel which can
					 * handle 64-bit offsets. May be
					 * NULL, and must be NULL if
					 * seekProc is NULL. */
} Tcl_ChannelType;

/*
 * The following flags determine whether the blockModeProc above should
 * set the channel into blocking or nonblocking mode. They are passed
 * as arguments to the blockModeProc procedure in the above structure.
 */
#define TCL_MODE_BLOCKING 0		/* Put channel into blocking mode. */
#define TCL_MODE_NONBLOCKING 1		/* Put channel into nonblocking
					 * mode. */

/*
 * Enum for different types of file paths.
 */
typedef enum Tcl_PathType {
    TCL_PATH_ABSOLUTE,
    TCL_PATH_RELATIVE,
    TCL_PATH_VOLUME_RELATIVE
} Tcl_PathType;


/* 
 * The following structure is used to pass glob type data amongst
 * the various glob routines and Tcl_FSMatchInDirectory.
 */
typedef struct Tcl_GlobTypeData {
    /* Corresponds to bcdpfls as in 'find -t' */
    int type;
    /* Corresponds to file permissions */
    int perm;
    /* Acceptable mac type */
    Tcl_Obj* macType;
    /* Acceptable mac creator */
    Tcl_Obj* macCreator;
} Tcl_GlobTypeData;

/*
 * type and permission definitions for glob command
 */
#define TCL_GLOB_TYPE_BLOCK		(1<<0)
#define TCL_GLOB_TYPE_CHAR		(1<<1)
#define TCL_GLOB_TYPE_DIR		(1<<2)
#define TCL_GLOB_TYPE_PIPE		(1<<3)
#define TCL_GLOB_TYPE_FILE		(1<<4)
#define TCL_GLOB_TYPE_LINK		(1<<5)
#define TCL_GLOB_TYPE_SOCK		(1<<6)
#define TCL_GLOB_TYPE_MOUNT		(1<<7)

#define TCL_GLOB_PERM_RONLY		(1<<0)
#define TCL_GLOB_PERM_HIDDEN		(1<<1)
#define TCL_GLOB_PERM_R			(1<<2)
#define TCL_GLOB_PERM_W			(1<<3)
#define TCL_GLOB_PERM_X			(1<<4)


/*
 * Typedefs for the various filesystem operations:
 */
typedef int (Tcl_FSStatProc) _ANSI_ARGS_((Tcl_Obj *pathPtr, Tcl_StatBuf *buf));
typedef int (Tcl_FSAccessProc) _ANSI_ARGS_((Tcl_Obj *pathPtr, int mode));
typedef Tcl_Channel (Tcl_FSOpenFileChannelProc) 
	_ANSI_ARGS_((Tcl_Interp *interp, Tcl_Obj *pathPtr, 
	int mode, int permissions));
typedef int (Tcl_FSMatchInDirectoryProc) _ANSI_ARGS_((Tcl_Interp* interp, 
	Tcl_Obj *result, Tcl_Obj *pathPtr, CONST char *pattern, 
	Tcl_GlobTypeData * types));
typedef Tcl_Obj* (Tcl_FSGetCwdProc) _ANSI_ARGS_((Tcl_Interp *interp));
typedef int (Tcl_FSChdirProc) _ANSI_ARGS_((Tcl_Obj *pathPtr));
typedef int (Tcl_FSLstatProc) _ANSI_ARGS_((Tcl_Obj *pathPtr, 
					   Tcl_StatBuf *buf));
typedef int (Tcl_FSCreateDirectoryProc) _ANSI_ARGS_((Tcl_Obj *pathPtr));
typedef int (Tcl_FSDeleteFileProc) _ANSI_ARGS_((Tcl_Obj *pathPtr));
typedef int (Tcl_FSCopyDirectoryProc) _ANSI_ARGS_((Tcl_Obj *srcPathPtr,
	   Tcl_Obj *destPathPtr, Tcl_Obj **errorPtr));
typedef int (Tcl_FSCopyFileProc) _ANSI_ARGS_((Tcl_Obj *srcPathPtr,
			    Tcl_Obj *destPathPtr));
typedef int (Tcl_FSRemoveDirectoryProc) _ANSI_ARGS_((Tcl_Obj *pathPtr,
			    int recursive, Tcl_Obj **errorPtr));
typedef int (Tcl_FSRenameFileProc) _ANSI_ARGS_((Tcl_Obj *srcPathPtr,
			    Tcl_Obj *destPathPtr));
typedef void (Tcl_FSUnloadFileProc) _ANSI_ARGS_((Tcl_LoadHandle loadHandle));
typedef Tcl_Obj* (Tcl_FSListVolumesProc) _ANSI_ARGS_((void));
/* We have to declare the utime structure here. */
struct utimbuf;
typedef int (Tcl_FSUtimeProc) _ANSI_ARGS_((Tcl_Obj *pathPtr, 
					   struct utimbuf *tval));
typedef int (Tcl_FSNormalizePathProc) _ANSI_ARGS_((Tcl_Interp *interp, 
			 Tcl_Obj *pathPtr, int nextCheckpoint));
typedef int (Tcl_FSFileAttrsGetProc) _ANSI_ARGS_((Tcl_Interp *interp,
			    int index, Tcl_Obj *pathPtr,
			    Tcl_Obj **objPtrRef));
typedef CONST char** (Tcl_FSFileAttrStringsProc) _ANSI_ARGS_((Tcl_Obj *pathPtr, 
			    Tcl_Obj** objPtrRef));
typedef int (Tcl_FSFileAttrsSetProc) _ANSI_ARGS_((Tcl_Interp *interp,
			    int index, Tcl_Obj *pathPtr,
			    Tcl_Obj *objPtr));
typedef Tcl_Obj* (Tcl_FSLinkProc) _ANSI_ARGS_((Tcl_Obj *pathPtr, 
					       Tcl_Obj *toPtr, int linkType));
typedef int (Tcl_FSLoadFileProc) _ANSI_ARGS_((Tcl_Interp * interp, 
			    Tcl_Obj *pathPtr,
			    Tcl_LoadHandle *handlePtr,
			    Tcl_FSUnloadFileProc **unloadProcPtr));
typedef int (Tcl_FSPathInFilesystemProc) _ANSI_ARGS_((Tcl_Obj *pathPtr, 
			    ClientData *clientDataPtr));
typedef Tcl_Obj* (Tcl_FSFilesystemPathTypeProc) 
			    _ANSI_ARGS_((Tcl_Obj *pathPtr));
typedef Tcl_Obj* (Tcl_FSFilesystemSeparatorProc) 
			    _ANSI_ARGS_((Tcl_Obj *pathPtr));
typedef void (Tcl_FSFreeInternalRepProc) _ANSI_ARGS_((ClientData clientData));
typedef ClientData (Tcl_FSDupInternalRepProc) 
			    _ANSI_ARGS_((ClientData clientData));
typedef Tcl_Obj* (Tcl_FSInternalToNormalizedProc) 
			    _ANSI_ARGS_((ClientData clientData));
typedef ClientData (Tcl_FSCreateInternalRepProc) _ANSI_ARGS_((Tcl_Obj *pathPtr));

typedef struct Tcl_FSVersion_ *Tcl_FSVersion;

/*
 *----------------------------------------------------------------
 * Data structures related to hooking into the filesystem
 *----------------------------------------------------------------
 */

/*
 * Filesystem version tag.  This was introduced in 8.4.
 */
#define TCL_FILESYSTEM_VERSION_1	((Tcl_FSVersion) 0x1)

/*
 * struct Tcl_Filesystem:
 *
 * One such structure exists for each type (kind) of filesystem.
 * It collects together in one place all the functions that are
 * part of the specific filesystem.  Tcl always accesses the
 * filesystem through one of these structures.
 * 
 * Not all entries need be non-NULL; any which are NULL are simply
 * ignored.  However, a complete filesystem should provide all of
 * these functions.  The explanations in the structure show
 * the importance of each function.
 */

typedef struct Tcl_Filesystem {
    CONST char *typeName;   /* The name of the filesystem. */
    int structureLength;    /* Length of this structure, so future
			     * binary compatibility can be assured. */
    Tcl_FSVersion version;  
			    /* Version of the filesystem type. */
    Tcl_FSPathInFilesystemProc *pathInFilesystemProc;
			    /* Function to check whether a path is in 
			     * this filesystem.  This is the most
			     * important filesystem procedure. */
    Tcl_FSDupInternalRepProc *dupInternalRepProc;
			    /* Function to duplicate internal fs rep.  May
			     * be NULL (but then fs is less efficient). */ 
    Tcl_FSFreeInternalRepProc *freeInternalRepProc;
			    /* Function to free internal fs rep.  Must
			     * be implemented, if internal representations
			     * need freeing, otherwise it can be NULL. */ 
    Tcl_FSInternalToNormalizedProc *internalToNormalizedProc;
			    /* Function to convert internal representation
			     * to a normalized path.  Only required if
			     * the fs creates pure path objects with no
			     * string/path representation. */
    Tcl_FSCreateInternalRepProc *createInternalRepProc;
			    /* Function to create a filesystem-specific
			     * internal representation.  May be NULL
			     * if paths have no internal representation, 
			     * or if the Tcl_FSPathInFilesystemProc
			     * for this filesystem always immediately 
			     * creates an internal representation for 
			     * paths it accepts. */
    Tcl_FSNormalizePathProc *normalizePathProc;       
			    /* Function to normalize a path.  Should
			     * be implemented for all filesystems
			     * which can have multiple string 
			     * representations for the same path 
			     * object. */
    Tcl_FSFilesystemPathTypeProc *filesystemPathTypeProc;
			    /* Function to determine the type of a 
			     * path in this filesystem.  May be NULL. */
    Tcl_FSFilesystemSeparatorProc *filesystemSeparatorProc;
			    /* Function to return the separator 
			     * character(s) for this filesystem.  Must
			     * be implemented. */
    Tcl_FSStatProc *statProc; 
			    /* 
			     * Function to process a 'Tcl_FSStat()'
			     * call.  Must be implemented for any
			     * reasonable filesystem.
			     */
    Tcl_FSAccessProc *accessProc;	    
			    /* 
			     * Function to process a 'Tcl_FSAccess()'
			     * call.  Must be implemented for any
			     * reasonable filesystem.
			     */
    Tcl_FSOpenFileChannelProc *openFileChannelProc; 
			    /* 
			     * Function to process a
			     * 'Tcl_FSOpenFileChannel()' call.  Must be
			     * implemented for any reasonable
			     * filesystem.
			     */
    Tcl_FSMatchInDirectoryProc *matchInDirectoryProc;  
			    /* Function to process a 
			     * 'Tcl_FSMatchInDirectory()'.  If not
			     * implemented, then glob and recursive
			     * copy functionality will be lacking in
			     * the filesystem. */
    Tcl_FSUtimeProc *utimeProc;       
			    /* Function to process a 
			     * 'Tcl_FSUtime()' call.  Required to
			     * allow setting (not reading) of times 
			     * with 'file mtime', 'file atime' and
			     * the open-r/open-w/fcopy implementation
			     * of 'file copy'. */
    Tcl_FSLinkProc *linkProc; 
			    /* Function to process a 
			     * 'Tcl_FSLink()' call.  Should be
			     * implemented only if the filesystem supports
			     * links (reading or creating). */
    Tcl_FSListVolumesProc *listVolumesProc;	    
			    /* Function to list any filesystem volumes 
			     * added by this filesystem.  Should be
			     * implemented only if the filesystem adds
			     * volumes at the head of the filesystem. */
    Tcl_FSFileAttrStringsProc *fileAttrStringsProc;
			    /* Function to list all attributes strings 
			     * which are valid for this filesystem.  
			     * If not implemented the filesystem will
			     * not support the 'file attributes' command.
			     * This allows arbitrary additional information
			     * to be attached to files in the filesystem. */
    Tcl_FSFileAttrsGetProc *fileAttrsGetProc;
			    /* Function to process a 
			     * 'Tcl_FSFileAttrsGet()' call, used by
			     * 'file attributes'. */
    Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
			    /* Function to process a 
			     * 'Tcl_FSFileAttrsSet()' call, used by
			     * 'file attributes'.  */
    Tcl_FSCreateDirectoryProc *createDirectoryProc;	    
			    /* Function to process a 
			     * 'Tcl_FSCreateDirectory()' call. Should
			     * be implemented unless the FS is
			     * read-only. */
    Tcl_FSRemoveDirectoryProc *removeDirectoryProc;	    
			    /* Function to process a 
			     * 'Tcl_FSRemoveDirectory()' call. Should
			     * be implemented unless the FS is
			     * read-only. */
    Tcl_FSDeleteFileProc *deleteFileProc;	    
			    /* Function to process a 
			     * 'Tcl_FSDeleteFile()' call.  Should
			     * be implemented unless the FS is
			     * read-only. */
    Tcl_FSCopyFileProc *copyFileProc; 
			    /* Function to process a 
			     * 'Tcl_FSCopyFile()' call.  If not
			     * implemented Tcl will fall back
			     * on open-r, open-w and fcopy as
			     * a copying mechanism, for copying
			     * actions initiated in Tcl (not C). */
    Tcl_FSRenameFileProc *renameFileProc;	    
			    /* Function to process a 
			     * 'Tcl_FSRenameFile()' call.  If not
			     * implemented, Tcl will fall back on
			     * a copy and delete mechanism, for 
			     * rename actions initiated in Tcl (not C). */
    Tcl_FSCopyDirectoryProc *copyDirectoryProc;	    
			    /* Function to process a 
			     * 'Tcl_FSC