Synopsis:
Description:
Notes:
Error codes are maintained on a per-thread basis and can be set and
examined using PIPlatform_getLastError() and PIPlatform_setLastError()
respectively. The following are the error codes used and thier
meanings.
PIAPI_ERROR an unspecified error, use operating system
facilities to further isolate the error.
PIAPI_EXHAUSTED memory or disk space exhausted.
PIAPI_EINVAL invalid parameter
PIAPI_NOTSUPPORTED unimplemented facilitiy
PIAPI_EEXIST a file or other object cannot be created
because some object already exists which
the creation would corrupt.
PIAPI_EACCES access denied
PIAPI_EINIT library not correctly initialised.
PIAPI_DEADLOCK action would leave no runnable threads.
Synopsis:
int PIDLL_delete( PIDLL *pDLL )
Description:
Destroys and free memory associated with the dynamic link object
pDLL.
Notes:
Whether or not the DLL is unloaded from the address space of
the process is implementation specific. Typically a DLL only
becomes unloaded when the load reference count reaches zero.
Return Values:
On success PIDLL_delete() returns zero (PIAPI_COMPLETED).
Errors:
On error PIDLL_delete() returns a negative value.
More specific error information can be retrieved using
PIPlatform_getLastError().
See Also:
PIDLL_new
Synopsis:
void *PIDLL_getAddress( PIDLL *pDLL, const char *pSymbolName )
Description:
Returns the address of symbol pSymbolName is the DLL pDLL.
Notes:
This function is intended primarily for retrieving the address
of functions with "C" linkage.
Return Values:
On success PIDLL_getAddress() returns a pointer to the memory
address of the required symbol.
Errors:
PIDLL_getAddress returns NULL if the address of the function
could not be retrieved.
More specific error information can be retrieved using
PIPlatform_getLastError().
Additionally the PIDLL_getErrorDescription() can be used to get
an english description of the last error.
See Also:
Name:
PIDLL_getErrorDescription
Synopsis:
const char *PIDLL_getErrorDescription( const PIDLL *pDLL )
Description:
Returns an english description of the last error which
occurred when performing a DLL operation.
Notes:
The error message string is allocate by the DLL object and
is invalided by invoking another operation on that DLL or
destroying the DLL object with PIDLL_delete().
Return Values:
PIDLL_getErrorDescription() always returns an error
description.
Errors:
None.
See Also:
Synopsis:
int PIDLL_isLoaded( const PIDLL *pDLL )
Description:
Indicates whether or not a new DLL object actually represents
a loaded dynamic link library.
Notes:
Return Values:
PIDLL_isLoaded() returns either PIAPI_TRUE or PIAPI_FALSE. If
PIAPI_FALSE is returned and no error code is set (see below), the
function PIDLL_getErrorDescription() can be used to get a
text description of the reason the library could not be loaded.
Errors:
On error PIDLL_isLoaded() returns PIAPI_FALSE and sets the
error code to a value other than PIAPI_COMPLETED. This error
code may be retrieved using PIPlatform_getLastError().
See Also:
PIDLL_new
Synopsis:
PIDLL *PIDLL_new( const char *pPath )
Description:
Create a new dynamic link library object by loading the
library pointed to by pPath.
Notes:
Return Values:
On success PIDLL_new returns a pointer to a new dynamic link
library.
Errors:
If pPath is NULL or memory cannot be allocated PIDLL_new() will
return NULL.
More specific error information can be retrieved using
PIPlatform_getLastError().
See Also:
PIDLL_delete
Synopsis:
int PIFInfo_delete( PIFInfo *pFileInfo );
Description:
Destroys an PIFInfo object and free any memory associated with it.
Notes:
Using pFileInfo for any further operations after PIFInfo_delete()
has been used will cause undefined behaviour.
Return Values:
On success PIFInfo_delete() returns zero (PIAPI_COMPLETED).
Errors:
On error PIFInfo_delete() will return a non-zero value. The function
PIPlatform_getLastError() can be used to retreve more specific error
information.
See Also:
PIFInfo_new
Synopsis:
int PIFInfo_exists( PIFInfo *pFileInfo )
Description:
Specifies whether or not the file information object pFileInfo
refers to a file that actually exists.
Notes:
Always compare this return code against PIAPI_TRUE as some
error return value may be non-negative.
Return Values:
On success PIFInfo_exists() returns either PIAPI_TRUE or
PIAPI_FALSE, indicating whether or not a file respresented by
pFileInfo exists.
Errors:
This function does not generate an error.
See Also:
PIFInfo_isRegular PIFInfo_isReadable PIFInfo_isDirectory PIFInfo_isLink
Synopsis:
const char *PIFInfo_getAlternateName( PIFInfo *pFileInfo )
Description:
Returns the alternet name of the file referred to by pFileInfo.
Notes:
Some operating systems maintain alternate filenames for files. This function can be used to access the alternate filename. When the
operating system does not define an alternate file
PIFInfo_getAlternateName() behaves as PIFInfo_getName().
Return Values:
On sucess PIFInfo_getAlternateName() returns a non-NULL pointer to
the alternate filename.
Errors:
On error PIFInfo_getAlternateName() returns NULL. The function
PIPlatform_getLastError() can be used to retrieve more specific
error information.
See Also:
PIFInfo_getPath
Synopsis:
const char *PIFInfo_getExtension( PIFInfo *pFileInfo )
Description:
Returns the extension of the file represented by pFileInfo.
A file extension is the sequence of characters following the
last period ('.') in the filename, when scanning left to right.
Notes:
PIFInfo_getExtension() may operate correctly even when pFileInfo
does not represent a real file.
The returned value is a pointer to a component of the filename
as represented internally in the PIFInfo object. Some functions
such as PIFInfo_delete() will cause this pointer to become
invalid.
Return Values:
On success PIFInfo_getExtension() returns the extension of the
file. If the file does not have an extension this will be
the empty string ("").
Errors:
If pFileInfo is NULL an error occurs PIFInfo_getExtension() returns
NULL.
More specific error information can be retrieved using
PIPlatform_getLastError().
See Also:
PIFInfo_getPath
Name:
PIFInfo_getFirstFileInDirectory
Synopsis:
PIFInfo *PIFInfo_getFirstFileInDirectory( PIFInfo *pFileInfo )
Description:
Returns a new PIFInfo object which contains information about the
first file in the directory referred to by pFileInfo. This object
can be used in subsequent calls to PIFInfo_getNextFileInDirectory() to
iterate through all files in a directory.
Notes:
PIFInfo_getFirstFileInDirectory() allocates a new PIFInfo object,
distinct from pFileInfo which must be seperately destroyed using
PIFInfo_delete().
Return Values:
On success PIFInfo_getFirstFileInDirectory() returns a non-NULL pointer
to a valid PIFInfo object.
Errors:
On error PIFInfo_getFirstFileInDirectory() returns NULL and
PIPlatform_getLastError() can be used to retrieve an error code
indicating the reason for the failure.
See Also:
PIFInfo_getNextFileInDirectory
Synopsis:
PIPLATFORM_TIME PIFInfo_getLastModified( PIFInfo *pFileInfo )
Description:
Gives the time of the last modification to the file specified
by pFileInfo.
Notes:
Time is measured in seconds elapsed since 00:00:00 UTC, Jan. 1, 1970.
Return Values:
On success PIFInfo_getFile() returns the time of the last modification
to the file pFileInfo. On error PIFInfo_getLastModified() returns 0.
Errors:
PIPlatform_getLastError() can be examined to distinguish an error
condition from a file which was last modified at exactly
00:00:00 UTC, Jan. 1, 1970.
See Also:
Synopsis:
const char *PIFInfo_getName( PIFInfo *pFileInfo )
Description:
Returns the name of the file referred to by pFileInfo.
Notes:
Return Values:
On sucess PIFInfo_getName() returns a non-NULL pointer to
the filename.
Errors:
On error PIFInfo_getName() returns NULL. The function
PIPlatform_getLastError() can be used to retrieve more specific
error information.
See Also:
PIFInfo_getPath
Name:
PIFInfo_getNextFileInDirectory
Synopsis:
int PIFInfo_getNextFileInDirectory( PIFInfo *pFileInfo )
Description:
Makes pFileInfo point to the next file in the directory. The object
referred to by pFileInfo must have been created with a call to
PIFInfo_getFirstFileInDirectory().
Notes:
If pFileInfo refers the last file in the directory,
PIFInfo_getNextFileInDirectory() returns PIAPI_FALSE and pFileInfo
does no refer to a valid file.
Return Values:
On success PIFInfo_getNextFileInDirectory() returns PIAPI_TRUE and
pFileInfo points to the next file in the directory. If there
are no other files in the directory or an error occurs
PIFInfo_getNextFileInDirectory() returns PIAPI_FALSE.
The object pFileInfo should be destroy using PIFInfo_delete() when
it is no longer needed.
Errors:
On error PIFInfo_getNextFileInDirectory() returns PIAPI_FALSE and
PIPlatform_getLastError() returns a value other than
PIAPI_COMPLETED indicating which error occurred.
See Also:
PIFInfo_getFirstFileInDirectory
Synopsis:
const char *PIFInfo_getPath( PIFInfo *pFileInfo )
Description:
Returns the full path to the file referred to by pFileInfo.
Notes:
Return Values:
On sucess PIFInfo_getPath() returns a non-NULL pointer to
the files path.
Errors:
On error PIFInfo_getPath() returns NULL. The function
PIPlatform_getLastError() can be used to retrieve more specific
error information.
See Also:
PIFInfo_getName
Synopsis:
const char *PIFInfo_getPathRoot( PIFInfo *pFileInfo )
Description:
Returns the file path to the directory containing the file
referred to by pFileInfo.
Notes:
Return Values:
On sucess PIFInfo_getPathRoot() returns a non-NULL pointer.
Errors:
On error PIFInfo_getPathRoot() returns NULL. The function
PIPlatform_getLastError() can be used to retrieve more specific
error information.
See Also:
PIFInfo_getPathRoot
Synopsis:
PIPLATFORM_FSIZE PIFInfo_getFile( PIFInfo *pFileInfo )
Description:
Specifies the size of the file represented by file information
object pFileInfo.
Notes:
PIPlatform_getLastError() must be used to distinguish an error
condition from a zero length file.
Return Values:
On success PIFInfo_getFile() returns the file size. On failure
PIFInfo_getFile() returns 0.
Errors:
PIPlatform_getLastError() can be examined to distinguish an error
condition from a zero byte file. PIFInfo_getSize() will set the
thread specific error code to PIAPI_COMPLETED before attempting to
get the file size. If PIPlatform_getLastError() returns 0
(PIAPI_COMPLETED) then no error occured. See 'Errors' for a full
description of possible errors.
See Also:
PIFInfo_getExtension
Synopsis:
int PIFInfo_isDirectory( PIFInfo *pFileInfo )
Description:
Specifies whether or not the file information object pFileInfo
refers to a directory.
Notes:
Return Values:
On success PIFInfo_isDirectory() returns either PIAPI_TRUE or
PIAPI_FALSE, indicating whether or not a file respresented by
pFileInfo is a directory.
Errors:
This function does not generate an error.
See Also:
PIFInfo_exists PIFInfo_isRegular PIFInfo_isReadable PIFInfo_isLink
Synopsis:
int PIFInfo_isExecutable( PIFInfo *pFileInfo )
Description:
Specifies whether or not the file information object pFileInfo
refers to a file that may be executed as a program.
Notes:
The execute status of a file is effected by its permissions, the
user privilages of the executing program and the exclusive lock
status of the file.
Return Values:
On success PIFInfo_isExecutable() returns either PIAPI_TRUE or
PIAPI_FALSE, indicating whether or not a file respresented by
pFileInfo may be executed.
Errors:
This function does not generate an error.
See Also:
PIFInfo_exists PIFInfo_isRegular PIFInfo_isReadable PIFInfo_isWritable PIFInfo_isDirectory PIFInfo_isLink
Synopsis:
int PIFInfo_isLink( PIFInfo *pFileInfo )
Description:
Specifies whether or not the file information object pFileInfo
refers to a symbolic link.
Notes:
Return Values:
On success PIFInfo_isLink() returns either PIAPI_TRUE or
PIAPI_FALSE, indicating whether or not a file respresented by
pFileInfo is a symbolic link.
Errors:
This function does not generate an error.
See Also:
PIFInfo_exists PIFInfo_isRegular PIFInfo_isReadable PIFInfo_isDirectory
Synopsis:
int PIFInfo_isReadable( PIFInfo *pFileInfo )
Description:
Specifies whether or not the file information object pFileInfo
refers to a file that may be opened for reading.
Notes:
The readibility of a file is effected by its permissions, the
user privilages of the executing program and the exclusive lock
status of the file.
Return Values:
On success PIFInfo_isReadable() returns either PIAPI_TRUE or
PIAPI_FALSE, indicating whether or not a file respresented by
pFileInfo may be opened for reading.
Errors:
This function does not generate an error.
See Also:
PIFInfo_exists PIFInfo_isRegular PIFInfo_isExecutable PIFInfo_isWritable PIFInfo_isDirectory PIFInfo_isLink
Synopsis:
int PIFInfo_isRegular( PIFInfo *pFileInfo )
Description:
Specifies whether or not the file information object pFileInfo
refers to a file that is a regular file.
Notes:
Directories and symbolic links are some of the valid PIFInfo
objects that are not regular files.
Return Values:
On success PIFInfo_isRegular() returns either PIAPI_TRUE or
PIAPI_FALSE, indicating whether or not a file respresented by
pFileInfo is a regular file.
Errors:
This function does not generate an error.
See Also:
PIFInfo_exists PIFInfo_isReadable PIFInfo_isDirectory PIFInfo_isLink
Synopsis:
int PIFInfo_isWritable( PIFInfo *pFileInfo )
Description:
Specifies whether or not the file information object pFileInfo
refers to a file that may be opened for writting.
Notes:
The readibility of a file is effected by its permissions, the
user privilages of the executing program and the types of locks
held on the file.
Return Values:
On success PIFInfo_isWritable() returns either PIAPI_TRUE or
PIAPI_FALSE, indicating whether or not a file respresented by
pFileInfo may be opened for writting.
Errors:
This function does not generate an error.
See Also:
PIFInfo_exists PIFInfo_isRegular PIFInfo_isReadable PIFInfo_isExecutable PIFInfo_isDirectory PIFInfo_isLink
Synopsis:
PIFInfo *PIFInfo_new( const char *pPath )
Description:
Create a new file information object.
Notes:
This object should be deleted with PIFInfo_delete() when it is
no longer needed.
Return Values:
On success PIFInfo_new() return a pointer to a new PIFInfo object.
Errors:
NULL will be returned if an pPath is NULL or memory could not be
allocated for the new PIFInfo object.
More specific error information can be retrieved using
PIPlatform_getLastError().
See Also:
PIFInfo_delete
Synopsis:
int PIFMap_delete( PIFMap *pMappedFile )
Description:
Destroys and free memory associated with the mapped file object
pMappedFile.
Notes:
Return Values:
On success PIFMap_delete() returns zero (PIAPI_COMPLETED).
Errors:
On error PIFMap_delete() returns a negative value.
More specific error information can be retrieved using
PIPlatform_getLastError().
See Also:
PIFMap_new
Synopsis:
void *PIFMap_lock( PIFMap *pMappedFile, int *piLength )
Description:
Locks a mapped file object in memory and returns a pointer
to the first byte. If piLength is not NULL the length of
the mapped file will be written in the location it points at.
Notes:
PIFMap_lock() maps the file in read only mode. When the address
of the file map is no longer needed the mapped file object should
be unlocked using PIFMap_unlock(). PIFMap_lock() and PIFMap_unlock()
may be invoked any number of times in order.
Return Values:
On success PIFMap_lock() returns a pointer to a memory address where
the file has been mapped.
Errors:
PIFMap_lock() returns NULL if pMappedFile is NULL or an error
occurred.
More specific error information can be retrieved using
PIPlatform_getLastError().
See Also:
PIFMap_unlock
Synopsis:
PIFMap *PIFMap_new( const PIFInfo *pFileInfo )
Description:
Create a new mapped file object to map a file into virtual
memory.
Notes:
The mapped file object should be destroyed using PIFMap_delete()
when it is no longer needed.
Return Values:
On success PIFInfo returns a pointer to a new mapped file object.
Errors:
If pFileInfo is NULL or memory cannot be allocated PIFMap_new() will
return NULL.
More specific error information can be retrieved using
PIPlatform_getLastError().
See Also:
PIFMap_delete
Synopsis:
int PIFMap_unlock( PIFMap *pMappedFile )
Description:
Unlocks the mapped file object pMappedFile. This invalidates any
memory pointer obtained from PIFMap_lock().
Notes:
The use of lock and unlock on a file mapping object allows some operating
systems to more efficiently manage system resources.
It is an error to invoke PIFMap_unlock() on a file mapping object
that has not been locked with PIFMap_lock().
Return Values:
On success PIFMap_unlock() returns zero (PIAPI_COMPLETED).
Errors:
On error PIFMap_unlock() returns a negative value.
More specific error information can be retrieved using
PIPlatform_getLastError().
See Also:
PIFMap_lock
Synopsis:
int PIFile_close( PIPLATFORM_FD tFD )
Description:
Closes a platform specific file descriptor opened by PIFile_open().
Notes:
Return Values:
On success PIFile_delete() returns zero (PIAPI_COMPLETED).
Errors:
On error PIFile_close() does not return PIAPI_COMPLETED. The function
PIPlatform_getLastError() can be used to retrieve more specific
error information.
See Also:
PIFile_open
Synopsis:
PIPLATFORM_FD PIFile_open( const char *pPath, const char *pFlags )
Description:
Open a new platform specific file handle to the file identified
by the path pPath.
The value pFlags is a sequence of characters with the following
meanings. "W" - open file in write mode overwritting any
previous file with the same path. "A" - open the file in write
mode appending to any file with the same path. "R" can be
specified for opening a file for reading. "N" indicates that the
file should not be opened if it already exists (must not alreadu exist).
In all cases
With the exception of when the "N" flag is present,
a new file will be created if the it did not exist.
Flags are not case sensitive.
Notes:
PIPLATFORM_FD, is an operating system specific handle or descriptor,
other operations may be performed on this object by casting this
value to the type associated with operating system specific descriptors
and using system calls.
PIFile_* functions are primarily intented for creating and appended
file optimally with synchronization amoungst write operations from
multiple threads and processes, however they may also be used for
simple unbuffering readonly access to existing files.
The function PIFile_close() should be used to close a file handle when
it is no longer needed. File handles should be considered an
easily exhaustable resource, and omitting to match successful
PIFile_open() calls with calls to PIFile_close() is a serious
resource leak.
Return Values:
The values returned from PIFile_open should be compared with
the PIPLATFORM_FD_INVALID to determine if an error occurred, i.e.
PIPLATFORM_FD tFD;
if ((tFD = PIFile_open( "/tmp/dummy.txt", "w" ))==PIPLATFORM_FD_INVALID)
{
/.* --- handle error --- *./
int iErrorCode = PiPlatform_getLastError();
...
}
else
{
/.* --- tFD is a valid file handle --- *./
...
PIFile_close( tFD );
};
Errors:
More specific error information can be retrieved using
PIPlatform_getLastError().
See Also:
PIFile_close
Synopsis:
int PIFile_write( PIPLATFORM_FD tFD, int iLength, const void *pData )
Description:
Write the data block if Length bytes to the file referenced by
the descriptor tFD.
Notes:
The function PIPlatform_PollFD() may to used yield processing to
another thread if the write operation would block.
Return Values:
On success PIFile_write() returns zero (PIAPI_COMPLETED).
Errors:
On error, the function PIPlatform_getLastError() can be used to get
more specific error information.
See Also:
PIFile_writeAtomic
Synopsis:
int PIFile_writeAtomic( PIPLATFORM_FD tFD, int iLength, const void *pData )
Description:
Write the data block if Length bytes to the file referenced by
the descriptor tFD. The write operation is atomic, meaning that
descriptor will be locked using a platform specific method to ensure
the block of a data is written correctly in an environment where
multiple processes and threads are competing to write to the file.
Notes:
This function will only gaurentee synchronized writes amoungst
processes on POSIX compliant platforms. On other platforms only
thread synchronization is performed.
Return Values:
On success PIFile_writeAtomic() returns zero (PIAPI_COMPLETED).
Errors:
On error, the function PIPlatform_getLastError() can be used to get
more specific error information.
See Also:
PIFile_write
Name:
PIPlatform_advisaryLockFd
Synopsis:
PIPlatform_advisaryLockFd( PIPLATFORM_FD tFD )
Description:
Place an advisary lock on a file descriptor, blocking until the
the lock can be obtained. The blocking is performed in an
efficient manner for the process and thread model beng used.
Notes:
Return Values:
On success PIPlatform_advisaryLockFd() returns zero (PIAPI_COMPLETED).
Errors:
On error, the function PIPlatform_getLastError() can be used to get
more specific error information.
See Also:
PIPlatform_advisaryUnlockFd
Name:
PIPlatform_advisaryUnlockFd
Synopsis:
PIPlatform_advisaryUnlockFd( PIPLATFORM_FD tFD )
Description:
Release an advisary lock from a file descriptor, previously placed
with PIPlatform_advisaryLockFd().
Notes:
Return Values:
On success PIPlatform_advisaryUnlockFd() returns zero (PIAPI_COMPLETED).
Errors:
On error, the function PIPlatform_getLastError() can be used to get
more specific error information.
See Also:
PIPlatform_advisaryLockFd
Name:
PIPlatform_afterUnsafeBlock
Synopsis:
int PIPlatform_afterUnsafeBlock()
Description:
Ends a block protected by reentrance with PIPlatform_beforeUnsafeBlock().
Notes:
Return Values:
Returns 0 on success.
Errors:
On error a non-zero value is returned, the function
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIPlatform_beforeUnsafeBlock
Name:
PIPlatform_allocLocalMutex
Synopsis:
PISync *PIPlatform_allocLocalMutex()
Description:
Returns a new local mutex which can be used to synchronize threads of
control within a process.
Notes:
The synchronization object should be destroyed using PISync_delete() when
it is no longer needed.
Return Values:
Returns a pointer to a new synchronization object or NULL on error.
Errors:
NULL may be returned if a new syncronization object could not be
created due to exhausted memory, kernel mutexes or user mutexes.
More information can be retrieved using PIPlatform_getLastError().
See Also:
PISync_lock PISync_unlock PISync_tryLock PISync_delete
Name:
PIPlatform_allocLocalSemaphore
Synopsis:
PISync *PIPlatform_allocLocalSemaphore( int iInitalCount, int iMaxCount )
Description:
Returns a new local semaphore which can be used to synchronize
threads of control within a process.
Notes:
The synchronization object should be destroyed using PISync_delete() when
it is no longer needed.
Return Values:
Returns a pointer to a new synchronization object or NULL on error.
Errors:
NULL may be returned if a new syncronization object could not be
created due to exhausted memory, kernel semaphores or user semaphores.
More specific error information can be retrieved using
PIPlatform_getLastError().
See Also:
PISync_lock PISync_unlock PISync_tryLock PISync_delete
Name:
PIPlatform_beforeUnsafeBlock
Synopsis:
int PIPlatform_beforeUnsafeBlock()
Description:
Protects reentrance into non-thread safe blocks by blocking on a
semaphore.
Notes:
Calls to PIPlatform_beforeUnsafeBlock() must be matched by calls to
PIPlatform_afterUnsafeBlock().
Return Values:
Returns 0 on success.
Errors:
On error a non-zero value is returned, the function
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIPlatform_afterUnsafeBlock
Name:
PIPlatform_catchExceptions
Synopsis:
void PIPlatform_catchExceptions( void (*)(void *), void * )
Description:
Not yet documented.
Notes:
Return Values:
Errors:
See Also:
Synopsis:
int PIPlatform_enter( const char *pArgv0, int iVersion, PIPlatformFn fn )
Description:
Initializes the platform facilities including user context threads
and custom memory management, then calls the user supplied function
fn. PIPlatform_enter() cleans platform facilities before returning.
Notes:
The parameter pArgv0 should be passed argv[0] from the main() entry
point to the program, as certain implementations of dynamic loading
require this. However this is not essential to the functioning of
most platform functionality and NULL may be passed instead.
The constant PLATFORM_VERSION_1_0 should be used as parameter iVersion
to this function.
A typical use of this function is to invoke it immediately on entering
main() or equivalent function.
The function fn is run in the main thread with initial priority
PITHREAD_PRIORIY_MED.
/* --- globals --- */
int iArgc;
char **ppArgv;
int iRet;
/* --- Main program function --- */
void foo()
{
/* ... */
iRet = 0;
}
/* --- initialize the platform and invoke foo() --- */
int main( int iArgc, char *ppArgv[] )
{
iArgc = iTheArgc;
ppArgv = ppTheArgv;
if ( PIPlatform_enter( ppArgv[0], PLATFORM_VERSION_1_0, foo ) )
{
printf( "Error initializing platform\n" );
return 0;
};
return iRet;
}
Return Values:
PIPlatform_enter() returns zero (PIAPI_COMPLETED) on success.
Errors:
On error PIPlatform_enter() returns a negative value.
More error information can be retrieved using PIPlatform_getLastError().
See Also:
PIPlatform_getDescription
Name:
PIPlatform_getCurrentDirectory
Synopsis:
int PIPlatform_getCurrentDirectory( char *pBuffer, int iMaxLen )
Description:
Retrieve the current directory for the process and write it
into the buffer pBuffer up to iMaxLen characters.
The buffer pBuffer may not be null terminated if the length
of the current directory is greater than or equal to iMaxLen.
Notes:
Return Values:
Returns the length of the current directory. Although no more
than iMaxLen characters will be written into pBuffer,
PIPlatform_getCurrentDirectory() may return a length greater
than iMaxLen.
Errors:
On error PIPlatform_getCurrentDirectory() returns 0.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
Name:
PIPlatform_getDescription
Synopsis:
const char *PIPlatform_getDescription()
Description:
Returns a string which describes the range of operating systems
and machine/processor sets for which this build is compatible.
Notes:
The description is of the form
Operating system ( machine processor )
Return Values:
Returns an internally allocated pointer to a string. The caller should
not modify this string.
Errors:
PIPlatform_getDescription returns NULL if PIPlatform_Init() has not
been called.
More error information can be retrieved using PIPlatform_getLastError().
See Also:
PIPlatform_enter
Synopsis:
int PIPlatform_getLastError()
Description:
Returns the last error code for the current thread.
Notes:
Error codes are only set on error. Except where noted they are
not cleared on success.
Return Values:
PIPlatform_getLastError() always returns the last error code.
Errors:
This function does not generate an error.
See Also:
PIPlatform_setLastError Errors
Synopsis:
int PIPlatform_getProcess()
Description:
Retrieve the platform specific identifier or handle for the current
process.
Notes:
Return Values:
Idenifier or handle of Current process.
Errors:
PIPlatform_getProcess() does not generate errors.
See Also:
PIPlatform_getProcessId
Synopsis:
int PIPlatform_getProcessId()
Description:
Retrieve the platform specific identifier for the current
process.
Notes:
PIPlatform_getProcessId() differs from PIPlatform_getProcess() in that
PIPlatform_getProcessId() always returns an integer process index that
can be used to reference a specific process across all processes.
PIPlatform_getProcess() returns the native reference to a process and
may only be valid within the process space of the current process.
Return Values:
Identifier for the Current process.
Errors:
PIPlatform_getProcessId() does not generate errors.
See Also:
PIPlatform_getProcess
Synopsis:
int PIPlatform_pollFD( PIPLATFORM_FD fd, int iFlags,
int iTimeout )
Description:
Waits for the activity on the specified file descriptor.
The value iFlags is formed by OR'ing together any
combination of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE.
The value piTimeout is a pointer to an integer containing a time to
wait in seconds.
Notes:
A value of PIPLATFORM_NOTIMEOUT for iTimeout specifies no timeout.
A value of PIPLATFORM_NOWAIT for iTimeout specifies that
PIPlatform_pollNetFD() should test for activity on fd but return
immediately even if there is none.
On systems where differences between sockets and file descriptors
are transparent, PIPlatform_pollFD() is implemented using
PIPlatform_pollNetFD(). On other systems PIPlatform_pollFD() may not
be implemented, see below under 'Errors'.
Return Values:
On success PIPlatform_pollFD() returns a value formed by OR'ing
some of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE together
indicating which operations may be performed on file description fd
without blocking.
If the specified timeout period expires, PIPlatform_pollFD() returns
a value of zero.
Errors:
On failure PIPlatform_pollNetFD() returns a negative value.
More specific error information can be retreived using
PIPlatform_getLastError().
On some systems PIPlatform_pollFD() is not yet implemented, in this
case a value of PIAPI_ERROR will be returned and PIPlatform_getLastError()
will return a value of PIAPI_NOTSUPPORTED.
See Also:
PIPlatform_pollNetFD PIPlatform_pollPipeFD PIPlatform_sleep
Synopsis:
int PIPlatform_pollNetFD( PIPLATFORM_NETFD fdSocket, int iFlags,
int iTimeout )
Description:
Waits for the activity on the specified network file descriptor
(socket). The value iFlags is formed by OR'ing together any
combination of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE.
The value piTimeout is a pointer to an integer containing a time to
wait in seconds.
Notes:
A value of PIPLATFORM_NOTIMEOUT for iTimeout specifies no timeout.
A value of PIPLATFORM_NOWAIT for iTimeout specifies that
PIPlatform_pollNetFD() should test for activity on fdSocket but return
immediately even if there is none.
Return Values:
On success PIPlatform_pollNetFD() returns a value formed by OR'ing
some of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE together
indicating which operations may be performed on socket fdSocket
without blocking.
If the specified timeout period expires, PIPlatform_pollNetFD() returns
a value of zero.
Errors:
On failure PIPlatform_pollNetFD() returns a negative value.
More specific error information can be retreived using
PIPlatform_getLastError().
See Also:
PIPlatform_pollFD PIPlatform_pollPipeFD PIPlatform_sleep
Synopsis:
int PIPlatform_pollPipeFD( PIPLATFORM_FD fd, int iFlags,
int iTimeout )
Description:
Waits for activity on the specified pipe.
The value iFlags is formed by OR'ing together any
combination of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE.
The value piTimeout is a pointer to an integer containing a time to
wait in seconds.
Notes:
A value of PIPLATFORM_NOTIMEOUT for iTimeout specifies no timeout.
A value of PIPLATFORM_NOWAIT for iTimeout specifies that
PIPlatform_pollNetFD() should test for activity on fd but return
immediately even if there is none.
On systems where differences between pipes and file descriptors
are transparent, PIPlatform_pollPipeFD() is implemented using
PIPlatform_pollFD(). On other systems PIPlatform_pollPipeFD() may not
be implemented, see below under 'Errors'.
Return Values:
On success PIPlatform_pollPipeFD() returns a value formed by OR'ing
some of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE
together indicating which operations may be performed on
pipe fd without blocking.
If the specified timeout period expires, PIPlatform_pollPipeFD()
returns a value of zero.
Errors:
On failure PIPlatform_pollNetFD() returns a negative value.
More specific error information can be retreived using
PIPlatform_getLastError().
On some systems PIPlatform_pollPipeFD() is not yet implemented, in this
case a value of PIAPI_ERROR will be returned and
PIPlatform_getLastError() will return a value of PIAPI_NOTSUPPORTED.
See Also:
PIPlatform_pollPipeFD IPlatform_pollNetFD PIPlatform_sleep
Synopsis:
void PIPlatform_setLastError( int iErrorCode )
Description:
Set the error code for this thread. Subsequent calls to
PIPlatform_getLastError() will return this error code.
Notes:
Return Values:
PIPlatform_setLastError() does not return a value.
Errors:
This function does not generate an error.
See Also:
PIPlatform_getLastError Errors
Synopsis:
int PIPlatform_sleep( int iMilliseconds )
Description:
Causes the current thread to sleep for at least iMilliseconds
thousandths of a second. The current thread may sleep for longer
than the specified time period. This is particularly true where
user context threads are in use.
Notes:
If user context threads are being used and no other threads are
runnable PIPlatform_sleep() will cause the process to enter a
'tight loop'. This may be expensive on CPU utilization with some
programs.
Return Values:
On success PIPlatform_sleep() returns a value of 0.
Errors:
On failure PIPlatform_sleep() returns a negative value.
PIPlatform_getLastError() returns more specific error information.
See Also:
PIPlatform_pollNetFD PIPlatform_pollFD
Name:
PIPlatform_waitForProcess
Synopsis:
int PIPlatform_waitForProcess( int tProcess, int iFlags, int
iTimeout )
Description:
Cause the current thread to sleep until the process specified by the
operating system specific identifier or handle (tProcess) has
terminated. iFlags is reserved for future use and should always be 0.
iTimeout specifies the maximum time to wait, measured in seconds.
Notes:
The parameter iFlags must be passed the value 0.
Return Values:
Returns PIAPI_COMPLETED on success, PIAPI_TIMEOUT on timeout,
otherwise PIAPI_ERROR.
Errors:
On error PIAPI_ERROR is returned. The function PIPlatform_getLastError()
can be used to retreive more specific error information.
See Also:
Synopsis:
int PISync_delete( PISync *pSync )
Description:
Destroy's a synchronization object.
Notes:
Return Values:
PISync_delete returns zero (PIAPI_COMPLETED) on success.
Errors:
PIAPI_ERROR an error occurred.
PIPlatform_getLastError() can be used to obtain more detailed error
information.
See Also:
PIPlatform_allocLocalMutex PIPlatform_allocLocalSemaphore
Synopsis:
int PISync_lock( PISync *pSync )
Description:
Attempts to grap a mutex resource or increment the count on a
semaphore resource. If the lock cannot be obtained PISync_lock() will
block until it is obtained.
Notes:
The behaviour of PISync_lock depends on the type of the synchronization
object pSync.
PISync_delete() should be used to destroy a synchronization object when
it is no longer needed.
Return Values:
PISync_lock returns zero (PIAPI_COMPLETED) on success.
Errors:
PIAPI_ERROR an error occurred.
PIPlatform_getLastError() can be used to obtain more detailed
error information.
See Also:
PISync_lock PISync_tryLock PISync_unlock
Synopsis:
int PISync_tryLock( PISync *pSync )
Description:
Attempts to grap a mutex resource or increment the count on a
semaphore resource. If the lock cannot be immediately obtained
PISync_lock() will return without blocking.
Notes:
The behaviour of PISync_tryLock depends on the type of the synchronization
object pSync.
PISync_delete() should be used to destroy a synchronization object when
it is no longer needed.
Return Values:
PISync_lock returns zero (PIAPI_COMPLETED) if the lock was obtained or
PIAPI_WOULDBLOCK if the lock could not be obtained.
Errors:
PIAPI_ERROR an error occurred.
PIPlatform_getLastError() can be used to obtain more detailed error
information.
See Also:
PISync_lock PISync_tryLock PISync_unlock
Synopsis:
int PISync_unlock( PISync *pSync )
Description:
Free's a lock that was placed on a mutex synchronization object or
increments the free count of a semaphore synchronization object. This
function removes the lock placed by PISync_lock() or PISync_tryLock().
Notes:
The behaviour of PISync_unlock depends on the type of the synchronization
object pSync.
PISync_delete() should be used to destroy a synchronization object when
it is no longer needed.
Return Values:
PISync_unlock returns zero (PIAPI_COMPLETED) on success.
Errors:
PIAPI_ERROR an error occurred.
PIPlatform_getLastError() can be used to obtain more detailed error
information.
See Also:
PISync_lock PISync_tryLock PISync_unlock
Synopsis:
int PIThread_begin( PIThread *pThread, PIThreadFn fnEntry,
unsigned long ulData, int iPriority, int iFlags )
Description:
Schedules the thread object pThread to be executed. The entry point
function fnEntry will invoked with the argument ulData.
The value iPriority can be one of the thread priority values
described in PIThread_setPriority() and indicates the initial
priority at which the thread runs.
The value of iFlags is formed by OR'ing together zero or more of
the following values:-
PITHREAD_FLAGS_SUSPENDED The thread not run until PIThread_resume()
Notes:
The thread object pThread can be a newly created object from
PIThread_new() or a previously run thread which has terminated.
Return Values:
On success PIThread_begin() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_ERROR if an error occurred.
PIPlatform_getLastError() can be used to obtain more detailed error
information.
See Also:
PIThread_terminate PIThread_waitForThread
Synopsis:
void PIThread_dbgDump( const char *pDumpFile )
Description:
Opens the specified file for write append and writes internal
information on thread status within the program.
If pDumpFile is NULL, information will be written to the stdout stream.
Notes:
This function is mainly for getting verbose information on
thread scheduling when the internal user thread implementation is
being used.
If operating system kernel threads are used this debugging
information will be terse.
Return Values:
PIThread_dbgDump does not return a value.
Errors:
PIThread_dbgDump does not return errors.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
Synopsis:
int PIThread_delete( PIThread *pThread )
Description:
Destroys a thread object, and invalidates the pointer pThread.
Notes:
If pThread has not terminated, PIThread_delete() will kill the thread
and poll for its termination using PIThread_terminate() and
PIThread_waitForThread().
PIThread_delete completely invalidates the pointer pThread, the
results are undefined if the pointer pThread is used in a thread function
again. A defensive use of this function would set pThread to NULL after
PIThread_delete() has been successfully completed.
Return Values:
On success PIThread_delete() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_ERROR if an error occurred.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_new
Name:
PIThread_destroyThreadKey
Synopsis:
int PIThread_destroyThreadKey( int iKey )
Description:
Destroy the thread key (index) iKey. This key can subsequently be
reassigned by PIThread_initThreadKey().
Notes:
Return Values:
On success PIThread_destroyThreadKey() returns zero (PIAPI_COMPLETED).
Errors:
On failure PIThread_destroyThreadKey() returns PIAPI_ERROR.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_initThreadKey
Synopsis:
PIThread *PIThread_getCurrent()
Description:
Returns a pointer to the currently executing thread object.
Notes:
Return Values:
On success PIThread_getCurrent() returns the non-NULL pointer
to the currently executing thread object.
Errors:
NULL if an error occurs.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_getMain
Synopsis:
void *PIThread_getData( PIThread *pThread, int iKey )
Description:
Returns the thread local data for the thread referenced by pThread
at key iKey. This is the value previously set by PIThread_setData() for
this thread and key.
Notes:
All thread local data is zero initialized by PIThread_new().
It is undefined whether using PIThread_terminate() followed by
PIThread_begin() will modify thread local data when used to reuse a
thread.
Return Values:
On success PIThread_getData() returns the thread local data for
this thread object at the specified key and PIPlatform_getLastError()
will return PIAPI_COMPLETED.
Errors:
On error PIThread_getData() will return NULL and PIPlatform_getLastError()
will return a specific error code.
See Also:
PIThread_setData
Synopsis:
PIThread *PIThread_getMain()
Description:
Returns a pointer to the main thread for the process.
Notes:
Return Values:
On success PIThread_getCurrent() returns the non-NULL pointer
to the main thread object.
Errors:
NULL if an error occurs.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_getCurrent
Synopsis:
int PIThread_getPriority( PIThread *pThread, int *piPriority )
Description:
Returns the priority of the thread pThread. piPriority points
to the location where the priority will be written.
Notes:
See PIThread_setPriority() for a description of thread priorities.
Return Values:
On success PIThread_getPriority() write the thread priority into
piPriority and returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_ERROR if an error occurs.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_setPriority
Synopsis:
void *PIThread_getSystemHandle( PIThread *pThread )
Description:
Returns the implementation specific handle or pointer of the the
thread.
This value can be used to reference the thread in additional thread
library functions supplied by the operating system.
Notes:
The value returned by PIThread_getSystemHandle() must be cast to the
appriopriate type e.g. 'thread_t', 'HANDLE'.
Return Values:
On success PIThread_getSystemHandle() returns the specific
operating system handle of the thread.
Errors:
The function PIPlatform_getLastError() must be used to determine
if a handle value of NULL is an error or the valid system
dependant handle of the current thread.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
Synopsis:
int PIThread_initThreadKey()
Description:
Returns a new key (index) that can be used in PIThread_setData() and
PIThread_getData() to save and retrieve thread local data.
Notes:
Return Values:
On success PIThread_initThreadKey() returns a non-negative thread
key.
Errors:
On failure PIThread_initThreadKey() returns a negative number.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_destroyThreadKey
Synopsis:
PIThread *PIThread_new( PIMemoryPool *pPool, int iStackSize )
Description:
Creates and initializes a new thread object. The function PIThread_begin()
can be used to run the thread.
The parameters pPool and iStackSize are for future use but
the values NULL and 0 respectively should be used to ensure
future compatibility.
Notes:
If successful a new thread object will be created but will not
be executed.
The pointer to the thread object remains valid until PIThread_delete() is
called.
Return Values:
On success PIThread_new() returns a pointer to a new
thread object.
Errors:
On error PIThread_new() returns NULL.
PIPlatform_getLastError() can be used to obtain more detailed
error information.
See Also:
PIThread_delete
Synopsis:
int PIThread_resume( pThread )
Description:
Resumes execution of a thread.
Notes:
Return Values:
PIThread_resume() returns zero (PIAPI_COMPLETED) if the thread was
succesfully resumed or if the thread was not suspended.
Errors:
PIAPI_ERROR if an error occurred.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_suspend
Synopsis:
int PIThread_setData( PIThread *pThread, int iKey, void *pData )
Description:
Sets the local data to pData for the thread referenced by pThread
at the key iKey.
Notes:
Return Values:
On success PIThread_setData() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_ERROR if an error occurred.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_getData
Synopsis:
int PIThread_setPriority( PIThread *pThread, int iNewPriority )
Description:
Set the priority of the thread pThread. The following are valid
priority values.
PITHREAD_PRIORITY_LOWEST
PITHREAD_PRIORITY_LOW
PITHREAD_PRIORITY_MED
PITHREAD_PRIORITY_HIGH
PITHREAD_PRIORITY_HIGHEST
Notes:
The precise behaviour of threads and thread priorities varies
greatly across implementations. In general a higher priority
thread will be scheduled before and run for longer than a
lower priority thread. However whether or not a lower priority
thread with be scheduled AT ALL when higher priority threads
are runnable is implementation defined.
The main thread initially runs at priority PITHREAD_PRIORITY_MED.
Return Values:
On success PIThread_setPriority() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_ERROR if an error occurs.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_getPriority
Synopsis:
int PIThread_suspend( PIThread *pThread )
Description:
Suspends execution of the thread pThread.
Notes:
Return Values:
PIThread_suspend() return zero (PIAPI_COMPLETED) if the thread was
succesfully suspended or if the thread had previously been suspended.
Errors:
PIAPI_ERROR if an error occurred.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_resume
Synopsis:
int PIThread_terminate( PIThread *pThread, unsigned long ulExitCode )
Description:
Schedules the specified thread for termination. The thread will exit
with the status code ulExitCode.
Notes:
** IMPORTANT **
Use of this function is not recommended as the target thread will
usually have no opportunity to cleanup critical activity or
synchronized actions it may be performing. This can cause the state
of global objects to become unstable. This is true for user context
threads, and particularly true for some operating system threads
implementations.
PIThread_terminate is not guaranteed to wait for the thread to
terminate. Use the function PIThread_waitForThread() after
PIThread_terminate() to poll for the termination of
another thread.
If pThread is the main thread then the following actions will also
occur in order:-
Return Values:
On success PIThread_terminate returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_ERROR an error occurred.
PIPlatform_getLastError() can be used to get more specific
error information.
See Also:
PIThread_begin PIThread_waitForThread
Synopsis:
int PIThread_userYield()
Description:
Yield processing to another user thread. This function has no
effect when multi-threading is implemented with operating system
specific kernel threads.
When multithreading is implemented with user context threads this
function will behave like PIThread_Yield().
Notes:
Unlike kernel supplied threads (operating system specific)
user context threads will not context switch until a synchronization
function, such as PISync_lock(), PIPlatform_pollNetFD() is invoked. In
code which does not use these synchronization functions (such as
complex mathematical algorithms) one thread would monopolize all the
processing in the application. PIThread_userYield() can be inserted into
such code as a portable way to force preemptive thread behaviour
in a non-preemptive threads environment without added unnecessary
PIThread_Yield() calls to kernel multithreading environments.
Return Values:
On success PIThread_userYield() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_ERROR if an error occurred.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_yield
Synopsis:
int PIThread_waitForThread( PIThread *pThread );
Description:
Suspends execution of the current thread until the thread referenced
by pThread has terminated.
Notes:
PIThread_waitForThread() does not attempt to terminate the thread
referenced by pThread, the function PIThread_terminate() can be used
for that.
Return Values:
PIThread_waitForThread() returns zero (PIAPI_COMPLETED) if the
thread referenced by pThread has terminated.
Errors:
PIAPI_ERROR if an error occurred.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_terminate
Synopsis:
int PIThread_yield()
Description:
Yield processing to another thread.
Notes:
PIThread_waitForThread() does not attempt to terminate the thread
referenced by pThread, the function PIThread_terminate() can be used
for that.
When multithreading is implemented using the kernel threads
implementation of the current operating system with function will
invoke the appropriate theads system call to cause the current
thread to yield.
PIThread_yield() does not guarantee that the current thread will
yield. This is especially true when no other threads of equal or
greater priority are runnable.
Return Values:
On success PIThread_yield() returns zero (PIAPI_COMPLETED).
Errors:
PIAPI_ERROR if an error occurred.
PIPlatform_getLastError() can be used to get more specific error
information.
See Also:
PIThread_userYield
Synopsis:
int PITimer_delete( PITimer *pTimer )
Description:
Destroys a timer object and deallocates memory associated with it.
Notes:
Return Values:
Returns PIAPI_COMPLETED on success.
Errors:
On error PIAPI_ERROR is returned. The function PITimer_getLastError()
returns more specific error information.
See Also:
PITimer_new
Synopsis:
int PITimer_elapsed( PITimer *pTimer, long *plSeconds,
long *plMicroSeconds )
Description:
Returns the number of seconds and microseconds elapsed since the
timer was last reset.
Notes:
If plSeconds is NULL, the number of seconds will not be set.
If plMicroSeconds is NULL, the number of microseconds will not be set.
Return Values:
Returns PIAPI_COMPLETED on success.
Errors:
On error PIAPI_ERROR is returned. The function PITimer_getLastError()
returns more specific error information.
See Also:
PITimer_reset
Synopsis:
PITimer *PITimer_new()
Description:
Allocates and returns a pointer to a new timer object.
Notes:
Timer internals and API functions support microsecond resolution, however,
most operating systems will not support this granularity. Actual
timer resolution is operating system dependant.
Return Values:
Returns a pointer to a new Timer object.
Errors:
On error PITimer_new() returns NULL. The function
PITimer_getLastError() can be used to get more specific
error information.
See Also:
PITimer_delete
Synopsis:
int PITimer_reset( PITimer *pTimer )
Description:
Reset the timer to 0 seconds and 0 microseconds.
Notes:
Return Values:
Returns PIAPI_COMPLETED on success.
Errors:
On error PIAPI_ERROR is returned. The function PITimer_getLastError()
returns more specific error information.
See Also:
PITimer_elapsed
Synopsis:
void PIUtil_free( void *pV )
Description:
Deallocate memory allocated by another function with the PIUtil_
prefix.
Notes:
Return Values:
PIUtil_free() does not return a value.
Errors:
None.
See Also:
PIUtil_malloc
Synopsis:
void *PIUtil_malloc( unsigned long lSize )
Description:
Allocate memory.
Notes:
Memory allocated with PIUtil_malloc() should be freed with
PIUtil_free().
Return Values:
On success this function returns a non-NULL pointer to a memory
area of size equal to or greater than lSize.
Errors:
PIUtil_malloc() returns NULL if the requested memory could not
be allocated.
More error information is available via PIPlatform_getLastError().
See Also:
PIUtil_free
Synopsis:
char *PIUtil_strdup( const char *pS )
Description:
Duplicate a NULL terminated character array.
Notes:
The function PIUtil_free() should be used to deallocate memory
allocated via PIUtil_strdup().
Return Values:
On success PIUtil_strdup returns a copy of the character array
pS.
Errors:
On error PIUtil_strdup() returns NULL.
More information is available via PIPlatform_getLastError().
See Also:
PIUtil_free
Synopsis:
int PIUtil_stricmp( const char *pS1, const char *pS2 )
Description:
Compare two strings without case sensitivity.
Notes:
The result is undefined if either parameter is NULL.
Return Values:
This function returns the following values
> 0 if pS1 is lexigraphically greater than pS2
< 0 if pS2 is lexigraphically greater than pS1
0 if both strings are lexigraphically equivalent
Errors:
There are no error return codes from this function.
See Also:
Synopsis:
int PIUtil_strncmpi( const char *pS1, const char *pS2, int iLen )
Description:
Compare two strings without case sensitivity up to iLen characters.
Notes:
The result is undefined if either parameter is NULL.
Return Values:
This function returns the following values
> 0 if pS1 is lexigraphically greater than pS2
< 0 if pS2 is lexigraphically greater than pS1
0 if both strings are lexigraphically equivalent
Errors:
There are no error return codes from this function.
See Also: