


IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


NNAAMMEE
       io_ctrl  - generic functions for the socket replacement io
       layer

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

       iinntt iioo__ccttrrll ((uunnssiiggnneedd _f_d,, iioo__ccttrrll__rreeqquueesstt _r_e_q_u_e_s_t,,
                    iinntt **aarrgg _a_r_g_u_m_e_n_t,, uunnssiiggnneedd _h_o_w));;

DDEESSCCRRIIPPTTIIOONN
       Refering to the man page  for  iioo__ppuusshh((33)),  this  function
       calls simply

              ((**_i_o_c_t_l___f_n)) ((_d_e_s_c,, _r_e_q_u_e_s_t,, _a_r_g))

       where  ddeesscc  == ddeesscc ((ffdd,, hhooww)) is the data area initialized
       as described in iioo__ppuusshh((33)), and  iiooccttll__ffnn(())  is  the  call
       back  function  passed  as argument to iioo__ppuusshh(()) upon ini-
       tialization.  There is a set of defined standard  requests
       all defined in the ppeekkss..hh header file, as there are:


       IIOO__RREESSIIZZEE__BBUUFF
              Argument is ((iinntt**))_b_u_f_f_e_r___s_i_z_e, or 0

              Return code is the buffer size currently effective

              Any  sender  or  receiver  define a new size of the
              maximal data block that can be processed  at  once.
              The  request returns the current buffer size (which
              might be different from the argument  size  due  to
              some adjustments,) or -1 to indicate some error.

              When the sender defines a new buffer size limit, it
              also adjusts its working buffer to that  limit  and
              forwards that information to the receiver not until
              the next data packet is sent.

              If the working buffer size sent is not larger  than
              the  limit  on  the  receiver, it will decrease the
              internal working buffer size (still remembering the
              buffer  size  limit) to the new size.  Otherwise it
              will ignore that information.

              By default, the internal buffer size limit  on  the
              receiver  is  CBC_IO_BUFLEN_MAX,  and  the  working
              buffers are set to CBC_IO_BUFLEN  on  both,  sender
              and receiver.

       IIOO__PPUUTT__SSEESSSSIIOONN__KKEEYY
              Argument is _k_e_y___d_a_t_a[[KKEEYYLLEENNGGTTHH__MMAAXX]]

              Return code is the 0, or -1 on error.



PEKS CIPHER LAYER          Jan 21, 2001                         1





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


              If  the argument _k_e_y___d_a_t_a exists, a new master ses-
              sion key will be set up by hashing the current mas-
              ter  session  key  with  the argument data.  In any
              case, the use of the master  session  key  will  be
              enabled.   So the master session key will be hashed
              with every new session key refresh.

              The client also  registeres,  that  the  next  data
              packet  to  be  received  _m_u_s_t invoke a session key
              update, otherwise an error will be  detected.   The
              server  will immediately change the session key and
              send the key change request to the client.

              Upon error -1 is returned.


       IIOO__SSEETT__KKEEYY__SSCCHHEEDDUULLEE
              Argument is ((iinntt**))_k_e_y___s_c_h_e_d_u_l_e

              Return code is the time to refresh the session  key
              next,  or the key refresh interval previosly effec-
              tive.

              The integer value passed by  the  argument  pointer
              defines  a  key schedule: A positive value sets the
              time interval (in seconds) to the next change while
              the absolute value of a negative argument implies a
              time period (in seconds), when the key  has  to  be
              changed  at  regular intervals.  A value 0 disables
              any automated session key refresh.

              The request returns a non negative value indicating
              the  old  setting of the time due when the argument
              was positive, or the key schedule when the argument
              pointer  was  NULL, or the argument value was nega-
              tive or zero.  Upon error -1 is returned.

       IIOO__RREEGGIISSTTEERR__TTHHRREEAADD
              Argument is ignored

              Return code is the id _t_h_r_e_a_d_I_D  of  the  io  thread
              just created


       IIOO__AACCTTIIVVAATTEE__TTHHRREEAADD
              Argument is ((iinntt**))_t_h_r_e_a_d_I_D or 0

              Return  code  is  the  id _t_h_r_e_a_d_I_D of the io thread
              previously active

              A thread is an independent instance of  the  sender
              descriptor  piping  through  the  same  io channel.
              There is always just one active thread.  The thread
              ID that was active before the new one was activated



