3.2 Routines E-F


EC()

void	EC(line); This macro defines a line of code that will only be compiled into the  error-checking version of the geode. The *line* parameter of the macro is the  actual line of code. When the EC version of the program is compiled, the line  will be treated as a normal line of code; when the non-EC version is compiled,  the line will be ignored.

EC_BOUNDS()

void	EC_BOUNDS(addr); This macro adds an address check to the error-checking version of a program.  When the EC version of the program is compiled, the address check will be  included; when the non-EC version is compiled, the address check will be left  out. The *addr* parameter is the address or pointer to be checked.

The macro expands to a call to ECCheckBounds() on the specified address or pointer. If the address is out of bounds, the program will stop with a call to FatalError().

See Also: ECCheckBounds()


EC_ERROR()

void	EC_ERROR(code); This macro inserts a call to **FatalError()** in the error-checking version of the  program and does nothing to the non-EC version. When the program gets to  this point, it will halt and put up an error message corresponding to the  specified error *code*. If a condition should be checked before calling  **FatalError()**, you can use EC_ERROR_IF() instead.

EC_ERROR_IF()

void	EC_ERROR_IF(test, code); This macro inserts a conditional call to **FatalError()** in the error-checking  version of a program; it does nothing for the non-EC version. The *test*  parameter is a Boolean value that, if *true*, will cause the **FatalError()** call  to be made. If test is *false*, **FatalError()** will not be called.

EC_WARNING()

EC_WARNING(word warningCode); This macro generates a warning for the debugger when executed by  error-checking code; it has no effect when in non-EC code.

Include: ec.h


EC_WARNING_IF()

EC_WARNING_IF(<expr>, word warningCode) When this macro is executed in error-checking code, it tests <*expr*>; if  <*expr*>  is non-zero, it generates a warning with code *warningCode* for the debugger.

In non-EC code, the macro has no effect (and <expr> is not evaluated).

Include: ec.h


ECCheckBounds()

void	ECCheckBounds(
		void	*address); This routine checks to see if the given pointer is within bounds of the block  into which it points. If assertions fail, a fatal error will occur.

Include: ec.h


ECCheckChunkArray()

void	ECCheckChunkArray(
		optr	o); This routine checks the validity of the specified chunk array. If the assertions  fail, a fatal error will occur.

Include: ec.h


ECCheckChunkArrayHandles()

void	ECCheckChunkArrayHandles(
		MemHandle mh,
		ChunkHandle ch); This routine checks the validity of the specified chunk array. If the assertions  fail, a fatal error will occur.

Include: ec.h


ECCheckClass()

void	ECCheckClass(
		ClassStruct *class); This routine checks that the given pointer actually references a class  definition. If the assertions fail, a fatal error will occur.

Include: ec.h


ECCheckDriverHandle()

void	ECCheckDriverHandle(
		GeodeHandle gh); This routine checks that the passed handle actually references a driver. If the  assertions fail, a fatal error will occur.

Include: ec.h


ECCheckEventHandle()

void	ECCheckEventHandle(
		EventHandle eh); This routine checks that the passed handle actually references a stored  message. If the assertions fail, a fatal error will occur.

Include: ec.h


ECCheckFileHandle()

void	ECCheckFileHandle(
		FileHandle file); This routine checks that the passed handle actually is a file handle and  references a file. If the assertions fail, a fatal error will occur.

Include: ec.h


ECCheckGeodeHandle()

void	ECCheckGeodeHandle(
		GeodeHandle gh); This routine checks that the passed handle references a loaded geode. If the  assertions fail, a fatal error will occur.

Include: ec.h


ECCheckGStateHandle()

void	ECCheckGStateHandle(
		GStateHandle gsh); This routine checks that the passed handle references a GState. If the  assertions fail, a fatal error will occur.

Include: ec.h


ECCheckHugeArray()

void	ECCheckHugeArray(
		VMFileHandle		vmFile,
		VMBlockHandle		vmBlock); This routine checks the validity of the passed Huge Array. If the block passed  is not the directory block of a Huge Array, the routine fails.

Include: ec.h


ECCheckLibraryHandle()

void	ECCheckLibraryHandle(
		GeodeHandle gh); This routine checks that the passed handle references a library. If the  assertions fail, a fatal error will occur.

Include: ec.h


ECCheckLMemChunk()

void	ECCheckLMemChunk(
		void * chunkPtr); This routine checks the validity of the chunk pointed to by *chunkPtr*. If the  assertions fail, a fatal error will occur.

Include: ec.h


ECCheckLMemHandle()

void	ECCheckLMemHandle(
		MemHandle mh); This routine checks that the passed handle is a memory handle and actually  references a local memory block. If the assertions fail, a fatal error will occur.

Include: ec.h


ECCheckLMemHandleNS()

void	ECCheckLMemHandleNS(
		MemHandle mh); This routine checks that the passed handle is a local memory handle; unlike  **ECCheckLMemHandle()**, however, it does not check sharing violations  (when threads are illegally using non-sharable memory). If the assertions  fail, a fatal error will occur.

Include: ec.h


ECCheckLMemObject()

void	ECCheckLMemObject(
		optr	obj); This routine checks the validity of an object to ensure that it is an object  stored in an object block. If the assertions fail, a fatal error will occur.

Include: ec.h


ECCheckLMemObjectHandles()

void	ECCheckLMemObjectHandles(
		MemHandle mh,
		ChunkHandle ch); This routine checks the validity of an object to ensure that it is an object  stored in an object block. If the assertions fail, a fatal error will occur.

Include: ec.h


ECCheckLMemOD()

void	ECCheckLMemOD(
		optr	o); This routine checks the validity of the given local-memory-based object. If  assertions fail, a fatal error will occur.

Include: ec.h


ECCheckLMemODHandles()

void	ECCheckLMemODHandles(
		MemHandle objHan,
		ChunkHandle objCh); This routine checks the validity of the given local-memory-based object. If  assertions fail, a fatal error will occur.

Include: ec.h


ECCheckMemHandle()

void	ECCheckMemHandle(
		MemHandle mh); This routine checks that the passed handle is a memory handle that  references a memory block. If the assertions fail, a fatal error will occur.

Include: ec.h


ECCheckMemHandleNS()

void	ECCheckMemHandleNS(
		MemHandle mh); This routine checks that the passed handle references a memory block;  unlike **ECCheckMemHandle()**, however, it will not check for sharing  violations (when a thread illegally accesses a non-sharable block). If the  assertions fail, a fatal error will occur.

Include: ec.h


ECCheckObject()

void	ECCheckObject(
		optr	obj); This routine checks the validity of the given locked object. If the assertions  fail, a fatal error will occur.

Include: ec.h


ECCheckObjectHandles()

void	ECCheckObjectHandles(
		Memhandle mh,
		ChunkHandle ch); This routine checks the validity of the given locked object. If the assertions  fail, a fatal error will occur.

ECCheckOD()

void	ECCheckOD(
		optr	obj); This routine checks the validity of the given object. Unlike  **ECCheckLMemObject()**, however, it allows optrs of Process objects to be  specified. If assertions fail, a fatal error will occur.

ECCheckODHandles()

void	ECCheckODHandles(
		MemHandle objHan,
		ChunkHandle objCh); This routine checks the validity of the given object. Unlike  **ECCheckLMemObjectHandles()**, however, it allows processes to be  specified. If assertions fail, a fatal error will occur.

Include: ec.h


ECCheckProcessHandle()

void	ECCheckProcessHandle(
		GeodeHandle gh); This routine checks that the passed handle actually references a process. If  the assertions fail, a fatal error will occur.

Include: ec.h


ECCheckQueueHandle()

void	ECCheckQueueHandle(
		QueueHandle qh); This routine ensures the passed handle references an event queue. If the  assertions fail, a fatal error will occur.

Include: ec.h


ECCheckResourceHandle()

void	ECCheckResourceHandle(
		MemHandle mh); This routine ensures that the passed handle references a geode resource. If  the assertions fail, a fatal error will occur.

Include: ec.h


ECCheckStack()

void	ECCheckStack(); This routine checks to make sure the current stack has not overflown (and is  not about to). This routine also enforces a 100-byte gap between the stack  bottom and the stack pointer. If assertions fail, a fatal error will occur.

Include: ec.h


ECCheckThreadHandle()

void	ECCheckThreadHandle(
		ThreadHandle th); This routine checks that the passed handle actually references a thread. If  the assertions fail, a fatal error will occur.

Include: ec.h


ECCheckWindowHandle()

