


IOSTREAM(3)     PEKS 0.8.13 Programming Interface     IOSTREAM(3)


NNAAMMEE
       io_connect, io_accept, io_listen - a transparent TCP layer

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

       iinntt sseenndd ((uunnssiiggnneedd _f_d,, ccoonnsstt cchhaarr **_d_a_t_a,, uunnssiiggnneedd _l_e_n,,
                 uunnssiiggnneedd _f_l_a_g_s));;

       iinntt rreeccvv ((uunnssiiggnneedd _f_d,, cchhaarr **_b_u_f_f_e_r,, uunnssiiggnneedd _l_e_n,,
                 uunnssiiggnneedd _f_l_a_g_s));;

       iinntt sshhuuttddoowwnn ((uunnssiiggnneedd _f_d,, uunnssiiggnneedd _h_o_w));;

       iinntt cclloossee ((uunnssiiggnneedd _f_d));;

       iinntt iioo__ccoonnnneecctt ((ccoonnsstt cchhaarr** _s_e_r_v_e_r,, uunnssiiggnneedd _t_c_p___p_o_r_t_)_;
       iinntt iioo__lliisstteenn  ((ccoonnsstt cchhaarr** _b_i_n_d___n_a_m_e,, uunnssiiggnneedd _t_c_p___p_o_r_t_)_;
       iinntt iioo__aacccceepptt  ((iinntt _s_o_c_k_e_t));;

       iinntt _i_o___c_o_n_n_e_c_t___t_i_m_e_o_u_t,,_i_o___a_c_c_e_p_t___t_i_m_e_o_u_t,,_i_o___l_i_s_t_e_n___b_a_c_k_l_o_g;;

DDEESSCCRRIIPPTTIIOONN
       Make sure that the  "##iinncclluuddee  <<ppeekkss..hh>>"  directive  comes
       last  of the include files. This include file replaces the
       functions  sseenndd(()),  rreeccvv(()),  sshhuuttddoowwnn(()),  and  cclloossee(())  by
       extended versions iioo__sseenndd(()), iioo__rreeccvv(()), iioo__sshhuuttddoowwnn(()), and
       iioo__cclloossee(()).

       By default, the extended versions of the io-functions just
       call the functions that they are hiding, passing arguments
       and returning the function value received.

       Not until a cipher layer is (logically) pushed upon the io
       data  stream,  the extended io-functions become effective.
       Pushing a cipher layer upon the io data  stream  is  typi-
       cally  done transparently while the session key is negoti-
       ated.

       It may be nessary (but unlikely)  that  the  cypher  layer
       needs  to be removed, or popped from the io stream without
       closing it.  In that case, the extended  io-functions  act
       as  described  before,  just  passing arguments and return
       codes to and from the functions that they are hiding.

       IIoo__ccoonnnneecctt(()) is a TCP convenience function wrapper  around
       the ccoonnnneecctt(()) service from the operating system. The first
       argument _s_e_r_v_e_r is the server  name  to  connect  to  (see
       ggeetthhoossttbbyynnaammee(2)  for  the name resolution) and the second
       argument _t_y_p___p_o_r_t is TCP port on that server.

       By setting the global variable _i_o___c_o_n_n_e_c_t___t_i_m_e_o_u_t to  some
       positive  value n (default is 20), some timeout is imposed
       on how long the system waits fo  data.   This  is  unsally



PEKS CIPHER LAYER          Jul 10, 2000                         1





IOSTREAM(3)     PEKS 0.8.13 Programming Interface     IOSTREAM(3)


       done  by  wating  until  the data arrive and installing an
       aallaarrmm(()) timer, while reading.  So a signal SSIIGGAALLRRMM will be
       sent after n seconds terminating a pending ccoonnnneecctt(()) call.
       Setting this  variable  to  zero,  this  feature  will  be
       totally disabled, something negative allows to set a time-
       out (the absolute value of  that)  until  the  first  data
       arrive,  only.   In any case of a timeout, global variable
       eerrrrnnoo is set to the value _E_I_N_T_R.

       IIoo__lliisstteenn(()) is a TCP convenience function  wrapper  around
       the  lliisstteenn(()) service from the operating system. The first
       argument _b_i_n_d___n_a_m_e is a host name, the listener  binds  an
       address  to the listener socket (see bbiinndd(2) for details.)
       The second argument _t_c_p___p_o_r_t tells on which  tcp  port  an
       incoming connection request is accepted (see lliisstteenn(2) for
       details.)

       By setting the global variable _i_o___l_i_s_t_e_n___b_a_c_k_l_o_g  to  some
       value  n (default is 5), you can control how many connect-
       ing clients can be handled, simultaneously (see  lliisstteenn(2)
       for details.)

       IIoo__aacccceepptt(())  is  a TCP convenience function wrapper around
       the aacccceepptt(()) service from the operating system. The  func-
       tion argument is a listener socket number as returned from
       IIoo__lliisstteenn(()).

       By setting the global variable _i_o___a_c_c_e_p_t___t_i_m_e_o_u_t  to  some
       positive  value n (default is 5), a signal SSIIGGAALLRRMM will be
       sent after n seconds terminating a pending aacccceepptt(())  call.
       Setting  this  variable   to  something non-positive, this
       feature will be disabled.

       Example (client):

         int socket ;

         if ((socket = io_connect ("server.my.domain", 1234)) < 0)
            return -1;
         ...

       Example (server):

         int socket, listen_socket ;

         if ((listen_spcket = io_listen (0, 1234)) < 0)
            return -1;
         ...

         if ((socket = io_accept (listen_socket)) < 0)
            return -1;
         ...





PEKS CIPHER LAYER          Jul 10, 2000                         2





IOSTREAM(3)     PEKS 0.8.13 Programming Interface     IOSTREAM(3)


       Note:
           It is safe, to use the "##iinncclluuddee  <<ppeekkss..hh>>"  directive
           all  over  the  place  provided this include directive
           comes last.

RREETTUURRNN VVAALLUUEE
       The functions  sseenndd(()),  rreeccvv(()),  sshhuuttddoowwnn(()),  and  cclloossee(())
       behave  as  described  in the manual(2) from the operating
       system.

       Upon success, IIoo__ccoonnnneecctt(()) and io_accept() rreettuurrnn  aa  ooppeenn
       TTCCPP   ssoocckkeett   nnuummbbeerr   aass  ddeessccrriibbeedd  iinn  ccoonnnneecctt_(_2_)  _a_n_d
       aacccceepptt_(_2_)_, _a_n_d IIoo__lliisstteenn(()) _a _l_i_s_t_e_n_e_r _s_o_c_k_e_t _a_s  _d_e_s_c_r_i_b_e_d
       _i_n lliisstteenn..

       Upon  error,  these  functions  return -1 while the global
       variable eerrrrnnoo is set to indicate some explanation.

SSEEEE AALLSSOO
       lliisstteenn(2), aacccceepptt(2), ccoonnnneecctt(2),  ssoocckkeett(2),  iioo__ppuusshh(3),
       iioo__sseenndd(3), eerrrrnnoo(3), ppeekkss--eerrrrnnuumm(3, ggeetthhoossttbbyynnaammee(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          Jul 10, 2000                         3