PEKS CIPHER LAYER          Jan 21, 2001                         2





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


              is the return code passed back  from  the  registry
              service (unless -1 to indicate an error.)


       IIOO__UUNNLLIINNKK__TTHHRREEAADD
              Argument is ((iinntt**))_t_h_r_e_a_d_I_D or 0

              Return  code  is  the  id _t_h_r_e_a_d_I_D of the io thread
              record just removed


       IIOO__UUNNLLIINNKK__TTHHRREEAADD__PPIIDD
              Argument is ((uunnssiiggnneedd lloonngg**))_P_I_D or 0

              Return code is the number  of  io  thread  records,
              removed


       IIOO__DDEESSTTRROOYY__TTHHRREEAADD
              Argument is ((iinntt**))_t_h_r_e_a_d_I_D or 0

              Return  code  is  the  id _t_h_r_e_a_d_I_D of the io thread
              just closed

              Before forking, the sender has a new thread  regis-
              tered  on  sender and receiver.  After forking, the
              child activates the thread while the parent unlinks
              the  thread  without  notifying the receiver.  When
              the child finishes, it destroys the tread, finally.
              Upon  success,  the  destroy  or  unlink  functions
              return the id of the affected thread, and -1,  oth-
              erwise  while  errno is set to indicate the type of
              error.

              Example:
                int id = io_ctrl (socket, IO_REGISTER_THREAD, 0, 1);
                ...
                if (fork () == 0) {
                    /* child */
                    io_ctrl (socket, IO_ACTIVATE_THREAD, &id, 1);
                    ...
                    io_close (socket);
                    /* implies io_ctrl (, IO_DESTROY_THREAD, ); */
                    exit (0);
                }
                /* parent */
                io_ctrl (socket, IO_UNLINK_THREAD, &id, 1);
                ...


       IIOO__DDEESSTTRROOYY__TTHHRREEAADD__PPIIDD
              Argument is ((uunnssiiggnneedd lloonngg**))_P_I_D or 0

              Return code is the  number  of  io  thread  records



PEKS CIPHER LAYER          Jan 21, 2001                         3





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


              locally found

              The  unlink/destroy  requests are available in some
              other flavour, as well.  When a  thread  is  regis-
              tered, or activated the process id is stored.  Upon
              pid-unlinking or pid-destroying, all those  threads
              are  canceled,  that have been created/activated by
              the  PID  given as argument.  On argument value  0,
              all  threads  are  unlinked  or destroyed, when the
              NULL pointer is passed, the current process  id  is
              used.  So, with the same effect as before, the last
              iioo__ccttrrll(()) statement in the example,  above  can  be
              replaced by

                  ...
                  }
                  /* parent */
                  io_ctrl (socket, IO_UNLINK_THREAD_PID, 0, 1);
                  ...

              Upon  return,  the  non-negative  number of threads
              unlinked, or destroyed is returned, and  -1  if  an
              error occured (while the errno variable is set.)


       IIOO__PPUURRGGEE__TTHHRREEAADD
              Argument is ((iinntt**))_t_h_r_e_a_d_I_D or 0

              Return  code  is  the  id _t_h_r_e_a_d_I_D of the io thread
              just closed

              This   request    is    mainly    the    same    as
              IIOO__DDEESSTTRROOYY__TTHHRREEAADD  (see  above)  with a lazy way to
              remove the io  threads  on  the  receiver.  On  the
              reciever,  a purged io thread is not deleted unless
              the threads table reaches its  maximum  size.  Then
              the  oldest  io  thread  that  has  been  purged is
              deleted, first.

              As  a  side  effect,  the  receiver  will  continue
              accepting  messages  on  purged io threads (but not
              pass it to the invoking function) up until  the  io
              thread is finally removed from the table.


       IIOO__PPUURRGGEE__TTHHRREEAADD__PPIIDD
              Argument is ((uunnssiiggnneedd lloonngg**))_P_I_D or 0

              Return  code  is  the  number  of io thread records
              locally found

              This   function   is   basically   the   same    as
              IIOO__DDEESSTTRROOYY__TTHHRREEAADD__PPIIDD  but with the laziness on the
              receiver as described in IIOO__PPUURRGGEE__TTHHRREEAADD__PPIIDD.



