Main Page   Modules  

AtheOS System Calls


Functions

status_t rename_process (int nProcessID, const char *pzName)
 Rename a process. More...

int alloc_tld (void)
 Allocate a TLD slot. More...

int free_tld (int nHandle)
 Release a TLD slot. More...

status_t delete_semaphore (sem_id hSema)
 Delete a kernel semaphore. More...

status_t lock_semaphore_ex (sem_id hSema, int nCount, uint32 nFlags, bigtime_t nTimeOut)
 Aquire a semaphore. More...

status_t lock_semaphore (sem_id hSema, uint32 nFlags, bigtime_t nTimeOut)
 Lock a semaphore. More...

status_t unlock_semaphore_ex (sem_id hSema, int nCount)
 Release a semaphore. More...

status_t unlock_semaphore (sem_id hSema)
 Release a semaphore. More...

int based_open (int nRootFD, const char *pzPath, int nFlags,...)
 Open a file relative to a given directory. More...

int freadlink (int nFile, char *pzBuffer, size_t nBufSize)
 Read the content of an previously opened symlink. More...

void set_tld (int nHandle, int nValue)
 Assign a value to a TLD slot. More...

int get_tld (int nHandle)
 Retrieve the value stored in a TLD. More...

Function Documentation

int alloc_tld ( void )
 

Allocate a TLD slot.

Description:
Allocate a TLD. A TLD (thread local storage) is a integer that is allocated on the process level but accessed by threads. A thread can assign an arbritary value to a TLD and then retrieve the value later. The TLD handle can be distributed among the threads but each thread will have their own privat storage for the TLD. This means that both thread A and thread B can store different values to the same TLD without overwriting each other's TLD. This is for example used to give each thread a privat "errno" global variable.

Returns:
On success a positive handle is returned. On error -1 is returned "errno" will receive the error code.
Error codes:
ENOMEM All TLD slots are in use.
See also:
free_tld(), set_tld(), get_tld()
Author(s):
Kurt Skauen (kurt@atheos.cx)

int based_open ( int nRootFD,
const char * pzPath,
int nFlags,
... )
 

Open a file relative to a given directory.

Description:
based_open() have the same semantics as open() except that you can specify the "current working directory" as a parameter.

The first parameter should be a file descriptor for a open directory and the path can be eighter absolute (starting with a "/") in which case the semantics is exactly the same as for open() or it can be relative to nRootFD.

The "real" current working directory is not affected.

This provide a thread-safe way to do do the following: 

                int nOldDir = open( ".", O_RDONLY );
                fchdir( nRootFD );
                nFile = open( pzPath, ... );
                fchdir( nOldDir );
                close( nOldDir );

The problem with the above example in a multithreaded environment is that other threads will be affected by the change of current working directory and might get into trouble while we temporarily change it. Using based_open() is also more efficient since only one kernel-call is done (based_open() is just as efficient as open()).

Parameters:
nRootFD   The directory to use as starting point when searching for pzPath
pzPath   Path to the file to open. This can eighter be absolute or relative to nRootFD.
nFlags   Flags controlling how to open the file. Look at open() for a full description of the flags.
nMode   The access rights to set on the newly created file if O_CREAT is specified in nFlags

Returns:
based_open() return the new file descriptor on success or -1 if an error occurs, placing the error code in the global variable errno.
Error codes:
  • EMFILE nRootFD is not a valid file descriptor
  • ENOTDIR nRootFD is not a directory
  • In addition all error-codes returned by open() can be returned.
See also:
open(), close()
Author(s):
Kurt Skauen (kurt@atheos.cx)

status_t delete_semaphore ( sem_id hSema )
 

Delete a kernel semaphore.

Description:
Delete a semaphore previously created with create_semaphore(). Resources consumed by the semaphore will be released and all threads currently blocked on the semaphore will be waked up and the blocking function will return an error code.
Parameters:
hSema   Semaphore handle returned by a previous call to create_semaphore()
Returns:
On success 0 is returned. On error -1 is returned "errno" will receive the error code.
See also:
create_semaphore(), lock_semaphore(), lock_semaphore_ex(), unlock_semaphore(), unlock_semaphore_ex(), sleep_on_sem(), wakeup_sem(), unlock_and_suspend()
Author(s):
Kurt Skauen (kurt@atheos.cx)