void	ECCheckWindowHandle(
		WindowHandle wh); This routine checks that the passed handle actually references a window. If  the assertions fail, a fatal error will occur.

Include: ec.h


ECLMemExists()

void	ECLMemExists(
		optr	o); This routine checks to see if the specified chunk exists. This routine should  be called by applications to check the chunk handle's validity. If the  assertions fail, a fatal error will occur.

Include: ec.h


ECLMemExistsHandles()

void	ECLMemExistsHandles(
		MemHandle mh,
		ChunkHandle ch); This routine checks to see if the specified chunk exists. This routine should  be called by applications to check the chunk handle's validity. If the  assertions fail, a fatal error will occur.

Include: ec.h


ECLMemValidateHandle()

void	ECLMemValidateHandle(
		optr	o); This routine checks that the passed optr points to a local memory chunk. If  the assertions fail, a fatal error will occur.

Include: ec.h


ECLMemValidateHandleHandles()

void	ECLMemValidateHandleHandles(
		MemHandle mh,
		ChunkHandle ch); This routine checks that the passed memory and chunk handles actually  reference a local memory chunk. If the assertions fail, a fatal error will occur.

Include: ec.h


ECLMemValidateHeap()

void	ECLMemValidateHeap(
		MemHandle mh); This routine does a complete error-check of the LMem heap. It is used  internally and should not be needed by application programmers.

Include: ec.h


ECMemVerifyHeap()

void	ECMemVerifyHeap() This routine makes sure the global heap is in a consistent state. If the  assertions fail, a fatal error will occur. This routine should likely not be called  by anything other than the EC kernel.

Include: ec.h


ECVMCheckMemHandle()

void	ECVMCheckMemHandle(
		MemHandle han); This routine checks that the given memory handle is actually linked to a VM  block handle. If assertions fail, a fatal error will occur.

Include: ec.h


ECVMCheckVMBlockHandle()

void	ECVMCheckVMBlockHandle(
		VMFileHandle file,
		VMBlockHandle block); This routine checks the validity of the given VM file and block handles. If  assertions fail, a fatal error will occur.

Include: ec.h


ECVMCheckVMFile()

void	ECVMCheckVMFile(
	VMFileHandle file); This routine checks the validity of the given VM file handle. If assertions fail,  a fatal error will occur.

Include: ec.h


ElementArrayAddElement ()

word	ElementArrayAddElement(
		optr	arr,			/* Handle of element array */
		void *	element,		/* Element to add (if necessary) */
		dword	callBackData,	/* This is passed to the Callback routine */
		Boolean _pascal (*callback) (void *elementToAdd, 
					void *elementFromArray, dword valueForCallback)); This routine is used to add elements to an array. It is passed the address of a  potential element. It compares the element with each member of an element  array. If there are no matches, it adds the element to the array and sets the  reference count to one. If there is a match, it increments the reference count  of the matching element in the array and returns; it does not add the new  element. When you pass the address of an element, make sure you pass the  address of the data portion of the element (not the reference-count header).

You can pass a callback routine to ElementArrayAddElement(). ElementArrayAddElement() will call the callback routine to compare elements and see if they match. The callback routine should be declared _pascal. ElementArrayAddElement() passes the callback routine the address of the element you passed it, as well as the address of the data-portion of the element in the array (the part after the RefElementHeader structure). If the two elements match (by whatever criteria you use), return true; otherwise, return false. If you pass a null function pointer, the default comparison routine will be called, which checks to see if every data byte matches.

Include: chunkarr.h

Tips and Tricks: If you know the element is already in the array, you can increment its reference count by calling ElementArrayAddReference().

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayAddReference()


ElementArrayAddElementHandles()

word	ElementArrayAddElementHandles(
		MemHandle		mh,				/* Global handle of LMem heap */
		ChunkHandle		chunk			/* Chunk handle of element array */
		void *			element,		/* Element to add */
		dword			callBackData,	/* Passed to the Callback routine */
		Boolean _pascal (*callback) (void *elementToAdd, 
					void *elementFromArray, dword valueForCallback)); This routine is exactly like **ElementArrayAddElement()** above, except  that the element array is specified by its global and chunk handles (instead  of with an optr).

Include: chunkarr.h

Tips and Tricks: If you know the element is already in the array, you can increment its reference count by calling ElementArrayAddReferenceHandles().

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayAddReferenceHandles()


ElementArrayAddReference()

void	ElementArrayAddReference(
		optr	arr,		/* optr to element array */
		word	token);		/* Index number of element */ This routine increments the reference count of a member of an element array. 

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayAddElement()


ElementArrayAddReferenceHandles()

void	ElementArrayAddReferenceHandles(
		MemHandle		mh,			/* Handle of LMem heap's block */
		ChunkHandle		ch,			/* Handle of element array */
		word			token);		/* Index number of element */ This routine is exactly like **ElementArrayAddReference()** above, except  that the element array is specified by its global and chunk handles (instead  of with an optr).

Include: chunkarr.h


ElementArrayCreate()

ChunkHandle ElementArrayCreate(
		MemHandle	mh,				/* Handle of LMem heap's block */
		word		elementSize,	/* Size of each element, or zero
									 * for variable-sized */
		word		headerSize);	/* Header size (zero for default) */ This routine creates an element array in the indicated LMem heap. It creates  an **ElementArrayHeader** structure at the head of the chunk. If you want  to leave extra space before the start of the array, you can pass a larger header  size; if you want to use the standard header, pass a header size of zero.

You can specify the size of each element. Remember that the first three bytes of every element in an element array are the element’s RefElementHeader; structure, which contains the reference count; leave room for this when you choose a size. For arrays with variable-sized elements, pass a size of zero.

Include: chunkarr.h

Tips and Tricks: You may want to declare a structure for array elements; the first component should be a RefElementHeader. You can pass the size of this structure to ElementArrayCreate().

If you want extra space after the ElementArrayHeader, you may want to create your own header structure, the first element of which is an ElementArrayHeader. You can pass the size of this header to ElementArrayCreate(), and access the data in your header via the structure.

Be Sure To: Lock the block on the global heap before calling this routine (unless it is fixed). If you pass a header size, make sure it is larger than sizeof(ElementArrayHeader).


ElementArrayCreateAt

ChunkHandle 	ElementArrayCreateAt(
		optr	arr,			/* optr of chunk for array */
		word	elementSize,	/* Size of each element, or zero
								 * for variable-sized */
		word	headerSize);	/* Header size (zero for default) */ This routine is just like **ElementArrayCreate()** above, except that the  element array is created in a pre-existing chunk. The contents of that chunk  will be overwritten.

Include: chunkarr.h

Warnings: If the chunk isn’t large enough, it will be resized. This will invalidate all pointers to chunks in that block.


ElementArrayCreateAtHandles

ChunkHandle 	ElementArrayCreateAtHandles(
		MemHandle	mh,				/* Handle of LMem heap */
		ChunkHandle	ch				/* Create array in this chunk */
		word		elementSize,	/* Size of each element, or zero
										 * for variable-sized */
		word		headerSize);	/* Header size (zero for default) */ This routine is exactly like **ElementArrayCreateAt()** above, except that  the element array is specified by its global and chunk handles (instead of  with an optr).

Include: chunkarr.h

Warnings: If the chunk isn’t large enough, it will be resized. This will invalidate all pointers to chunks in that block.


ElementArrayDelete()

void	ElementArrayDelete(
		optr	arr,		/* optr to element array */
		word	token);		/* index of element to delete */ This routine deletes an element from an element array regardless of its  reference count. The routine is passed the element array's optr and the token  for the element to delete.

Note that when an element is removed, it is actually resized down to zero size and added to a list of free elements. That way the index numbers of later elements are preserved.

Include: chunkarr.h

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayRemoveReference()


ElementArrayDeleteHandles()

void	ElementArrayDeleteHandles(
		MemHandle	mh,			/* Handle of LMem heap */
		ChunkHandle	ch,			/* Chunk handle of element array */
		word		token);		/* Index of element delete */ This routine is exactly like **ElementArrayDelete()** above, except that the  element array is specified by its global and chunk handles (instead of with an  optr).

Include: chunkarr.h

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayRemoveReference()


ElementArrayElementChanged()

void	ElementArrayElementChanged(
		optr	arr,				/* optr to element array */
		word	token,				/* Index number of element */
		dword	callbackData,		/* This is passed along to callback */
		Boolean _pascal (*callback)	/* Returns true if elements identical */
					(void *		elementChanged,
					 void *		elementToCompare,
					 dword		valueForCallback));