PEKS CIPHER LAYER          Jan 21, 2001                         4





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


       IIOO__SSYYNNTTHHEETTIICC__PPIIDD
              Argument is ((uunnssiiggnneedd lloonngg**))_P_I_D or 0

              Return code is the synthetic _P_I_D  previosly  effec-
              tive

              In  order  to  control the result of ggeettppiidd(()) used,
              when threads are created  or  activated,  a  static
              value  can  be  stored on both, sender and receiver
              thread. If the argument value is 0, it  is  deacti-
              vated.  If the argument is NULL, the current pid is
              used. Upon return, the old value of  the  synthetic
              pid  is used (which might be negative, but errno is
              zero.)  On error, -1 is returned and  the  variable
              errno is set.


       IIOO__CCOOMMPPRREESSSS__LLEEVVEELL
              Argument is ((iinntt**))_C_o_m_p_r_e_s_s_L_e_v_e_l, or 0

              Return  code  is the previous state (0 or 1) of the
              compression for this channel.

              if the argument _C_o_m_p_e_s_s_L_e_v_e_l points  to  some  non-
              negative  integer,  the  current io channel will be
              compressed according to the integer value.  If  the
              interger  value  is negative, a current compression
              is removed from the channel.

              Sensible compression values are 0 => maximal speed,
              ...  9  =>  maximal  compression. Other values will
              produce some sensible default.

              When  forking  (see  REGISTER_THREAD),  the   newly
              reated  thread  inherits  the  compression property
              from the current one.

              Upon return, 0 is returned if there was no compres-
              sion  previously  active,  and  1  otherwise.    On
              error, -1 is returned and  the  variable  errno  is
              set, accordingly.


       IIOO__MMAAXX__TTHHRREEAADDSS
              Argument is ((iinntt**))_T_h_r_e_a_d_s_M_a_x, or 0

              Return  code is the maximal number _T_h_r_e_a_d_s_M_a_x, pre-
              viously effective

              The number of active threads can be  controlled  by
              the  this  request  on  receiver.   Note,  that the
              receiver will  be  most  likely  unable  to  resyn-
              cronize, when this limit is exeeded.  All that cur-
              rently can be done is  to  close,  and  reopen  the



PEKS CIPHER LAYER          Jan 21, 2001                         5





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


              dialogue.

              On  error, -1 is returned and the variable errno is
              set.


       IIOO__HHWWMMBBLL__TTHHRREEAADDSS
              Argument is ((iinntt**))_H_i_g_h_W_a_t_e_r_M_a_r_k_B_l, or 0

              Return code is the value  of  the  _H_i_g_h_W_a_t_e_r_M_a_r_k_B_l,
              previously effective.

              In  addition  to  the maximal value of threads, the
              receiver can impose a default _h_i_g_h _w_a_t_e_r  _m_a_r_k,  so
              that  an  action  occurs  whenever  the  number  of
              threads exceeds this value. The _h_i_g_h _w_a_t_e_r _m_a_r_k for
              threads trapping is calculated as

                  ThreadsMax - HighWaterMarkBl

              where   first   term   is  described  earlier  (see
              IIOO__MMAAXX__TTHHRREEAADDSS.)

              On error, -1 is returned and the variable errno  is
              set.


       IIOO__TTRRAAPP__TTHHRREEAADD__VVRRFFYY
              Arg           is           ((vvooiidd((****))((vvooiidd**,,uunnssiiggnneedd
              lloonngg**,,iinntt,,iinntt))))_T_r_a_p_F_n, or 0

              Return code is 1 if the previous trap was non-NULL,
              and  0  otherwise  while  in case that the argument
              pointer is non-NULL, the target value  is  replaced
              by the trap, previosly effective.

              By  setting  trap  functions a defensive feature is
              provided to prevent the  receiver  from  a  threads
              table overflow. Of course, this happens only if the
              sender  continues  creating  new  threads   without
              cleaning  up  the  old  ones  which  have  expired,
              already.

              Whenever the number  of  threads  on  the  receiver
              exeeds    a    certain   _h_i_g_h   _w_a_t_e_r   _m_a_r_k   (see
              IIOO__HHWWMMBBLL__TTHHRREEAADD) the trap function is called.  This
              trap  function  receives  a  random list of threads
              that   may   be   passed   to   the   sender   (see
              IIOO__SSEENNDD__TTHHRREEAADD__VVRRFFYY)  for  checking. The trap func-
              tion will be invoked as TTrraappFFnn((_f_d,,_l_i_s_t,,11)) where  _f_d
              is  the  current file descriptor of type _v_o_i_d_* (you
              need to cast it as _(_i_n_t_)_f_d) and _l_i_s_t is a  _u_n_s_i_g_n_e_d
              _s_h_o_r_t_* array of at most 8 thread ids to be checked,
              followed by a terminating 0 entry. On the receiver,