int freadlink ( int nFile,
char * pzBuffer,
size_t nBufSize )
 

Read the content of an previously opened symlink.

Description:
Read the content of a symlink previously opened with open( path, O_NOTRAVERSE ).

The semantics is the same as for readlink() except that it take and already opened symlink rather than a path-name.

Normally when passing a symlink path to open() it will automatically open the file/dir that the link points to and not the link itself. To stop open() from traversing the links you can add the O_NOTRAVERSE flag to the open-mode. open() will then return a file-handle representing the link itself rather than the file the link points at.

Parameters:
nFile   File descriptor representing the symlink to read.
pzBuffer   Pointer to a buffer of at least nBufSize bytes that will receive the content of the symlink. The buffer will not be NUL terminated but the number of bytes added to the buffer will be returned by freadlink().
nBufSize   Size of pzBuffer.
Returns:
The call returns the number of bytes placed in the buffers on success, or -1 if an error occurs, placing the error code in the global variable errno.
Error codes:
  • EBADF nFile is not a valid file descriptor or is not open for reading
  • EINVAL nFile is not a symlink
  • ENOSYS The filesystem hosting nFile does not support symbolic links.
See also:
readlink()
Author(s):
Kurt Skauen (kurt@atheos.cx)

int free_tld ( int nHandle )
 

Release a TLD slot.

Description:
Release a TLD slot previously allocated with alloc_tld().
Parameters:
nHandle   The TLD slot to release.
Returns:
On success 0 is returned. On error -1 is returned "errno" will receive the error code.
Error codes:
  • EINVAL Invalid TLD handle.
See also:
alloc_tld(), set_tld(), get_tld()
Author(s):
Kurt Skauen (kurt@atheos.cx)

int get_tld ( int nHandle )
 

Retrieve the value stored in a TLD.

Description:
Retrieve the value stored earlier by *this* thread.
Parameters:
nHandle   The TLD to examine.
Returns:
The value of the given TLD
See also:
set_tld(), alloc_tld(), free_tld()
Author(s):
Kurt Skauen (kurt@atheos.cx)

status_t lock_semaphore ( sem_id hSema,
uint32 nFlags,
bigtime_t nTimeOut )
 

Lock a semaphore.

Description:
Locks a semaphore. Equivalent of calling lock_semaphore_ex() with a count of 1.
Parameters:
hSema   Semaphore handle to lock.
nFlags   No flags currently defined
nTimeOut   Maximum number of micro seconds to wait for the semaphore to be released. If the timeout is 0 lock_semaphore_ex() will never return, and if it is INFINITE_TIMEOUT it will block until the semaphore can be aquired or a signel is caught.
Returns:
On success 0 is returned. On error -1 is returned "errno" will receive the error code.
Error codes:
  • ETIME the semaphore could not be aquired before the timeout expiered.
  • EINTR a signal was caught before the semaphore could be aquired.
  • EINVAL hSema was not a valid semaphore handle, or the semaphore was deleted while we blocked.
See also:
lock_semaphore_ex()
Author(s):
Kurt Skauen (kurt@atheos.cx)

status_t lock_semaphore_ex ( sem_id hSema,
int nCount,
uint32 nFlags,
bigtime_t nTimeOut )
 

Aquire a semaphore.

Description:
Aquire a semaphore. lock_semaphore_ex() will decrease the semaphore's nesting counter with "nCount".

If the timeout is larger than 0 and the nesting counter becomes negative the calling thread will be blocked. The thread will then stay blocked until one of the following conditions are met:

  • Another thread release the semaphore and cause the nesting counter to become positive again and the function returns successfully.
  • The timeout runs out and the function returns with an ETIME error.
  • The calling threads catch a signal and the function return the EINTR error code.