This routine checks to see if an element is identical to any other elements in the same element array. This is used after an element has changed to see if it now matches another element. If the element matches another, it will be deleted, and the other element will have its reference count incremented.

The routine is passed an optr to the element array, the token of the element which is being checked, a dword of data (which is passed to the callback routine), and a pointer to a callback comparison routine. The callback routine itself is passed pointers to two elements and the callbackData argument passed to ElementArrayElementChanged(). The callback routine should be declared _pascal. If the two elements are identical, the callback should return true (i.e. non-zero); otherwise, it should return false.

If you pass a null function pointer, ElementArrayElementChanged() will do a bytewise comparison of the elements.

Include: chunkarr.h


ElementArrayElementChangedHandles()

void	ElementArrayElementChangedHandles(
		MemHandle		memHandle,		/* Handle of LMem heap's block */
		ChunkHandle		chunkHandle,	/* Chunk handle of element array */
		word			token,			/* Index number of element */
		dword			callbackData,	/* This is passed along to
										 * callback */
		Boolean _pascal (*callback)		/* Returns true if elements identical */
						(void *		elementChanged,
						 void *		elementToCompare,
						 dword		valueForCallback)); This routine is exactly like **ElementArrayElementChanged()** above,  except that the element array is specified by its global and chunk handles  (instead of with an optr).

Include: chunkarr.h


ElementArrayGetUsedCount()

word	ElementArrayGetUsedCount(
		optr	arr,			/* optr to element array */
		dword	callbackData,			/* This is passed to callback routine */
		Boolean _pascal (*callback)				/* return true to count this element */
					(void * element, dword cbData)); This routine counts the number of active elements in an element array; that  is, elements which have a reference count of one or greater. It can be  instructed to count every element, or every element which matches certain  criteria. The routine is passed three parameters: the optr of the chunk array,  a dword which is passed to the callback routine, and a callback routine which  determines whether the element should be counted. The callback  routine,which should be declared _pascal, is passed the dword an a pointer  to an element. It should return *true* if the element should be counted;  otherwise, it should return *false*. To count every element, pass a null callback  pointer.

Include: chunkarr.h

See Also: ElementArrayTokenToUsedIndex(), ElementArrayUsedIndexToToken()


ElementArrayGetUsedCountHandles()

void	ElementArrayGetUsedCountHandles(
		MemHandle 	mh,				/* Handle of LMem heap's block */
		ChunkHandle	ch,				/* Chunk handle of element array */
		dword		callbackData,	/* This is passed to callback routine */
		Boolean _pascal (*callback)	/* return true to count this element */
					(void * element, dword cbData)); This routine is exactly like **ElementArrayGetUsedCount()** above, except  that the element array is specified by its global and chunk handles (instead  of with an optr).

Include: chunkarr.h


ElementArrayRemoveReference()

void	ElementArrayRemoveReference(
		optr	arr,			/* optr of element array */
		word	token,			/* Index of element to unreference */
		dword	callbackData,	/* Passed to callback routine */
		void _pascal (*callback) (void *element, dword valueForCallback));
				/* Routine is called if element is actually removed */ This routine decrements the reference count of the specified element. If the  reference count drops to zero, the element will be removed. If an element is  to be removed, **ElementArrayRemoveReference()** calls the callback  routine on that element. The callback routine should perform any cleanup  necessary; it is passed a pointer to the element and the *callbackData*  argument. If you pass a null function pointer, no callback routine will be  called.

Note that when an element is removed, it is actually resized down to zero size and added to a list of free elements. That way the index numbers of later elements are preserved.

Be Sure To: Lock the block on the global heap before calling (unless it is fixed).

See Also: ElementArrayDelete()

Include: chunkarr.h


ElementArrayRemoveReferenceHandles()

void	ElementArrayRemoveReferenceHandles(
		MemHandle	mh,				/* Handle of LMem heap */
		ChunkHandle	ch,				/* Chunk handle of element array */
		word		token,			/* Index of element to unreference */
		dword		callbackData,	/* Passed to callback routine */
		void _pascal (*callback) (void *element, dword valueForCallback));
				/* Routine is called if element is actually removed */ This routine is exactly like **ElementArrayRemoveReference()** above,  except that the element array is specified by its global and chunk handles  (instead of with an optr).

Include: chunkarr.h


ElementArrayTokenToUsedIndex()

word	ElementArrayTokenToUsedIndex(
		optr	arr,				/* Handle of element array */
		word	token,				/* Index of element to unreference */
		dword	callbackData,		/* Data passed to callback routine */
		Boolean _pascal (*callback)	/* Return true to count this element */
				(void *element, dword cbData)); This routine is passed the token of an element array. It translates the token  into an index from some non-standard indexing scheme. The indexing  scheme can either number the elements from zero, counting only those  elements in use (i.e. those with a reference count greater than zero); or it can  use a more restrictive scheme. If a callback routine is passed, the callback  routine will be called for every used element; it should be declared _pascal  and return *true* if the element should be counted. If a null callback pointer is  passed, every used element will be counted.

Include: chunkarr.h


ElementArrayTokenToUsedIndexHandles()

word	ElementArrayTokenToUsedIndexHandles(
		MemHandle 	mh,				/* Handle of LMem heap */
		ChunkHandle ch,				/* Chunk handle of element array */
		word		token,			/* Index of element to unreference */
		dword		callbackData,	/* Data passed to the
									 * callback routine */
		Boolean _pascal (*callback)	/* Return true to count this element */
				(void *element, dword cbData)); This routine is exactly like **ElementArrayTokenToUsedIndex()** above,  except that the element array is specified by its global and chunk handles  (instead of with an optr).

Include: chunkarr.h


ElementArrayUsedIndexToToken()

word	ElementArrayUsedIndexToToken(
		optr	arr,				/* optr to element array */
		word	index,				/* Find token of element with this index */
		dword	callbackData,		/* This is passed to the callback routine */
		Boolean _pascal (*callback)	/* Return true to count this element */
				(void *element, dword cbData)); This routine takes an index into an element array from some non-standard  indexing scheme. The routine finds the element specified and returns the  element's token. The indexing scheme can either number the elements from  zero, counting only those elements in use (i.e. those with a reference count  greater than zero); or it can use a more restrictive scheme. If a callback  routine is passed, the callback routine will be called for every used element;  it should should be declared _pascal return *true* if the element should be  counted. If a null callback pointer is passed, every used element will be  counted.

If no matching element is found, ElementArrayUsedIndexToToken() returns CA_NULL_ELEMENT.

Include: chunkarr.h


ElementArrayUsedIndexToTokenHandles()

word	ElementArrayUsedIndexToTokenHandles(
		MemHandle 	mh,				/* Handle of LMem heap's block */
		ChunkHandle 	ch,			/* Handle of element array */
		word		index,			/* Find token of element with this index */
		dword		callbackData,	/* Data passed to the callback routine */
		Boolean _pascal (*callback)	/* Return true to count this element */
				(void *element, dword cbData)); This routine is exactly like **ElementArrayUsedIndexToToken()** above,  except that the element array is specified by its global and chunk handles  (instead of with an optr).

Include: chunkarr.h


EvalExpression()

int	EvalExpression(
		byte	* tokenBuffer,		/* Pointer to the parsed expression */
		byte	* scratchBuffer,	/* Pointer to the base of a scratch buffer
									 * consisting of two stacks: an argument
									 * stack and an operator/function stack */
		byte	* resultsBuffer,	/* Pointer to a buffer to contain the
									 * result of the evaluation */
		word	bufSize,			/* Size of the scratch buffer */
		CEvalStruct * evalParams);	/* Pointer to CEvalStruct structure */ This routine evaluates a stream of parser tokens. It is used by the evaluator  portion of the parse library and will be used only rarely by applications.

Include: parse.h


FatalError()

void	FatalError(
		word errorCode); This routine causes a fatal error, leaving *errorCode* for the debugger.

FileClose()

word 	FileClose( /* returns error */
		FileHandle	fh,				/* File to close */
		Boolean		noErrorFlag);	/* Set if app. can't handle
									 * errors */ This routine closes an open byte file. If the routine succeeds, it returns zero.  If the routine fails and *noErrorFlag* is *false* (i.e., zero), **FileClose()** returns a  member of the **FileError** enumerated type. If the routine fails and  *noErrorFlag* is *true* (i.e., non-zero), the routine will fatal-error.

Warnings: The noErrorFlag parameter should be true only during debugging.

Include: file.h


FileCommit()

