Home

Libraries

Author

Links

---

System: Operating System Dependent Facilities
[SysToMath Base C Library]

Collaboration diagram for System: Operating System Dependent Facilities:

---

Detailed Description

Offer operating system dependent facilities with an operating system independent interface for console input, system time, process handling, threading, thread and process synchronization.

Files
file	system.h
	Specification of operating system dependent facilities.
Modules
	Abstract Data Type StmOnce
	A StmOnce object provides a thread safe means to initialize data once.
	Abstract Data Type StmProcessSemaphore
	A StmProcessSemaphore object provides a counting semaphore serving as synchronization primitive between the threads of the calling processes.
	Abstract Data Type StmSemaphore
	A StmSemaphore object provides a named counting semaphore serving as synchronization primitive between the threads of one or more processes.
	Abstract Data Type Family StmSharedMemory<ItemType>
	StmSharedMemory<ItemType> is an abstract data type for named shared memory objects of abstract data type ItemType.
	Abstract Data Type StmMutex
	A StmMutex object provides a means to protect resources used by several threads of the calling process by mutual exclusively locking the object.
	Abstract Data Type StmNamedMutex
	A StmNamedMutex object provides a means to protect resources used by the threads of several processes by mutual exclusively locking the object.
	Abstract Data Type StmCondition
	A StmCondition object is a synchronization primitive used to cause a thread to wait until a particular shared-data condition (or time) is met by another thread of the calling process.
	Abstract Data Type StmNamedCondition
	A StmNamedCondition object is a synchronization primitive used to cause a thread to wait until a particular shared-data condition (or time) is met by another thread of an arbitrary process.
	Abstract Data Type StmThread
	The abstract data type StmThread represents threads of execution, and provides the functionality to create and manage such threads.
	Abstract Data Type StmThreadSpecific
	StmThreadSpecific is an abstract data type for thread-specific items represented as void pointers.
Enumerations
enum	StmSystemFlags {   StmNoSystemFlag = 0x0000,   StmAttachExisting = 0x0010,   StmAttachCreated = 0x0020,   StmAttach = StmAttachExisting | StmAttachCreated,   StmAttachMask = StmAttach,   StmKeepLocked = 0x0040 }
	Definition of the system flags describing the conditions for attaching an underlying sytem object to a StmSemaphore, StmNamedMutex or named shared memory object and if a shared memory object shall keep locked after its creation. More...
Functions
int	stmGetkey (int fd)
	Read one character in raw mode without echoing and return it.
StmInt64	stmGetMsTime (void)
	Return the number of milliseconds elapsed since the Epoch (1970-01-01).
StmInt64	stmGetMsCount (void)
	Return the number of milliseconds elapsed since the very first call.
void	stmSleepMs (StmDword msecs)
	Suspend the calling thread for msecs milliseconds.
int	stmAtExit (void(*routine)(void))
	Register a function to run at process termination.
pid_t	stmProcessSpawn (const char *path, char *const argv[], StmBool usePath)
	Create and execute a new process asynchronously.
int	stmProcessWait (pid_t pid, int *result)
	Wait for the termination of a process.

---

Enumeration Type Documentation

enum StmSystemFlags

Definition of the system flags describing the conditions for attaching an underlying sytem object to a StmSemaphore, StmNamedMutex or named shared memory object and if a shared memory object shall keep locked after its creation.

The enumerators of the enumeration StmSystemFlags are bitwise orable.

See also:

stmSemaphoreCreate(), stmNamedMutexCreate(), stmSharedMemorySampleItemTypeCreate().

Enumerator:

StmNoSystemFlag	No system flag.
StmAttachExisting	Attach an underlying system object, if it exists.
StmAttachCreated	Attach an underlying system object, if it was created.
StmAttach	Attach an underlying system object, if it exists or was created.
StmAttachMask	Mask for all attach flags.
StmKeepLocked	Keep a shared memory object locked after its creation.

Definition at line 525 of file system.h.

---

Function Documentation

int stmGetkey

(

int

fd

)

Read one character in raw mode without echoing and return it.

Parameters:

[in]

fd

Descriptor of the file to be read from.

Effects:

Read one character from fd. Also on terminals reading occurs without echo in raw mode.

Note:

On Windows the file descriptor fd must correspond to the file stream stdin.

Returns:

The character read on success.

-1 on error. Then the variable errno contains the error's cause.

StmInt64 stmGetMsTime

(

void

)

Return the number of milliseconds elapsed since the Epoch (1970-01-01).

Returns:

The number of milliseconds elapsed since 00:00:00 UTC on January 1, 1970.

-1 on error. Then the variable errno contains the error's cause.

Examples:

conditiontest.c, namedconditiontest.c, and semaphoretest.c.

Referenced by handler(), and main().

StmInt64 stmGetMsCount

(

void

)

Return the number of milliseconds elapsed since the very first call.

Returns:

The number of milliseconds elapsed since the very first call of this function on success.

-1 on error. Then the variable errno contains the error's cause.

void stmSleepMs

(

StmDword

msecs

)

Suspend the calling thread for msecs milliseconds.

Parameters:

[in]

msecs

Number of milliseconds to sleep.

Effects:

Suspends the calling thread for msecs milliseconds. If msecs is 0, the current thread yields the processor.

Examples:

namedmutextest.c, sharedmemorytest.c, and systemuniquetest.c.

Referenced by main().

int stmAtExit

(

void(*)(void)

routine

)

Register a function to run at process termination.

Parameters:

[in]

routine

Address of the function to register.

Effects:

The function registers the function pointed to by routine, to be called without arguments at normal program termination. At normal program termination, all functions registered by the stmAtExit() function are called, in the reverse order of their registration.

Note:

This function is intended to behave as the Posix function atexit(). In contrast to atexit() also for Windows DLLs, the functions registered are called by ExitProcess() before all still running threads are terminated.

Returns:

0 on success.

-1 on error. Then the variable errno contains the error's cause.

pid_t stmProcessSpawn	(	const char *	path,
		char *const	argv[],
		StmBool	usePath
	)

Create and execute a new process asynchronously.

Parameters:

[in]	path	File system path to the command to execute. If usePath is StmTrue and path contains no path separator, the environment variable PATH is used to locate the command to execute.
[in]	argv	Array of character pointers to null-terminated strings. The last member of this array shall be NULL. These strings constitute the argument list available to the new process image. The value in argv[0] should point to a filename that is associated with the process image being started by the function.
[in]	usePath	If StmTrue and path contains no path separator, the environment variable PATH is used to locate the command to execute.

Effects:

The function functions creates a new process designated by path. The new process is started asynchronously according to argv inheriting the environment settings of the calling process. After spawning the new process, the function returns.

Returns:

The process ID of the spawned process on success.

(pid_t) -1 on error. Then the variable errno contains the error's cause.

See also:

stmProcessWait().

Examples:

namedconditiontest.c, namedmutextest.c, semaphoretest.c, sharedmemorytest.c, and systemuniquetest.c.

Referenced by main().

int stmProcessWait	(	pid_t	pid,
		int *	result
	)

Wait for the termination of a process.

Parameters:

[in]	pid	The process ID of the process to be waited.
[out]	result	If not NULL, the address of a variable for the exit status of the process.

Effects:

The calling thread blocks until the process designated by pid has terminated.

Returns:

0 on success.

-1 on error. Then the variable errno contains the error's cause.

See also:

stmProcessSpawn().

Examples:

namedconditiontest.c, namedmutextest.c, sharedmemorytest.c, and systemuniquetest.c.

Referenced by main().

---

© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).