Provided by: libbobcat-dev_2.20.01-1_amd64 bug

NAME

       FBB::LocalServerSocket - Unix Domain Server socket accepting connection requests

SYNOPSIS

       #include <bobcat/localserversocket>
       Linking option: -lbobcat

DESCRIPTION

       An  FBB::LocalServerSocket  defines  a Unix Domain server socket, listening for connection
       requests from the local host using a  Unix  Domain  socket.  Connection  requests  may  be
       accepted  in either blocking or non-blocking modes. When a connection is accepted a socket
       is returned which may be used to read information from or write information to the  client
       requesting  the  connection.  The socket that is made available is a file descriptor which
       may be used to initialize a std::istream and/or std::ostream. The std::istream is used  to
       read  information from the client process; the std::ostream is used to send information to
       the client process.  Since a socket may be  considered  a  file  descriptor  the  avaiable
       FBB::IFdStream,  FBB::IFdStreamBuf,  FBB::OFdStream,  and FBB::OFdStreamBuf classes may be
       used profitably here. Note that having available a socket does not mean that this  defines
       the  communication  protocol. It is (still) the responsibility of the programmer to comply
       with an existing protocol or to implement a tailor-made  protocol.  The  latter  situation
       implies that the sequence of input- and output operations is defined by the programmer.

NAMESPACE

       FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are
       defined in the namespace FBB.

INHERITS FROM

       FBB::LocalSocketBase

ENUMERATION

       The following enumeration is defined in th class FBB::LocalServerSocket:

       enum Socket
       This enumeration holds two values:

       o      KEEP:
              When this value is specified at construction time, the file representing  the  Unix
              Domain  Socket will not be removed when the LocalServerSocket is destroyed. This is
              the default value used with the LocalServerSocket constructor.

       o      UNLINK:
              When this value is specified at construction time, the file representing  the  Unix
              Domain Socket will be removed when the LocalServerSocket is destroyed.

CONSTRUCTOR

       o      LocalServerSocket():
              This  constructor creates an empty (non-functioning) FBB::LocalServerSocket object.
              Before it can be used, the open() member must be called (see below).

       o      LocalServerSocket(string const &name, Socket action = KEEP) throw (Errno):
              This constructor initializes an FBB::LocalServerSocket object,  which  will  listen
              for  connection  requests  using  the  named  Unix Domain socket.  An FBB::Errno is
              thrown if the socket could not be constructed. If the constructor is given a second
              argument  FBB::LocalServerSocket::UNLINK,  the  constructed socket will be unlinked
              when the FBB::LocalServerSocket object  is  destroyed.   The  construction  of  the
              socket  does  not mean that the FBB::LocalServerSocket object is actually listening
              for connections. To start listening, the member listen()  should  be  called.   The
              copy constructor is not available.

MEMBER FUNCTIONS

       o      size_t accept():
              The  accept() member returns an size_t which is a file descriptor (socket) that may
              be used to communicate with the client requesting the connection. In  more  complex
              programs  the  returned file descriptor (socket) could be passed to a class derived
              from FBB::Fork, handling the communication with the child  as  a  separate  (child)
              process.

       o      void listen(size_t backlog = 5, bool blocking = true):
              The  listen()  member  defines  the  way the FBB::LocalServerSocket will listen for
              clients  requesting  a  connection.   It   can   be   used   only   once   with   a
              FBB::LocalServerSocket. An FBB::Errno object is thrown if listening fails.

              The    listen()    member’s   backlog   parameter   defines   the   size   of   the
              FBB::LocalServerSocket’s internal queue in which connection requests may be  stored
              waiting  for  their  turn  to  be  serviced.  When backlog requests are waiting and
              another request arrives, then that request is lost.

              The member’s second parameter, blocking, is used to control the blocking  mode.  By
              default,   blocking  is  used,  and  listen()  will  wait  until  a  connection  is
              established. This is ok in situations where clients  connect  infrquently  and  for
              relatively   short   time  intervals.  Otherwise,  in  more  complex  programs,  an
              FBB::Selector object can be used to sense input on  the  server  socket  and/or  on
              various client sockets.

       o      void open(string const &name, Socket action = KEEP):
              This  member  prepares  a  FBB::LocalServerSocket object for use. It should only be
              used  in  combination  with  the  default   constructor.   Following   open()   the
              FBB:::LocalServerSocket object will be able to listen for connection requests using
              the named Unix Domain socket.  An FBB::Errno is thrown if the socket could  not  be
              constructed.  If  the a second argument FBB::LocalServerSocket::UNLINK, is provided
              the constructed socket will be unlinked when the FBB::LocalServerSocket  object  is
              destroyed.    The   construction   of   the   socket   does   not   mean  that  the
              FBB::LocalServerSocket object is  actually  listening  for  connections.  To  start
              listening, the member listen() should be called next.

EXAMPLE

       See also the localclientsocket(3bobcat) example.

           #include <iostream>
           #include <bobcat/localserversocket>
           #include <bobcat/ifdstream>
           #include <bobcat/ofdstream>

           using namespace std;
           using namespace FBB;

           int main(int argc, char **argv)
           try
           {
               if (argc == 1)
               {
                   cerr << "Provide local filename, e.g., /tmp/uds\n";
                   return 1;
               }

               LocalServerSocket server(argv[1]);

               cerr << "server using `" << argv[1] << "’" << endl;

               cout <<
                   "The server terminates when it receives a single `q’ on a line\n"
                   "A connection is terminated when no input is received anymore.\n"
                   "Then another connection is possible" << endl;

               server.listen();                // listen in blocking mode

               while (true)
               {
                   int fd = server.accept();

                   cerr << "Client FD = " << fd << ", " << endl;

                   IFdStream in(fd);           // stream to read from client
                   OFdStream out(fd);          // stream to write to client
                   string cmd;

                   while (getline(in, cmd))
                   {
                       cout << "Got: " << cmd << endl;
                       out << "Got: " << cmd << "\r" << endl;

                       if (cmd[0] == ’q’)
                           return 0;
                   }
                   cout << "Ready for another connection\n";
               }
           }
           catch (Errno const &err)
           {
               cerr <<
                   err.what() << endl <<
                   "Server socket on port " << argv[1] <<
                   " can’t be opened" << endl;
               return -1;
           }

FILES

       bobcat/serversocket - defines the class interface

SEE ALSO

       bobcat(7),       localclientsocket(3bobcat),       fork(3bobcat),      ifdstream(3bobcat),
       ifdstreambuf(3bobcat), localsocketbase(3bobcat),  ofdstream(3bobcat),  ofdstream(3bobcat),
       select(2), selector(3bobcat), serversocket(3bobcat)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_2.20.01-x.dsc: detached signature;

       o      bobcat_2.20.01-x.tar.gz: source archive;

       o      bobcat_2.20.01-x_i386.changes: change log;

       o      libbobcat1_2.20.01-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_2.20.01-x_*.deb:  debian  package holding the libraries, headers and
              manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT

       This is free software, distributed under the terms  of  the  GNU  General  Public  License
       (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).