If the timeout is 0 lock_semaphore_ex() will never block, but instead returns immediatly with ETIME if the semaphore can not be aquired. If the timeout is INFINITE_TIMEOUT the thread will be blocked until it can be successfully aquired or a signal is caught.

Parameters:
hSema   Semaphore handle to lock.
nCount   Positive value that should be subtracted from the current nesting counter.
nFlags   No flags currently defined
nTimeOut   Maximum number of micro seconds to wait for the semaphore to be released. If the timeout is 0 lock_semaphore_ex() will never return, and if it is INFINITE_TIMEOUT it will block until the semaphore can be aquired or a signel is caught.
Returns:
On success 0 is returned. On error -1 is returned "errno" will receive the error code.
Error codes:
  • ETIME the semaphore could not be aquired before the timeout expiered.
  • EINTR a signal was caught before the semaphore could be aquired.
  • EINVAL hSema was not a valid semaphore handle, or the semaphore was deleted while we blocked.
See also:
unlock_semaphore_ex(), lock_semaphore(), unlock_semaphore_ex(), create_semaphore(), delete_semaphore(), unlock_semaphore(), unlock_semaphore_ex(), sleep_on_sem(), wakeup_sem(), unlock_and_suspend()
Author(s):
Kurt Skauen (kurt@atheos.cx)

status_t rename_process ( int nProcessID,
const char * pzName )
 

Rename a process.

Description:
All processes have a name to aid debugging and to some degree make it possible to search for a process by name. The name is normally inherited from the parent during fork and later set to the executable name if the process exec's but it can also be set explicitly with rename_process().
Note:
The name will be replaced with the name of the executable if the process ever call execve().
Parameters:
nProcessID   Identity of the process to rename. You can also pass in -1 to rename the calling process.
pzName   The new process name. Maximum OS_NAME_LENGTH characters long including the 0 termination. On success 0 is returned. On error -1 is returned "errno" will receive the error code.
Error codes:
  • ESRCH nProcessID is not -1 and there is not process with that ID.
  • EFAULT pzName points to an address not accessible by this process.
See also:
rename_thread(), get_process_id()
Author(s):
Kurt Skauen (kurt@atheos.cx)

void set_tld ( int nHandle,
int nValue )
 

Assign a value to a TLD slot.

Description:
Assigne a value to the calling threads storage associated with the given TLD handle. This will not affect the value of the same TLD in another thread and the value can only be read back by the thread who actually assigned it.
Parameters:
nHandle   Handle to a TLD slot previously allocated by alloc_tld()
nValue   The value to assign to the TLD.

See also:
get_tld(), alloc_tld(), free_tld()
Author(s):
Kurt Skauen (kurt@atheos.cx)

status_t unlock_semaphore ( sem_id hSema )
 

Release a semaphore.

Description:
Same as unlock_semaphore_x() with a count of 1.
See also:
unlock_semaphore_x()
Author(s):
Kurt Skauen (kurt@atheos.cx)

status_t unlock_semaphore_ex ( sem_id hSema,
int nCount )
 

Release a semaphore.

Description:
Release a semaphore "nCount" number of times. The value of "nCount" will be added to the semaphores nesting counter and if the counter become positive (>=0) the first thread blocking on the semaphore will be unblocked.
Note:
If "nCount" is larger than 1 all blocked threads will be unblocked and they will then compeat for the semaphore based on their scheduler priority. If "nCount" is 1 only the first blocked thread will be unblocked.
Parameters:
hSema   The semaphore to release.
nCount   Number of times to release the semaphore.
Returns:
On success 0 is returned. On error -1 is returned "errno" will receive the error code.
Error codes:
  • EINVAL hSema is not a valid semaphore handle.
See also:
unlock_semaphore(), lock_semaphore_ex()
Author(s):
Kurt Skauen (kurt@atheos.cx)

Generated at Sat Apr 7 16:12:50 2001 for AtheOS syscalls by doxygen1.2.5 written by Dimitri van Heesch, © 1997-2001