


PEKS-PTHREADS(3)PEKS 0.8.18 Programming InterfacePEKS-PTHREADS(3)


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

SSYYNNOOPPSSIISS
       ##iinncclluuddee <<ppeekkss..hh>>

       iinntt iioo__ppttiinniitt ((vvooiidd **_p_t_h_r_e_a_d___m_u_t_e_x_a_t_t_r));;

       vvooiidd iioo__ppttddeessttrrooyy ((vvooiidd));;

       vvooiidd **iioo__ppttlloocckk ((uunnssiiggnneedd  _f_d,, uunnssiiggnneedd _h_o_w));;

       vvooiidd iioo__ppttuunnlloocckk ((vvooiidd **_l_o_c_k___h_a_n_d_l_e));;

       vvooiidd iioo__ppttlloocckk__sseemmaa ((vvooiidd));;

       vvooiidd iioo__ppttuunnlloocckk__sseemmaa ((vvooiidd));;

       iinntt iioo__ppttaavvaaiill ((vvooiidd));;

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

           ./configure --enable-pthreads ...

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

       IIoo__ppttiinniitt(()) enables the internal Posix thread control fea-
       tures.   Unless  explicitely  compiled  for posix threads,
       this function has no effect. The  argument  _p_t_h_r_e_a_d___m_u_t_e_x_-
       _a_t_t_r   is  of  type  ((pptthhrreeaadd__aattttrr__tt**))  and  described  in
       pptthhrreeaadd__mmuutteexx__iinniitt(3).  Only for compatibility with a  non
       threads   supporting  version,  the  type  has  been  made
       ((vvooiidd**)). For real Posix treads the value can be NULL  (for
       default)  although the symbol _p_t_h_r_e_a_d___a_t_t_r___d_e_f_a_u_l_t is also
       used in some (older) implementations.

       IIoo__ppttddeessttrrooyy(()) 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  ffoorrkk(())  directive.   The  very  first
       IIoo__ppttiinniitt(()) call will inialize all run-time  configuration
       data.



PEKS CIPHER LAYER          Jan 21, 2001                         1





PEKS-PTHREADS(3)PEKS 0.8.18 Programming InterfacePEKS-PTHREADS(3)


       IIoo__ppttlloocckk(()) lets you install a blocking lock on an io data
       stream pushed with iioo__ppuusshh(3).  This syncronization  works
       for  any  active  iostream  accessed  through the iostream
       functions  and  its  replacenemts  (send,  recv  etc.  see
       _i_o_s_t_r_e_a_m(3)).  It  does  not  work while a data stream has
       been  suspended  with  iioo__ssuussppeenndd(3).   The  arguments  to
       iioo__ppttlloocckk(())   are   the   same  ones  you  would  pass  to
       iioo__ppuusshh(3), a file handle _f_d and an io direction _h_o_w:  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 IIoo__ppttlloocckk(()) can savely be used also when the
       Posix threads support has not been enabled at compile time
       (in which case it has no effect.)

       IIoo__ppttuunnlloocckk(()) releases the blocking lock previously estab-
       lised with iioo__ppttlloocckk(()),  argument  is  the  pointer  value
       returned  from  iioo__ppttlloocckk(())  (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.

       IIoo__ppttlloocckk__sseemmaa(()) and iioo__ppttlloocckk__sseemmaa(())  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.)

       IIoo__ppttaavvaaiill(()) is a function available only with proper sup-
       port  for the Posix threads.  It returns 0.  This function
       is not prototyped in ppeekkss..hh. Some picky compiler may  want
       the line

           eexxtteerrnn iinntt iioo__ppttaavvaaiill ((vvooiidd));;

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

RREETTUURRNN VVAALLUUEE
       IIoo__ppttiinniitt(()) 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 _e_r_r_n_o will be set to  sug-
       gest an explanation.

       IIoo__ppttlloocckk(()) returns a pointer to an opaque lock descriptor
       on success, or NULL to indicate an error.   In  that  case
       the global variable _e_r_r_n_o will be set to suggest an expla-
       nation.




PEKS CIPHER LAYER          Jan 21, 2001                         2





PEKS-PTHREADS(3)PEKS 0.8.18 Programming InterfacePEKS-PTHREADS(3)


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

       The     functions      iioo__ppttddeessttrrooyy(()),      iioo__ppttuunnlloocckk(()),
       iioo__ppttlloocckk__sseemmaa(()), and iioo__ppttuunnlloocckk__sseemmaa(()) do not return any
       value.


EERRRROORR CCOODDEESS
       Some error codes besides the eerrrrnnoo(3) interface are  used,
       here.  They  are  referred  to as error symbols (see ppeekkss--
       eerrrrnnuumm(3) for details):

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

SSEEEE AALLSSOO
       iioossttrreeaamm(3),    iioo__ppuusshh(3),    iioo__ssuussppeenndd(3),    mmuutteexx(3),
       pptthhrreeaadd__mmuutteexx__iinniitt(3), ffoorrkk(2), eerrrrnnoo(3), ppeekkss--eerrrrnnuumm(3),

AAUUTTHHOORR
       The ppeekkss package where these functions belong to was writ-
       ten by Jordan Hrycaj <jordan@teddy-net.com>, originally to
       support the nneessssuuss security scanner.


































PEKS CIPHER LAYER          Jan 21, 2001                         3


