peks-pthreads(3)

NAME

io_ptinit, io_ptdestroy, io_ptavail, io_ptlock_sema, io_ptunlock_sema
io_ptlock, io_ptunlock - Posix threads support for peks

SYNOPSIS

#include <peks.h>

int io_ptinit (void *pthread_mutexattr);

void io_ptdestroy (void);

void *io_ptlock (unsigned  fd, unsigned how);

void io_ptunlock (void *lock_handle);

void io_ptlock_sema (void);

void io_ptunlock_sema (void);

int io_ptavail (void);

DESCRIPTION

Posix threads are supported through the iostream(3) part of the peks library. They must be explicitely enabled at configuration time as

./configure --enable-pthreads ...

The iostream lib can then internally be syncronized by means of Posix thread mutex(3) (mutual exlusive) access control (semaphores.)

Io_ptinit() enables the internal Posix thread control features. Unless explicitely compiled for posix threads, this function has no effect. The argument pthread_mutexattr is of type (pthread_attr_t*) and described in pthread_mutex_init(3). Only for compatibility with a non threads supporting version, the type has been made (void*). For real Posix treads the value can be NULL (for default) although the symbol pthread_attr_default is also used in some (older) implementations.

Io_ptdestroy() disables the support for Posix threads and releases all locks on the iostream resources. On a system that forks before the Posix threads are activated, it makes sense to implement

io_ptinit (0); /* pre-initialize iostreams */
io_ptdestroy ();

before the first fork() directive. The very first Io_ptinit() call will inialize all run-time configuration data.

Io_ptlock() lets you install a blocking lock on an io data stream pushed with io_push(3). This syncronization works for any active iostream accessed through the iostream functions and its replacenemts (send, recv etc. see iostream(3)). It does not work while a data stream has been suspended with io_suspend(3). The arguments to io_ptlock() are the same ones you would pass to io_push(3), a file handle fd and an io direction how: the value 0 for reading and 1 for writing. This function returns you an opaque handle that is needed for unlocking, later on.

The function Io_ptlock() can savely be used also when the Posix threads support has not been enabled at compile time (in which case it has no effect.)

Io_ptunlock() releases the blocking lock previously establised with io_ptlock(), argument is the pointer value returned from io_ptlock() (even if this is the NULL pointer). This function can savely be used when the Posix threads support has not been enabled at compile time, as well.

Io_ptlock_sema() and io_ptlock_sema() provide a simple, independent blocking semaphore not shared by any other functions. These functions can savely be used when the Posix threads support has not been enabled at compile time, as well (in which case tey have no effect.)

Io_ptavail() is a function available only with proper support for the Posix threads. It returns 0. This function is not prototyped in peks.h. Some picky compiler may want the line

extern int io_ptavail (void);

in your code before you invoke that function. Use Io_ptavail() to make sure that the library you link against is the one with support for Posix threads (otherwise your program would not link, at all.)

RETURN VALUE

Io_ptinit() returns 0 when the Posix threads support could be initialized, and -1 otherwise. In particulat, this function fails if there is no support for Posix threads, or if Posix threads had been initalized, already. In case of an error the global variable errno will be set to suggest an explanation.

Io_ptlock() returns a pointer to an opaque lock descriptor on success, or NULL to indicate an error. In that case the global variable errno will be set to suggest an explanation.

Io_ptavail() returns the value 0 (if available, at all.)

The functions io_ptdestroy(), io_ptunlock(), io_ptlock_sema(), and io_ptunlock_sema() do not return any value.

ERROR CODES

Some error codes besides the errno(3) interface are used, here. They are referred to as error symbols (see peks-errnum(3) for details):

IOST_PTH_INALREAD Posix threads initalized, already
IOST_NO_PTHREADS  Not compiled for Posix threads support

AUTHOR

The peks package where these functions belong to was written by Jordan Hrycaj <[email protected]>, originally to support the nessus security scanner.