PEKS CIPHER LAYER          Jan 21, 2001                         6





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


              the third argument will always be zero.

              Example (receiver):

                #include <assert.h>

                void trap
                  (void            *fd,
                   unsigned long *list,
                   int       using_pid,
                   int             how)
                {
                    assert (using_pid == 0)  ;
                    io_ctrl ((int)fd, IO_SEND_THREAD_VRFY, list);
                }

              When the sender receives a trap function (note that
              we assume a data channel in  either  direction)  on
              the  other channel, it invokes the trap function as
              TTrraappFFnn((_f_d,,_l_i_s_t,,00)),, where the list is  array  of  at
              most 8 thread ids to be checked, followed by a ter-
              minating  0  entry  as  passed  to   the   function
              iioo__ccttrrll((_(_i_n_t_)_f_d,,_I_O___S_E_N_D___T_H_R_E_A_D___V_R_F_Y,,_l_i_s_t))   in  the
              receiver example, above. On the  receiving  sender,
              the third argument will be zero the iioo__ccttrrll(()) func-
              tion was used with the request IIOO__SSEENNDD__TTHHRREEAADD__VVRRFFYY,
              and  1  if  the request was IIOO__SSEENNDD__TTHHRREEAADD__VVRRFFYY__PPIIDD
              (see below.)

              Example (sender):

                void trap
                  (void          *fd,
                   unsigned long *id,
                   int     using_pid,
                   int           how)
                {
                    while (*id) {
                      if (using_pid) {
                        if (!that_pid_exists (*id))
                          io_ctrl ((int)fd, IO_PURGE_THREAD_PID, id);
                      } else {
                        if (!that_thread_id_exists (*id))
                          io_ctrl ((int)fd, IO_PURGE_THREAD, id);
                      }
                      id ++ ;
                    }
                }

              It makes sense to combine the preceeding two  exam-
              ples  to  a  single  trap function interpreting the
              third argument value _h_o_w.