word	FileCommit( /* returns error */
		FileHandle	fh,
		Boolean		noErrorFlag);	/* set if can't handle errors */ **FileCommit()** forces the file system to write any cached information about  a file to the disk immediately. If it is successful, it returns zero. If it fails, it  returns an error code. If the routine fails and *noErrorFlag* is *true* (i.e.  non-zero), the routine will fatal-error.

Warnings: The noErrorFlag parameter should be true only during debugging.

Include: file.h


FileConstructFullPath()

DiskHandle 	FileConstructFullPath(
		char		* * buffer,		/* Path string is written here */
		word		bufSize,		/* Length of buffer (in bytes) */
		DiskHandle	disk,			/* Disk or standard path; null for 
									 * current path */
		const char	* tail,			/* Path relative to handle */
		Boolean		addDriveLetter);	/* Should path begin with drive
										 * name? */ This routine translates a GEOS directory specification into a complete path  string. It writes the string into the passed buffer. The directory is specified  by two arguments: The first, *disk*, is the handle of a disk; this may also be a  standard path constant. (If a null handle is passed, the current working  directory is used.) The second, *tail*, is a pointer to the character string  representing the tail end of the path. **FileConstructFullPath()** appends  this relative path to the location indicated by the disk handle. It then  constructs a full path string, beginning with that disk's root directory, and  writes it to the buffer passed. If *addDriveName* is *true* (i.e. non-zero), the  path string will begin with the drive's name and a colon.

Examples: The following call to FileConstructFullPath() might yield these results:


Code Display 6-1 Sample call to FileConstructFullPath()

/* Here we find out the full path of a subdirectory of the DOCUMENT directory */

	DiskHandle	documentDisk;
	char		pathBuffer[256];	/* long enough for most paths */

	documentDisk = FileConstructFullPath(&pathBuffer,	/* pointer to pointer */
				256, 			/* Length of buffer */
				SP_DOCUMENT,	/* This can be a disk or 
								 * standard path */
				"MEMOS\\JANUARY", /* In C strings, the
								   * backslash must be
								   * doubled */
				TRUE);			/* Prepend drive name */

/* If the standard paths are set up in the default configuration, "documentDisk"
 * would be the handle of the main hard drive, and pathBuffer would contain a
 * string like "C:\GEOWORKS\DOCUMENT\MEMOS\JANUARY" */

See Also: FileParseStandardPath()

Include: file.h


FileCopy()

word	FileCopy( /* returns error */
		const char	* source,		/* Source path and file name */
		const char	* dest,			/* Destination path and file name */
		DiskHandle	sourceDisk,		/* These handles may be Standard */
		DiskHandle	destDisk);		/* Path constants, or null to indi- 
									 * cate current working directory */ This routine makes a copy of a file. The source and destination are specified  with path strings. Each string specifies a path relative to the location  specified by the corresponding disk handle. If the handle is a disk handle, the  path is relative to that disk's root. If the disk handle is a standard path  constant, the path string is relative to that standard path. If the disk handle  is null, the path is relative to the current working directory.

If FileCopy() is successful, it returns zero. Otherwise, it returns one of the following error codes:

ERROR_FILE_NOT_FOUND
No such source file exists in the specified directory.

ERROR_PATH_NOT_FOUND
An invalid source or destination path string was passed.

ERROR_ACCESS_DENIED
You do not have permission to delete the existing copy of the destination file, or the destination disk or directory is not writable.

ERROR_FILE_IN_USE
Some geode has the existing destination file open.

ERROR_SHORT_READ_WRITE
There was not enough room on the destination disk.

See Also: FileMove()

Include: file.h


FileCreate()

FileHandle 	FileCreate( /* sets thread's error value */
		const char		* name,			/* relative to working directory */
		FileCreateFlags	flags,			/* see below */
		FileAttrs		attributes);	/* FileAttrs of new file */ This routine creates a byte file. The file may be a DOS file or a GEOS byte file.  If the file is successfully opened, **FileCreate()** will return the file's handle;  otherwise, it will return a null handle and set the thread's error value.

The second parameter is a word-length FileCreateFlags record. The lower byte of this field is a FileAccessFlags record. This specifies the file’s permissions and exclusions. Note that you must request write or read/write permission when you create a file. The upper byte specifies how the file should be created. It contains the following possible values:

FILE_CREATE_TRUNCATE
If a file with the given name exists, it should be opened and truncated; that is, all data should be deleted.

FILE_CREATE_NO_TRUNCATE
If the file exists, it should be opened without being truncated.

FILE_CREATE_ONLY
If the file exists, the routine should fail and set the thread’s error value to ERROR_FILE_EXISTS.

FCF_NATIVE
This flag is combined with one of the above flags if the file should be created in the device’s native format; e.g. if it should be a DOS file instead of a GEOS file. The name passed must be an acceptable native file name. If a GEOS file with the specified name already exists, FileCreate() will fail with error condition ERROR_FILE_FORMAT_MISMATCH. Similarly, if the flag isn’t set and a non-GEOS file with this name exists, FileCreate() will fail and return this error.

The third parameter, attributes, describes the FileAttrs record to be set for the new file.

If successful, FileCreate() returns the file’s handle. If it is unsuccessful, it returns a null handle and sets the thread’s error value. The following error values are commonly returned:

ERROR_PATH_NOT_FOUND
A relative or absolute path was passed, and the path included a directory which did not exist.

ERROR_TOO_MANY_OPEN_FILES
There is a limit to how many files may be open at once. If this limit is reached, FileCreate() will fail until a file is closed.

ERROR_ACCESS_DENIED
Either the caller requested access which could not be granted (e.g. it requested write access when another geode had already opened the file with FILE_DENY_W), or the caller tried to deny access when that access had already been granted to another geode (e.g. it tried to open the file with FILE_DENY_W when another geode already had it open for write-access).

ERROR_WRITE_PROTECTED
The caller requested write or read-write access to a file in a write-protected volume.

ERROR_FILE_EXISTS
Returned if FileCreate() was called with FILE_CREATE_ONLY and a file with the specified name already exists.

ERROR_FILE_FORMAT_MISMATCH
Returned if FileCreate() was called with FILE_CREATE_TRUNCATE or FILE_CREATE_NO_TRUNCATE and a file exists in a different format than desired; i.e. you passed FCF_NATIVE and the file already exists in the GEOS format, or vice versa.

Examples: An example of usage is shown below.


Code Display 6-2 Example of FileCreate() usage

/* Here we create a DOS file in the current working directory. If the file already
 * exists, we open the existing file and truncate it.
 */

	FileHandle		newFile;

	newFile = 		FileCreate("NEWFILE.TXT",
					( (FILE_CREATE_TRUNCATE | FCF_NATIVE)
					 | (FILE_ACCESS_RW | FILE_DENY_RW)),
					0); /* set no attribute bits */

See Also: FileCreateTempFile(), FileOpen()

Include: file.h


FileCreateDir()

word	FileCreateDir( /* Returns error & sets thread's error value */
		const char * name);		/* Relative path of new directory */ This routine creates a new directory. The parameter is a path string; the path  is relative to the current directory. The last element of the path string must  be the directory to create.

If FileCreateDir() is successful, it returns zero and clears the thread’s error value. Otherwise, it returns an error code and sets the thread’s error value. The following errors are returned:

ERROR_PATH_NOT_FOUND
The path string was in some way invalid; for example, it might have instructed FileCreateDir() to create the directory within a directory which does not exist.

ERROR_ACCESS_DENIED
The thread is not able to create directories in the specified location, or a directory with the specified name already exists.

ERROR_WRITE_PROTECTED
The volume is write-protected.

See Also: FileDeleteDir()

Include: file.h


FileCreateTempFile()

