--- name: "peks-pthreads" section: "3" platform: "linux" package: "libnessus-dev" version: "1.0.10-2" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/peks-pthreads" --- # peks-pthreads(3) Posix threads support for peks ## NAME io\_ptinit, io\_ptdestroy, io\_ptavail, io\_ptlock\_sema, io\_ptunlock\_sema\ io\_ptlock, io\_ptunlock - Posix threads support for peks ## SYNOPSIS ``` #include 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)](/iostream/3.md) 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)](/pthread_mutex_init/3.md). 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)](/io_push/3.md). This syncronization works for any active iostream accessed through the iostream functions and its replacenemts (send, recv etc. see [*iostream*(3)](/iostream/3.md)). It does not work while a data stream has been suspended with [**io\_suspend**(3)](/io_suspend/3.md). The arguments to **io\_ptlock()** are the same ones you would pass to [**io\_push**(3)](/io_push/3.md), 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)](/errno/3.md) interface are used, here. They are referred to as error symbols (see [**peks-errnum**(3)](/peks-errnum/3.md) for details): ``` IOST_PTH_INALREAD Posix threads initalized, already IOST_NO_PTHREADS Not compiled for Posix threads support ``` ## SEE ALSO [**iostream**(3)](/iostream/3.md), [**io\_push**(3)](/io_push/3.md), [**io\_suspend**(3)](/io_suspend/3.md), **mutex**(3), [**pthread\_mutex\_init**(3)](/pthread_mutex_init/3.md), [**fork**(2)](/fork/2.md), [**errno**(3)](/errno/3.md), [**peks-errnum**(3)](/peks-errnum/3.md), ## AUTHOR The **peks** package where these functions belong to was written by Jordan Hrycaj \, originally to support the **nessus** security scanner.