PEKS CIPHER LAYER          Jan 21, 2001                         7





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


       IIOO__SSEENNDD__TTHHRREEAADD__VVRRFFYY
              Argument is ((uunnssiiggnneedd lloonngg**))_T_i_d_L_i_s_t, or 0

              Return code is the number  of  the  first  non-zero
              entries in the _T_i_d_L_i_s_t_[_].

              The argument list is an array of at most 8 entries,
              the last entry is a 0. This  function  sends  short
              numbers  interpreted as thread ids to the receiver.
              If installed, a trap function will  be  invoked  on
              the    other    end   as   described   above   (see
              IIOO__TTRRAAPP__TTRREEAADD__VVRRFFYY.)

              When   a   trap   function   vvooiidd((**))((vvooiidd**,,uunnssiiggnneedd
              lloonngg**,,iinntt,,iinntt))  is  invoked  on  the  receiver, the
              third argument is always zero.

              If there are more  than  8  entries  provided,  the
              extra will be ignored. On error, -1 is returned and
              the variable errno is set.



       IIOO__SSEENNDD__TTHHRREEAADD__VVRRFFYY__PPIIDD
              Argument is ((uunnssiiggnneedd lloonngg**))_T_i_d_L_i_s_t, or 0

              Return code is the number  of  the  first  non-zero
              entries in the _T_i_d_L_i_s_t_[_].

              This    request    is   basically   the   same   as
              IIOO__SSEENNDD__TTHHRREEAADD__VVRRFFYY but  acting  upon  process  ids
              (see  IIOO__SSYYNNTTHHEETTIICC__PPIIDD)  rather  than thread ids in
              the receiver.

              When   a   trap   function   vvooiidd((**))((vvooiidd**,,uunnssiiggnneedd
              lloonngg**,,iinntt,,iinntt))  is  invoked  on  the  receiver, the
              third argument is always 1.


       IIOO__CCAATTCCHH__TTHHRREEAADD
              Argument is ((iinntt((****))((cchhaarr**,,uunnssiiggnneedd,,vvooiidd  ****))))_C_a_l_l_-
              _B_a_c_k_F_n, or 0

              Return  code  is  the  id  of the current call back
              function while in the case of CCaallllBBaacckkFFnn !!== 00,  the
              pointer target is replaced by the value of the call
              back function previously active/registered.

              When called from a normal context on  the  receiver
              and  non  NULL  *CallBackFn  argument, this request
              registeres a call back function to be  assigned  to
              the next thread that will be created (due to a RREEGG--
              IISSTTEERR__TTHHRREEAADD on the sender).  After that, the  call
              back  function  will  have been moved to the active



PEKS CIPHER LAYER          Jan 21, 2001                         8





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


              thread an not be available anymore.   So  you  need
              another  IIOO__CCAATTCCHH__TTHHRREEAADD  request  if  you like the
              next thread to be catched, as well. The  call  back
              function looks like

                  iinntt CCaallllBBaacckkFFnn ((cchhaarr **_d_a_t_a,, uunnssiiggnneedd _l_e_n,,
                                  vvooiidd **_s_o_c_k_e_t,, vvooiidd ****_c_o_n_t_e_x_t));;

              where  data  and len describe the data input buffer
              as passed to iioo__rreeaadd(()), len in the current size  of
              input  data just received.  The third value context
              points to a zero initialized static data area large
              enough  to  hold  a pointer variable (pointing to a
              pseudostatic function context).

              Only when the thread is to be called for the  first
              or  the  last  time,  the  function is invoked with
              bbuuff====00, where the  arguments  indicate  the  events
              listed below:

                buf len event
                -------------------------------------------------
                0   0  destructor
                0   1  constructor, first call of that function
                0   2  constructor, fn was cloned on a new thread

              Unless  invoked  for  the first time or with bbuuff====00
              (wich is the last time), the return code  for  this
              call back function is handled as follows:

                _r_e_t_u_r_n  _c_o_d_e  _< _0 , iioo__rreeaadd(()) will return -1 (you
                should set the errno variable in this case)

                _r_e_t_u_r_n _c_o_d_e _>_= _0 , iioo__rreeaadd(()) returns this  number
                as  data  length,  read (so you should adjust the
                contents of the input buffer pointed  to  by  the
                argument buf)

              If  you  process  data with the call back function,
              you should always invoke an IIOO__FFLLUUSSHH__CCAACCHHEE  control
              request  before  you  leave the function as data in
              the cache that came with this thread cannot be han-
              dled with a call back function, anymore.

              If  the  IIOO__CCAATTCCHH__TTHHRREEAADD request is dispatched from
              within an active call back function, the  registra-
              tion will refer to the currently active thread.  So
              it is possible to change  the  call  back  function
              from  within  the currently running call back func-
              tion.

              If the CallBackFn argument points to a zero  value,
              the  currently  registered  call  back  function is
              removed or deactivated, depending  on  the  calling



