--- name: "selector" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/selector" --- # selector(3bobcat) Timed delays, Alarms and Multiple File I/O. ## NAME FBB::Selector - Timed delays, Alarms and Multiple File I/O. ## SYNOPSIS **#include \**\ Linking option: *-lbobcat* ## DESCRIPTION **FBB::Selector** objects are wrappers around the [**select**(2)](/select/2.md) system calls and allow timed delays, alarm functionality and/or multiple file I/O. It requires the use of *file descriptors*, which are not an official part of **C++**. However, most operating systems offer *file descriptors*. Sockets are well-known file descriptors. ## NAMESPACE **FBB**\ All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace **FBB**. ## INHERITS FROM \- ## CONSTRUCTORS - o **Selector()**:\ This constructor initializes the object. Copy and move constructors (and assignment operators) are available. ## MEMBER FUNCTIONS - o **void addExceptFd(int fd)**:\ Adds a filedescriptor to the set of file descriptors that are monitored for exceptions (note these are not **C++** exceptions. See *man 2* *select* for details). - o **void addReadFd(int fd)**:\ Adds a filedescriptor to the set of file descriptors that are monitored for reading. - o **void addWriteFd(int fd)**:\ Adds a filedescriptor to the set of file descriptors that are monitored for writing. - o **int exceptFd()**:\ Returns -1 of no more file descriptors are available in the *exception* category. Otherwise the next available file descriptor in the *exception* category is returned. Returning from *wait*, this function can be called repeatedly until -1 is returned, servicing each available filedescriptor in turn. - o **void noAlarm()**:\ This member prevents any timeout-alarm from occurring. - o **int nReady()**:\ Returns the number of available file descriptors. 0 is returned at a timeout, -1: is returned when [*select*(2)](/select/2.md) itself failed. - o **int readFd()**:\ Returns -1 of no more file descriptors are available for reading. Otherwise the next available file descriptor for reading is returned. Returning from *wait*, this function can be called repeatedly until -1 is returned, servicing each available filedescriptor in turn. Note that the file whose file descriptor is returned by *readFd* may also be at its end-of-file position. The file is \`ready for reading’, but no characters will be returned when trying to read from it due to its end-of-file status. In that case the file descriptor is probably best removed from the set of active file descriptors. - o **void rmExceptFd(int fd)**:\ Removes a filedescriptor from the set of file descriptors that are monitored for exceptions (note these are not **C++** exceptions. See *man 2* *select* for details). - o **void rmReadFd(int fd)**:\ Removes a filedescriptor from the set of file descriptors that are monitored for reading. - o **void rmWriteFd(int fd)**:\ Removes a filedescriptor from the set of file descriptors that are monitored for writing. - o **void setAlarm(int sec, int usec = 0)**:\ This member sets the alarm at the indicated seconds and micro-seconds. If no action occurred on one of the monitored file descriptions following the indicated amount of time, *wait* will return with *nReady* returning 0. The requested alarm time (*sec + usec / 1e+6*) may not be negative and may not exceed *std::numeric\_limits\::max()* or an *FBB::Exception* exception will be thrown. A 0 alarm time specification results in *wait* returning immediately. To switch off the alarm time use *noAlarm*. - o **int wait()**:\ This member should be called to wait for activities on the installed file descriptors or timeout-period. The members *exceptFd, nReady, readFd* and *writeFd* show their defined behaviors only after *wait* has returned. - It throws an *FBB::Exception* exception when [**select**(2)](/select/2.md) fails, which may very well indicate the end of any available input. An exception is also thrown if the program received a signal. - If *wait* returns normally its return value represents the number of available file descriptors. Note that *wait* may also return with an input file descriptor returned by *readFd* of a file at its end-of-file position. The file is \`ready for reading’, but no characters will be returned when trying to read from it due to its end-of-file status. - - o **int writeFd()**:\ Returns -1 of no more file descriptors are available for writing. Otherwise the next available file descriptor for writing is returned. Returning from *wait*, this function can be called repeatedly until -1 is returned, servicing each available filedescriptor in turn. ## EXAMPLE ``` #include #include #include #include using namespace std; using namespace FBB; int main(int argc, char **argv, char **envp) try { Selector selector; selector.setAlarm(5); // every 5 secs: alarm fires selector.addReadFd(STDIN_FILENO); // look also at cin while (true) { if (!selector.wait()) // 0: alarm fires cout << "Are you still there?" << endl; else { string s; if (!getline(cin, s) || !s.length()) return 0; cout << "Thank you for: " << s << endl; } } } catch (Exception const &e) { cout << e.what() << ’\n’; return 1; } ``` ## FILES *bobcat/selector* - defines the class interface ## SEE ALSO [**bobcat**(7)](/bobcat/7.md), [**select**(2)](/select/2.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**).