--- name: "localserversocket" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/localserversocket" --- # localserversocket(3bobcat) Unix Domain Server socket accepting connection requests ## NAME FBB::LocalServerSocket - Unix Domain Server socket accepting connection requests ## SYNOPSIS **#include \**\ 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 available **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 is not removed when the **LocalServerSocket** is destroyed. - o **UNLINK**:\ When this value is specified at construction time, the file representing the Unix Domain Socket is removed when the **LocalServerSocket** is destroyed. As a socket cannot be reused, this is the default value used with the **LocalServerSocket** constructor. ## 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 = UNLINK)** **throw (Exception)**:\ This constructor initializes an **FBB::LocalServerSocket** object, which will listen for connection requests using the named Unix Domain socket. An **FBB::Exception** is thrown if the socket could not be constructed. If the constructor is given a second argument *FBB::LocalServerSocket::KEEP*, the constructed socket is not 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. Copy and move constructors (and assignment operators) are 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::Exception** 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 = UNLINK)**:\ 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::Exception** is thrown if the socket could not be constructed. If the a second argument *FBB::LocalServerSocket::KEEP*, is provided the constructed socket is not 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)](/localclientsocket/3bobcat.md) example. ``` #include #include #include #include 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 (Exception 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)](/bobcat/7.md), [**localclientsocket**(3bobcat)](/localclientsocket/3bobcat.md), [**fork**(3bobcat)](/fork/3bobcat.md), [**ifdstream**(3bobcat)](/ifdstream/3bobcat.md), [**ifdbuf**(3bobcat)](/ifdbuf/3bobcat.md), [**localsocketbase**(3bobcat)](/localsocketbase/3bobcat.md), [**ofdstream**(3bobcat)](/ofdstream/3bobcat.md), [**ofdstream**(3bobcat)](/ofdstream/3bobcat.md), [**select**(2)](/select/2.md), [**selector**(3bobcat)](/selector/3bobcat.md), [**serversocket**(3bobcat)](/serversocket/3bobcat.md) ## BUGS None Reported. ## BOBCAT PROJECT FILES - o *https://fbb-git.gitlab.io/bobcat/*: gitlab project page; Debian Bobcat project files: - o *libbobcat6*: debian package containing the shared library, changelog and copyright note; - o *libbobcat-dev*: debian package containing the static library, headers, manual pages, and developer info; ## 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**).