PEKS CIPHER LAYER          Jan 21, 2001                         9





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


              context.

              Example:

                int thread_catcher
                  (char    *buf,
                   unsigned len,
                   void *socket,
                   void     **p)
                {
                    CTX* context ;

                    /* get my thread id */
                    int myself = io_ctrl
                        ((int)socket, IO_CATCH_TRHEAD,0,0);

                    if (buf == 0) {
                        if (len == 0) {
                            free (context);
                            return 0 ;
                        }
                        *p = malloc (sizeof (CTX)) ;
                    }
                    context = *p ;

                    /* so lets look what the data are like */
                    if (len > 0) {
                        ...
                    }

                    /* ok, that's it */
                    if (ok != 0)
                        return len;
                    ...

                    /* error */
                    return -1;
                }

              On  error, -1 is returned and the variable errno is
              set.


       IIOO__CCAATTCCHH__CCLLOONNIINNGG
              Argument is ((iinntt**))_C_l_o_n_e_F_l_a_g, or 0

              Return code is the _C_l_o_n_e_F_l_a_g, previously effective

              The _C_l_o_n_e_F_l_a_g controls on the receiver, if  any  io
              thread  can clone its call back functions when cre-
              ating a new thread (invoked  by  the  sender).   By
              default, this flag is reset.

              This  directive  works  on  the same context as the



PEKS CIPHER LAYER          Jan 21, 2001                        10





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


              IIOO__CCAATTCCHH__TTHHRREEAADD directives.  Preferrably it  should
              be  invoked  by  the  running call back function in
              which case it acts on a local context.  If  a  call
              back  function  is  cloned, the _C_l_o_n_e_F_l_a_g flag will
              not be copied but reset.


       IIOO__CCAATTCCHH__EENNVVPP
              Argument is ((vvooiidd ****))_E_N_V, or 0

              Return code is 0, if there was no catcher  function
              active, and 1 otherwise.

              In the latter case, if _E_N_V is non-NULL, the pointer
              target is replaced by the value of  ENV  previously
              active/registered.

              If  a  catcher  function  has  been registered with
              IIOO__CCAATTCCHH__TTHHRREEAADD,  the  IIOO__CCAATTCCHH__EENNVVPP  request  will
              attach an environment pointer to that function.

              This  environment  simply  pre-initialize  the last
              argument passed to an active thread call back func-
              tion CCaallllBBaacckkFFnn(()).

              Once  registred,  this environment will be moved to
              the active thread, when it is initialized.  So  you
              need  another  IIOO__CCAATTCCHH__EENNVVPP request after the next
              IIOO__CCAATTCCHH__TTHHRREEAADD  request,  if  you  like  the  next
              thread  to  have  attached  another environment, as
              well.


       IIOO__UUNNCCAATTCCHH__TTHHRREEAADD
              Argument is ((iinntt **))_C_a_l_l_B_a_c_k_F_n_I_D, or 0

              Return code is the id of the currently removed call
              back function

              The  request  removes a currently active thread for
              the given _C_a_l_l_B_a_c_k_F_n_I_D and returns  the  number  if
              the  thread,  removed.   When the argument is NULL,
              the thread currently waiting to be assigned to  the
              next created thread is removed.

       IIOO__PPUUBBLLIICC__DDEESSTTRROOYY
              Argument is ((iinntt**))_P_u_b_l_i_c_D_e_s_t_r_o_y_F_l_a_g, or 0

              Return  code  is  the_P_u_b_l_i_c_D_e_s_t_r_o_y_F_l_a_g,  previously
              effective

              The _P_u_b_l_i_c_D_e_s_t_r_o_y_F_l_a_g controls on the receiver,  if
              any io stream can destroy another io stream differ-
              ent from the current one.  By default, this flag is