FileHandle FileCreateTempFile( /* Sets thread's error value */
		char		* dir,		/* directory, relative to working dir.;
								 * file name replaces 14 trailing null
								 * characters upon return */
		FileAttrs	attributes); This routine creates and opens a temporary file in the directory specified. The  routine automatically selects a name for the temporary file. No creation flags  are needed, since the file will definitely be created anew and will be used only  by this geode. The directory string must end with fourteen null bytes (enough  to be replaced by the new file's name).

If FileCreateTempFile() is successful, it returns the file’s handle as well as the string passed in dir, with the trailing null characters replaced by the file name. If it is unsuccessful, it returns a null handle and sets the thread’s error value to a member of the FileError enumerated type.

Tips and Tricks: Temporary files are usually created in a subdirectory of SP_PRIVATE_DATA.

See Also: FileCreate()

Include: file.h


FileDelete()

word	FileDelete( /* returns error */
		const char  * name);   /* path relative to working directory */ This routine deletes a file. If it is successful, it returns zero; otherwise, it  returns a **FileError**. Common errors include:

ERROR_FILE_NOT_FOUND
No such file exists in the specified directory.

ERROR_WRITE_PROTECTED
The volume is write-protected.

ERROR_PATH_NOT_FOUND
An invalid path string was passed.

ERROR_ACCESS_DENIED
You do not have permission to delete that file.

ERROR_FILE_IN_USE
Some geode has that file open.

Include: file.h


FileDeleteDir()

word	FileDeleteDir( /* Returns error & sets thread's error value */
		const char * name);	  /* Relative path of directory to delete */ This argument deletes an existing directory. The parameter is a string which  specifies the directory's position relative to the current working directory.  The last element of the path string must be the name of the directory to  delete.

If FileDeleteDir() is successful, it returns zero and clears the thread’s error value. Otherwise, it returns an error code and sets the thread’s error value. The following errors are returned:

ERROR_PATH_NOT_FOUND
The directory specified could not be found or does not exist.

ERROR_IS_CURRENT_DIRECTORY
This directory is some thread’s current directory, or else it is on some thread’s directory stack.

ERROR_ACCESS_DENIED
The thread does not have permission to delete the directory.

ERROR_WRITE_PROTECTED
The volume is write-protected.

ERROR_DIRECTORY_NOT_EMPTY
The directory specified is not empty. A directory must be empty before it can be deleted.

See Also: FileCreateDir()

Include: file.h


FileDuplicateHandle()

FileHandle FileDuplicateHandle( /* Sets thread's error value */
		FileHandle fh); This routine duplicates the handle of an open file and returns the duplicate  handle. The duplicate handle has the same read/write position as the  original. Both handles will have to be closed for the file to be closed. If there  is an error, **FileDuplicateHandle()** returns a null handle and sets the  thread's error value.

Include: file.h


FileEnum()

word	FileEnum( /* returns number of files returned */
		FileEnumParams	* params,		/* described below */
		MemHandle		* bufCreated,	/* FileEnum will allocate a return-
										 * buffer block & write its handle
										 * here */
		word			* numNoFit);	/* Number of files not handled is
										 * written here */ This routine is used to examine all the files in a directory. The routine can  filter the files by whether they have certain extended attributes. It creates a  buffer and writes information about the files in this buffer. This routine can  be called in many different ways; for full details, see the section "FileEnum()"  in the Concepts book.

Structures: FileEnum() uses several structures and enumerated types. They are shown below; the detailed description of the structures follows.

	/* Types, values, and structures passed
	 * to the FileEnum() routine: */

typedef enum /* word */ {
	FESRT_COUNT_ONLY,
	FESRT_DOS_INFO,
	FESRT_NAME,
	FESRT_NAME_AND_ATTR
} FileEnumStandardReturnType;

typedef enum /* word */ {
	FESC_WILDCARD
} FileEnumStandardCallback;

	/* Types, values, and structures returned
	 * by the FileEnum() routine: */

typedef struct {
	FileAttrs 			DFIS_attributes;
	FileDateAndTime 	DFIS_modTimeDate;
	dword 				DFIS_fileSize;
	FileLongName 		DFIS_name;
	DirPathInfo 		DFIS_pathInfo;
} FEDosInfo;

typedef struct _FileEnumCallbackData {
	FileExtAttrDesc 	FECD_attrs[1];
} FileEnumCallbackData;

typedef struct _FileEnumParams {
	FileEnumSearchFlags 		FEP_searchFlags;
	FileExtAttrDesc *			FEP_returnAttrs;
	word 						FEP_returnSize;
	FileExtAttrDesc *			FEP_matchAttrs;
	word 						FEP_bufSize;
	word 						FEP_skipCount;
	word _pascal (*FEP_callback) (struct _FileEnumParams *params,
							 FileEnumCallbackData *fecd, 
							 word frame);
	FileExtAttrDesc *			FEP_callbackAttrs;
	dword 						FEP_cbData1;
	dword 						FEP_cbData2;
	word 						FEP_headerSize;
} FileEnumParams;

Most of the information passed to FileEnum() is contained in a FileEnumParameters structure. The fields of the structure are as follows:

FEP_searchFlags
This is a byte-length flag field. The flags are of type FileEnumSearchFlags (described below). These flags specify which files at the current location will be examined by FileEnum(). They also specify such things as whether a callback routine should be used.

FEP_returnAttrs
This is a pointer to an array of FileExtAttrDesc structures. The last structure should have its FEA_attr field set to FEA_END_OF_LIST. The array specifies what information will be returned by FileEnum(). The FileExtAttrDesc structure is used in a slightly different way than usual. Every file will have an entry in the return buffer; this entry will contain all the extended attribute information requested. Each FileExtAttrDesc structure will specify where in that entry its information should be written. The FEAD_value field should contain only an offset value; the extended attribute will be written at that offset into the entry. (You can specify an offset by casting an integer value to type void .) The *FEAD_size value specifies how long the return value can be. You can also request certain return values by setting FEP_returnAttrs to equal a member of the FileEnumStandardReturnType (again, by casting the FileEnumStandardReturnType value to type void *). The FileEnumStandardReturnType enumerated type is described later in this section.

FEP_returnSize
This is the size of each entry in the returned buffer. If a standard return type or an array of FileExtAttrDesc structures was passed, each entry in the returned buffer will contain all the extended attribute information requested for that file.

FEP_matchAttrs
This is a pointer to an array of FileExtAttrDesc structures. The last structure should have its FEA_attr field set to FEA_END_OF_LIST. FileEnum() will automatically filter out and ignore all files whose attributes do not match the ones specified by this array. For attributes that are word-sized records, FEAD_value.offset holds the bits that must be set, and FEAD_value.segment holds the bits that must be clear. For byte-sized flags, FEAD_value.offset.low contains the flags that must be set, and FEAD_value.offset.high contains flags that must be clear. Byte- and word-sized non-flag values are stored in FEAD_value.offset. For all other values, FEAD_value holds a pointer to the exact value to match, and FEAD_size specifies the length of that value (in bytes). If you do not want to filter out any files in the working directory, or if you will use the callback routine to filter the files, pass a null pointer in this field.

FEP_bufsize
This specifies the maximum number of entries to be returned in the buffer. If you do not want to set a limit, pass the constant FEP_BUFSIZE_UNLIMITED. The buffer will be grown as necessary.

FEP_skipCount
This contains the number of matching files to be ignored before the first one is processed. It is often used in conjunction with FEP_bufSize to examine many files a few at a time. For example, if you only wanted to examine ten files at a time, you would set FEP_bufSize to ten and FEP_skipCount to zero. FileEnum() would return the data for the first ten files which match the search criteria. After processing the returned data, if there were any files left over, you could call FileEnum() again, this time with FEP_skipCount set to ten; FileEnum() would handle the next ten matching files and return the data about them. In this way you could walk through all the matching files in the directory. Note that if the FileEnumSearchFlags bit FESF_REAL_SKIP is set (in FEP_searchFlags), the first files in the directory will be skipped before they are tested to see if they match. This is faster, since the match condition won’t have to be checked for the first files in the directory.

FEP_callback
This holds a pointer to a Boolean callback routine. The callback routine can check to see if the file matches some other arbitrary criteria. The callback routine is called for any files which match all the above criteria. It should be declared _pascal. It is passed three arguments: a pointer to the FileEnumParams structure, a pointer to the current stack frame (which is used by some assembly callback routines), and a pointer to an array of FileExtAttrDesc structures. These structures are all the attributes required either for return, matching, or callback (see FEP_callbackAttrs below), with the information for the current file filled in; you can search through them directly for the information you want, or you can call FileEnumLocateAttr() to search through this array. If the file should be accepted by FileEnum(), the callback should return true; otherwise it should return false. You can also instruct FileEnum() to use one of the standard callback routines by passing a member of the FileEnumStandardCallback enumerated type. In this case, FEP_callbackAttrs is ignored; FileEnum() will automatically pass the appropriate information to the callback routine. (Note that if the FESF_CALLBACK bit of the FEP_searchFlags field is not set, the FEP_callback field is ignored.)

FEP_callbackAttrs
This is a pointer to an array of FileExtAttrDesc structures. The last structure should have its FEA_attr field set to FEA_END_OF_LIST. The array will be filled in with the appropriate information for each file before the callback routine is called. Note that if the FESF_CALLBACK bit of the FEP_searchFlags is not set, the FEP_callbackAttrs is ignored. If you do not need any attributes passed to the callback routine, set this field to be a null pointer.

FEP_cbData1, FEP_cbData2 These are dword-length fields. Their contents are ignored by FileEnum(); they are used to pass information to the callback routine. If you do not call a standard callback routine, you may use these fields any way you wish.

FEP_headerSize
If the flag FESF_LEAVE_HEADER is set, FileEnum() will leave an empty header space at the beginning of the return buffer. The size of the header is specified by this field. If FESF_LEAVE_HEADER is clear, this field is ignored.

The first field of the FileEnumParams structure, FEP_searchFlags, is a word-length record containing FileEnumSearchFlags. The following flags are available:

FESF_DIRS - Directories should be examined by FileEnum().

FESF_NON_GEOS - Non-GEOS files should be examined by FileEnum().

FESF_GEOS_EXECS - GEOS executable files should be examined by FileEnum().

FESF_GEOS_NON_EXECS - GEOS non-executable files (e.g., VM files) should be examined by FileEnum().

FESF_REAL_SKIP - If a skip count of n is specified, the first n files will be skipped regardless of whether they matched the attributes passed. In this case, FileEnum() will return the number of files passed through in order to get enough files to fill the buffer; the return value can thus be the real-skip count for the next pass.

FESF_CALLBACK - FileEnum() should call a callback routine to determine whether a file should be accepted.

FESF_LOCK_CB_DATA - This flag indicates that the FileEnumParams fields FEP_callback1 and FEP_callback2 are far pointers to movable memory that must be locked before FileEnum() is called.

FESF_LEAVE_HEADER - If set, FileEnum() should leave an empty header space at the start of the return buffer. The size of this buffer is specified by the FEP_headerSize field.

The FileEnumStandardReturnType enumerated type has the following values; they are used in conjunction with the FEP_returnAttrs field of the FileEnumParams structure.

FESRT_COUNT_ONLY - FileEnum() will not allocate any memory and will not return data about files; instead, it will simply return the number of files which match the specified criteria.

FESRT_DOS_INFO - FileEnum() will return an array of FEDosInfo structures. These structures contain basic information about the file: its virtual name, size, modification date, DOS attributes, and path information (as a DirPathInfo record).

FESRT_NAME - FileEnum() will return an array of FileLongName strings, each one of which is FILE_LONGNAME_BUFFER_SIZE characters long; every one of these will contain a file’s virtual name followed by a null terminator.

FESRT_NAME_AND_ATTR - FileEnum() will return an array of FENameAndAttr structures, each one of which contains a file’s DOS attributes and virtual name.

The FEDosInfo structure includes a word-sized record (DFIS_pathInfo) which describes the file’s position relative to the standard paths. It contains the following fields:

DPI_EXISTS_LOCALLY - This bit is set if the file exists in a directory under the primary tree.

DPI_ENTRY_NUMBER_IN_PATH - This is the mask for a seven-bit field whose offset is DPI_ENTRY_NUMBER_IN_PATH_OFFSET.

DPI_STD_PATH - This is the mask for an eight-bit field whose offset is DPI_STD_PATH_OFFSET. If the file is in a standard path, this field will contain a StandardPath constant for a standard path containing the file. This need not be the “closest” standard path; for example, if the file is in the “World” directory, this constant might nevertheless be SP_TOP.

See Also: FileEnumLocateAttr(), FileEnumWildcard()

Include: fileEnum.h


FileEnumLocateAttr()

void *	FileEnumLocateAttr( /* returns NULL if attr not found */
		FileEnumCallbackData*	fecd,	/* Passed to callback routine */
		FileExtendedAttribute	attr,	/* Search for this attribute */
		const char *			* name);	/* Attribute name (if second
											 * argument is FEA_CUSTOM) */ **FileEnum()** can be instructed to call a callback routine to decide which files  to filter out. This callback routine is passed an array of **FileExtAttrDesc**  structures. To find a particular extended attribute in this array, call  **FileEnumLocateAttr()**. This routine will find the address of the value of  the attribute desired, and return that address. If the attribute is not in the  array, **FileEnumLocateAttr()** will return a null pointer.

Include: fileEnum.h


FileEnumWildcard()

Boolean	FileEnumWildcard(
		FileEnumCallbackData	* fecd,		/* Passed to callback routine */
		word					frame);		/* Inherited stack frame */ This routine is a utility used by **FileEnum()** and is rarely used by  applications. It checks to see if the virtual name of the current file (the file  currently being evaluated by **FileEnum()**) matches the pattern in the  *FEP_cbData1* field of the **FileEnumParams** structure.

The fecd parameter is a pointer to the callback data of the FileEnum() routine. The frame parameter is a pointer to the FileEnum() stack frame: The first dword is the FEP_cbData1 field, and the second is the FEP_cbData2 field.

This routine returns true (non-zero) if the file name and pattern match. Otherwise, it returns false.

Include: fileEnum.h


FileFromTransferBlockID()

VMFileHandle	 FileFromTransferBlockID(id);
		TransferBlockID id; This macro extracts a VMFileHandle from a value of type **TransferBlockID**.

FileGetAttributes()

FileAttrs 	FileGetAttributes( /* Sets thread's error value */
		const char * path);		/* file's path relative to current
								 * working directory */

This routine returns the standard FileAttrs attributes for a file. The file may be a GEOS file or a plain DOS file. Note that you can also get a file’s attributes by getting the file’s FEA_FILE_ATTR extended attribute. If an error occurs, this routine sets the thread’s error.

See Also: FileAttrs, FileSetAttributes()

Include: file.h


FileGetCurrentPath()

DiskHandle FileGetCurrentPath(
		char *	buffer,			/* Path string is written here */
		word	bufferSize);	/* Size of buffer in bytes */ This routine writes the current path string (without drive specifier) to the  buffer provided. If the buffer is too small, it truncates the path to fit. It  returns the handle of the disk containing the current path. If the current  path was declared relative to a standard path, the standard path constant  will be returned.

Include: file.h


FileGetDateAndTime()

FileDateAndTime 	FileGetDateAndTime( /* sets thread's error value */
		FileHandle fh); This routine finds out the time a file was last modified. This routine can be  called on GEOS or non-GEOS files. Note that you can also find out the  modification time of a file by checking the extended attribute  FEA_MODIFICATION. If unsuccessful, it sets the thread's error value.

See Also: FileDateAndTime, FileSetDateAndTime()

Include: file.h


FileGetDiskHandle()

DiskHandle FileGetDiskHandle( /* sets thread's error value */
		FileHandle fh); This routine returns the handle of the disk containing an open file. If  unsuccessful, it sets the thread's error value.

Include: file.h


FileGetHandleExtAttributes()

word	FileGetHandleExtAttributes(
		FileHandle				fh,			/* open file's handle */
		FileExtendedAttribute	attr,		/* attribute to get */
		void					* buffer,	/* attribute is written here */
		word					bufSize);	/* length of buffer in bytes */ This routine gets one or more extended attributes of an open file. (To get the  attributes of a file without opening it, call **FileGetPathExtAttributes()**.) If  a single attribute is requested, the attribute will be written in the buffer  passed. If several attributes are requested, *attr* should be set to  FEA_MULTIPLE, and *buffer* should point to an array of **FileExtAttrDesc**  structures. In this case, *bufSize* should be the number of structures in the  buffer, not the length of the buffer. 

If FileGetHandleExtAttributes() is successful, it returns zero. Otherwise, it returns one of the following error codes:

ERROR_ATTR_NOT_SUPPORTED
The file system does not recognize the attribute constant passed.

ERROR_ATTR_SIZE_MISMATCH
The buffer passed was too small for the attribute requested.

ERROR_ATTR_NOT_FOUND
The file does not have a value set for that attribute.

ERROR_ACCESS_DENIED
You do not have read-access to the file.

Tips and Tricks: Note that the only way to recover a custom attribute is by passing FEA_MULTIPLE, and using a FileExtAttrDesc to describe the attribute.

See Also: FileGetPathExtAttributes()

Include: file.h


FileGetPathExtAttributes()

word	FileGetPathExtAttributes(
		const char				* path,		/* path relative to current
											 * working directory */
		FileExtendedAttribute	attr,		/* attribute to get */
		void					* buffer,	/* attribute is written here */
		word					bufSize);	/* length of buffer in bytes */ This routine gets one or more extended attributes of a GEOS file. If a single  attribute is requested, the attribute will be written in the buffer passed. If  several attributes are requested, *attr* should be set to FEA_MULTIPLE, and  *buffer* should point to an array of **FileExtArtrDesc** structures. In this case,  *bufSize* should be the number of structures in the buffer, not the length of the  buffer.

If FileGetPathExtAttributes() is successful, it returns zero. Otherwise, it returns one of the following error codes:

ERROR_ATTR_NOT_SUPPORTED
The file system does not recognize the attribute constant passed.

ERROR_ATTR_SIZE_MISMATCH
The buffer passed was too small for the attribute requested.

ERROR_ATTR_NOT_FOUND
The file does not have a value set for that attribute.

ERROR_ACCESS_DENIED
You do not have read-access to the file.

Tips and Tricks: Note that the only way to recover a custom attribute is by passing FEA_MULTIPLE, and using a FileExtAttrDesc to describe the attribute.

See Also: FileGetHandleExtAttributes()

Include: file.h


FileLockRecord()

word	FileLockRecord( 	/* returns error */
		FileHandle		fh,
		dword			filePos,	/* lock starting at this position... */
		dword			regLength);	/* lock this many bytes */ This routine puts a lock on a part of a byte file. It first checks to make sure  that there are no locks that overlap the region specified; if there are, it will  fail and return ERROR_ALREADY_LOCKED. If there are no locks, it will place  a lock on the region specified and return zero.

Warnings: Locking a region only prevents threads from locking part of the same region; it does not prevent them from reading from or writing to the region. If applications use this mechanism, they have to make sure to call FileLockRecord before trying to access a part of a file.

See Also: FileUnlockRecord(), HandleP()


FileMove()

word	FileMove( /* Returns error */
		const char		* source,	/* source path and file name */
		const char		* dest,		/* destination path and file name */
		DiskHandle		sourceDisk,	/* These handles may be Standard */
		DiskHandle		destDisk);	/* Path constants, or null to indi- 
									 * cate current working directory */ This routine moves a file from one location to another. The source and  destination are specified with path strings. Each string specifies a path  relative to the location specified by the corresponding disk handle. If the  handle is a disk handle, the path is relative to that disk's root. If the disk  handle is a standard path constant, the path string is relative to that  standard path. If the disk handle is null, the path is relative to the current  working directory.

If FileMove() is successful, it returns zero. Otherwise, it returns one of the following error codes and sets the thread’s error value.

ERROR_FILE_NOT_FOUND
No such source file exists in the specified directory.

ERROR_PATH_NOT_FOUND
An invalid source or destination path string was passed.

ERROR_ACCESS_DENIED
You do not have permission to delete the source file, or there is already a file with the same name as the destination file (and you do not have permission to delete it), or the destination disk or directory is not writable.

ERROR_FILE_IN_USE
Either the source file is in use, or there is already a file with the same name as the destination file, and it is in use.

ERROR_SHORT_READ_WRITE
There was not enough room on the destination disk.

See Also: FileCopy()

Include: file.h


FileOpen()

FileHandle FileOpen( /* sets thread's error value */
		const char			* name,		/* relative to working dir */
		FileAccessFlags		flags);		/* Permissions/exclusions */ This routine opens a file for bytewise access. The file may be a DOS file or a  GEOS byte file. If the file is successfully opened, **FileOpen()** will return the  file's handle; otherwise, it will return a null handle and set the thread's error  value. Errors typically set by this routine are listed below:

ERROR_FILE_NOT_FOUND
No file with the specified name could be found in the appropriate directory.

ERROR_PATH_NOT_FOUND
A relative or absolute path had been passed, and the path included a directory which did not exist.

ERROR_TOO_MANY_OPEN_FILES
There is a limit to how many files may be open at once. If this limit is reached, FileOpen() will fail until a file is closed.

ERROR_ACCESS_DENIED
Either the caller requested access which could not be granted (e.g. it requested write access when another geode had already opened the file with FILE_DENY_W), or the caller tried to deny access when that access had already been granted to another geode (e.g. it tried to open the file with FILE_DENY_W when another geode already had it open for write-access).

ERROR_WRITE_PROTECTED
The caller requested write or read-write access to a file in a write-protected volume.

See Also: FileCreate()

Include: file.h


FileParseStandardPath()

StandardPath FileParseStandardPath(
		DiskHandle		disk,
		const char		** path); This routine is passed a full path (relative to the passed disk or a standard  path, if the disk handle is null) and finds the standard path which most  closely contains that path. It updates the pointer whose address is passed so  that it points to the trailing portion of the path string. For example, if you  pass the path string "\GEOWORKS\DOCUMENT\MEMOS\APRIL", the  pointer would be updated to point to the "\MEMOS\APRIL" portion, and the  **StandardPath** SP_DOCUMENT would be returned. If the path passed does  not belong to a standard path, the constant SP_NOT_STANDARD_PATH will  be returned, and the pointer will not be changed.

Include: file.h


FilePopDir()

void	FilePopDir(); **FilePopDir()** pops the top directory off the thread's directory stack and  makes it the current working directory.

See Also: FilePushDir()

Include: file.h


FilePos()

dword	FilePos( /* Sets thread's error value */
		FileHandle		fh,
		dword			posOrOffset,
		FilePosMode		mode); This routine changes the current file position. The position can be specified  in three ways, depending on the value of the *mode* argument:

FILE_POS_START
The file position is set to a specified number of bytes after the start of the file. Passing this mode with an offset of zero will set the file position to the start of the file.

FILE_POS_RELATIVE
The file position is incremented by a specified number of bytes; this number may be negative.

FILE_POS_END
The file position is set to a specified number of bytes after the end of the file; it is usually passed with a negative number of bytes. Passing this mode with an offset of zero will set the file position to the end of the file.

FilePos() returns a 32-bit integer. This integer specifies the absolute file position after the move (relative to the start of the file).

Tips and Tricks: To find out the current file position without changing it, call FilePos() with mode FILE_POS_RELATIVE and offset zero.

Include: file.h


FilePushDir()

void	FilePushDir(); **FilePushDir()** pushes the current working directory onto the thread's  directory stack. It does not change the current working directory.

See Also: FilePopDir()

Include: file.h


FileRead()

word	FileRead( /* sets thread's error value */
		FileHandle		fh,				/* handle of open file */
		void			* buf,			/* copy data to this buffer */
		word			count,			/* Length of buffer (in bytes) */
		Boolean			noErrorFlag);	/* Set if app can't
										 * handle errors */ This routine copies data from a file into memory. It starts copying from the  current position in the file. If possible, it will copy enough data to fill the  buffer. If **FileRead()** reaches the end of the file, it sets the thread's error  value to ERROR_SHORT_READ_WRITE. In any event, it returns the number  of bytes copied. If an error occurs, **FileRead()** returns -1 and sets the  thread's error value (usually to ERROR_ACCESS_DENIED). The current file  position will be changed to the first byte after the ones which were read.

If the argument noErrorFlag is set to true (i.e. non-zero), FileRead() will fatal-error if an error occurs (including an ERROR_SHORT_READ_WRITE).

Warnings: Pass noErrorFlag true only during debugging.

Include: file.h


FileRename()

word	FileRename(
		const char * oldName,		/* Relative to working directory */
		const char * newName);		/* Name only, without path */ This routine changes a file's name. It cannot move a file to a different  directory; to do that, call **FileMove()**. If the routine is successful, it returns  zero; otherwise, it returns a **FileError**. Common errors include

ERROR_FILE_NOT_FOUND
No such file exists in the specified directory.

ERROR_PATH_NOT_FOUND
An invalid path string was passed.

ERROR_ACCESS_DENIED
You do not have permission to delete that file, or it exists on a read-only volume.

ERROR_FILE_IN_US
Some geode has that file open.

ERROR_INVALID_NAME
The name was not a valid GEOS name; or the file is a non-GEOS file, and the name was not an appropriate native name.

See Also: FileMove()

Include: file.h


FileResolveStandardPath()

DiskHandle FileResolveStandardPath(
		char		** buffer,				/* Write path here; update pointer
					 * to point to end of path */
		word		bufSize,				/* Size of buffer (in bytes) */
		const char *		path,				/* Relative path of file */
		FileResolveStandardPathFlags flags);							/* Flags are described below */ This routine finds a file relative to the current location, then writes the full  path to the file, starting at the root of the disk (*not* at a standard path). It  writes the path to the passed buffer, updating the pointer to point to the null  at the end of the path string; it also returns the handle of the disk. If it cannot  find the file it returns a null path.

Structures: A record of FileResolveStandardPathFlags is passed to FileResolveStandardPath(). The following flags are available:

FRSPF_ADD_DRIVE_NAME
The path string written to the buffer should begin with the drive name (e.g., “C:\GEOWORKS\DOCUMENT\MEMOS”).

FRSPF_RETURN_FIRST_DIR
FileResolveStandardPath() should not check whether the passed path actually exists; instead, it should assume that the path exists in the first directory comprising the standard path, and return accordingly.

Include: file.h


FileSetAttributes()

word	FileSetAttributes( /* returns error value */
		const char	* path,		/* file's path relative to current
								 * working directory */
		FileAttrs	attr);		/* new attributes for the file */ This routine changes the standard DOS attributes of a DOS or GEOS file. Note  that you can also change the attributes of a file by setting the extended  attribute FEA_FILE_ATTR.

See Also: FileAttrs, FileGetAttrs()

Include: file.h


FileSetCurrentPath()

DiskHandle FileSetCurrentPath(
		DiskHandle		disk,		/* May be a standard path constant */
		const char		* path);	/* path string, null-terminated */ This routine changes the current path. It is passed two parameters: The first  is the handle of the disk containing the new current path (this may be a  standard path constant). The second is a null-terminated path string. It is  specified with normal DOS conventions: directories are separated by  backslashes; a period (".") indicates the current directory; and a pair of  periods ("..") indicates the parent of the current directory. The string may not  contain wildcard characters.

If disk is a disk handle, the path is relative to the root directory of that disk; if disk is a standard path constant, the path is relative to the standard path; if it is null, the path is relative to the current working directory. FileSetCurrentPath() returns the disk handle associated with the new current path; this may be a standard path constant. If FileSetCurrentPath() fails, it returns a null handle.

Include: file.h


FileSetDateAndTime()

word	FileSetDateAndTime( /* returns error */
		FileHandle			fh,				/* handle of open file */
		FileDateAndTime		dateAndTime);	/* new modification time */ This routine changes a file's last-modification time-stamp. This routine can  be called on GEOS or non-GEOS files. Note that you can also change the  modification time of a file by changing the extended attribute  FEA_MODIFICATION. If unsuccessful, this routine returns an error and sets  the thread's error value.

See Also: FileDateAndTime, FileGetDateAndTime()

Include: file.h


FileSetHandleExtAttributes()

word	FileGetPathExtAttributes( /* returns error */
		FileHandle				fh,			/* handle of open file */
		FileExtendedAttribute	attr,		/* attribute to get */
		const void				* buffer,	/* attribute is read from here */
		word					bufSize);	/* length of buffer in bytes */ This routine sets one or more extended attributes of an open GEOS file. (To  set the attributes of a file without opening it, call  **FileSetPathExtAttributes()**.) If a single attribute is specified, the  attribute's new value will be read from the buffer passed. If several attributes  are to be changed, *attr* should be set to FEA_MULTIPLE, and *buffer* should  point to an array of **FileExtAttrDesc** structures. In this case, *bufSize* should  be the number of structures in the buffer, not the length of the buffer. 

If FileSetHandleExtAttributes() is successful, it returns zero. Otherwise, it sets the thread’s error value and returns one of the following error codes:

ERROR_ATTR_NOT_SUPPORTED
The file system does not recognize the attribute constant passed.

ERROR_ATTR_SIZE_MISMATCH
The buffer passed was the wrong size for the attribute specified.

ERROR_ACCESS_DENIED
The caller does not have write-access to the file.

ERROR_CANNOT_BE_SET
The extended attribute cannot be changed. Such attributes as FEA_SIZE and FEA_NAME cannot be changed with the FileSet…() routines.

Tips and Tricks: Note that the only way to create or change a custom attribute is by passing FEA_MULTIPLE, and using a FileExtAttrDesc to describe the attribute.

See Also: FileSetPathExtAttributes()

Include: file.h


FileSetPathExtAttributes()

word	FileSetPathExtAttributes(
		const char				* path,		/* path relative to current
											 * working directory */
		FileExtendedAttribute	 attr,		/* attribute to get */
		const void				* buffer,	/* attribute is read from here */
		word					bufSize);	/* length of buffer in bytes */ This routine sets one or more extended attributes of a file. If a single  attribute is specified, the attribute will be written in the buffer passed. If  several attributes are to be changed, *attr* should be set to FEA_MULTIPLE  and *buffer* should point to an array of **FileExtAttrDesc** structures. In this  case, *bufSize* should be the number of structures in the buffer, not the length  of the buffer.

If FileSetPathExtAttributes() is successful, it returns zero. Otherwise, it sets the thread’s error value and returns one of the following error codes:

ERROR_ATTR_NOT_SUPPORTED
The file system does not recognize the attribute constant passed.

ERROR_ATTR_SIZE_MISMATCH
The buffer passed was the wrong size for the attribute specified.

ERROR_ACCESS_DENIED
FileSetPathExtAttributes() returns this if any geode (including the caller) has the file open with “deny-write” exclusive access, or if the file is not writable.

ERROR_CANNOT_BE_SET
The extended attribute cannot be changed. Such attributes as FEA_SIZE and FEA_NAME cannot be changed with the FileSet…ExtAttributes() routines.

Tips and Tricks: Note that the only way to create or change a custom attribute is by passing FEA_MULTIPLE, and using a FileExtAttrDesc to describe the attribute.

See Also: FileSetHandleExtAttributes()

Include: file.h


FileSetStandardPath()

void	FileSetStandardPath(
		StandardPath path);			/* StandardPath to set */ This routine changes the current working directory to one of the system's  StandardPath directories. Pass a standard path.

Include: file.h


FileSize()

dword	FileSize(
		FileHandle fh);		/* handle of open file */

This routine returns the size of the open file specified.

Include: file.h


FileTruncate()

word	FileTruncate(
		FileHandle		fh,			/* handle of open file */
		dword			offset);	/* offset at which to truncate */ This routine truncates the specified file at the passed offset. The *offset*  parameter can also be thought of as the desired file size.

Include: file.h


FileUnlockRecord()

word	FileUnlockRecord( /* returns error */
		FileHandle		fh,				/* handle of open file
		dword		filePos,				/* Release lock that starts here */
		dword		regLength);				/* and is this long */ This routine releases a lock on a part of a byte-file. The lock must have been  previously placed with **FileLockRecord()**.

See Also: FileLockRecord(), HandleV()

Include: file.h


FileWrite()

word	FileWrite( /* sets thread's error value */
		FileHandle		fh,				/* handle of open file */
		const void		* buf,			/* Copy from here into file */
		word			count,			/* # of bytes to copy */
		Boolean			noErrorFlag);	/* Set if can't handle errors */ This routine copies a specified number of bytes from a buffer to the file. The  bytes are written starting with the current position in the file; any data  already at that location will be overwritten. **FileWrite()** returns the number  of bytes written. If **FileWrite()** could not write all the data (e.g. if the disk  ran out of space), it will set the thread's error value to  ERROR_SHORT_READ_WRITE and return the number of bytes that were  written. If it could not write the data to the file at all (e.g. if you do not have  write-access to the file), it will return -1 and set the thread's error value to  ERROR_ACCESS_DENIED. In any event, the file position will be changed to  the first byte after the ones written.

If the argument noErrorFlag is set to true (i.e. non-zero), FileWrite() will fatal-error if an error occurs.

Warnings: Pass noErrorFlag true only during debugging.

Include: file.h


FormatIDFromManufacturerAndType

dword	FormatIDFromManufacturerAndType(mfr, type);
		ManufacturerIDs 			mfr;
		ClipboardItemFormat 			type; This macro takes a manufacturer ID and a format type (e.g. CIF_TEXT) and  combines them into a dword argument of the type  **ClipboardItemFormatID**.

free()

void 	free(
		void * blockPtr);		/* address of memory to free */

The malloc() family of routines is provided for Standard C compatibility. The kernel will allocate a fixed block to satisfy the geode’s malloc() requests; it will allocate memory from this block. When the block is filled, it will allocate another fixed malloc-block. When all the memory in the block is freed, the memory manager will automatically free the block.

When a geode is finished with some memory it requested from malloc(), it should free the memory. That makes it easier for malloc() to satisfy memory request. It can free the memory by passing the address which was returned by malloc() (or calloc() or realloc()) when the memory was allocated. All of the memory will be freed.

The memory must be in a malloc-block assigned to the geode calling free(). If you want to free memory in another geode’s malloc-block, call GeoFree().

Include: stdlib.h

Warnings: Pass exactly the same address as the one returned to you when you allocated the memory. If you pass a different address, free() will take unpredictable actions, including possibly erasing other memory or crashing the system.

See Also: calloc(), malloc(), GeoFree(), realloc()


FractionOf()

word	FractionOf(
		WWFixedAsDWord		wwf); This macro returns the fractional portion of a **WWFixedAsDWord** value.

Include: geos.h

Routines A-D <– Table of Contents    –> Routines G-G