PEKS CIPHER LAYER          Jan 21, 2001                        11





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


              reset  with  the  effect,  that  an  io  stream can
              destroy itself, only.


       IIOO__SSTTOOPPOONNEEMMPPTTYY__SSTTAATTEE
              Argument is ((iinntt**))_S_t_o_p_O_n_E_m_p_t_y_F_l_a_g, or 0

              Return code is the  _S_t_o_p_O_n_E_m_p_t_y_F_l_a_g  value,  previ-
              ously effective

              With  the following commands, a stop-on-empty-frame
              flag is controlled.  At some requests,  the  sender
              needs  to  inform the receiver about changes of the
              io channel state.  This is done by sending an empty
              frame   with   embedded   commands.    In   IIOO__SSTTOO--
              PPOONNEEMMPPTTYY__SSTTAATTEE with an argument pionter to  a  zero
              value,  the  application  does  not  see that empty
              frame (which is the default). If a  non-zero  argu-
              ment is pointed, to these empty frames are returned
              to the iioo__rreeccvv(()) calling  process.   The  iioo__ccttrrll(())
              function  returns  the  state of the stop-on-empty-
              frame flag that was active before the  change  took
              place.


       IIOO__EEOOFF__SSTTAATTEE
              Argument is ((iinntt**))_E_o_f_F_l_a_g, or 0

              Return code is the _E_o_f_F_l_a_g value, previously effec-
              tive

              When an empty frame which is not an  embedded  com-
              mand  is  received, the eof flag will be set.  This
              can be used to distinguish a real  empty  frame  in
              IIOO__SSTTOOPPOONNEEMMPPTTYY__SSTTAATTEE  active  from  an  empty frame
              caused by an embedded command, in  which  case  the
              eof-state is false.  In order to read on after hav-
              ing received an empty frame, the eof state must  be
              reset.   The iioo__ccttrrll(()) function return the state of
              the eof flag that was active before the change took
              place.


       IIOO__TTOOTTAALL__CCOOUUNNTTEERR
              Argument is ((iinntt**))_C_o_u_n_t_e_r_S_t_a_t_e, or 0

              Return  code  is the _C_o_u_n_t_e_r_S_t_a_t_e value, previously
              effective


       IIOO__PPAAYYLLOOAADD__CCOOUUNNTTEERR
              Argument is ((iinntt**))_C_o_u_n_t_e_r_S_t_a_t_e, or 0

              Return  code  is  the   ((iinntt**))_C_o_u_n_t_e_r_S_t_a_t_e   value,



PEKS CIPHER LAYER          Jan 21, 2001                        12





IO_CTRL(3)      PEKS 0.8.18 Programming Interface      IO_CTRL(3)


              previously effective

              The underlying protocol layer updates two counters,
              keeping track of the user bytes processed  and  the
              total  protocol  overhead  (including the user pay-
              load.)  The  latter  counter  does  not  take  into
              account  the  protocol  overhead that is induced by
              using the TCP/IP (or whatever) transport  protocol.
              Note,  that  the interface to reading out the coun-
              ters is made up by an  int  data  type,  which  may
              overflow causeing a negative return value.  In this
              case, the errno register is set to 0.


       IIOO__FFLLUUSSHH__CCAACCHHEE
              Argument is ignored

              Return code is the number of bytes, flushed

              Any cached data not  processed,  yet  are  flushed.
              Currently,  this  has  an effect on the receiver of
              the data stream, only.   In  general,  transferring
              data  blockwise, tehre is no need for the sender to
              cache data, but for the receiver when it getts more
              data in than requested by the application.

              It  is  save calling the function iioo__ccttrrll(()) without
              having installed  a  data  stream  diversion  using
              iioo__ppuusshh(()).


EERRRROORR CCOODDEESS
       When  there  was no data stream, pushed the iioo__ccttrrll(()) will
       immediately return with -1. The the global variable  eerrrrnnoo
       wil  be  set  to EEBBAADDFF (Bad file descriptor), see errno(3)
       for details on error codes.

       Other important error return symbols, see peks_stderr(3):

         IOST_NO_RECV_CTLFN   No receiver input fn, assigned
         IOST_NO_SEND_CTLFN   No sender control fn, assigned


SSEEEE AALLSSOO
       iioossttrreeaamm(3),    ggeettppiidd(2),    eerrrrnnoo(3),    ppeekkss--eerrrrnnuumm(3),
       iioo__ppuusshh(3), iioo__sseenndd(3), ffoorrkk(2),

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                        13


