Provided by: libbobcat-dev_6.11.00-1_amd64 
NAME
FBB::Flock - allows multiple programs to synchronize access to the information they use
SYNOPSIS
#include <bobcat/classname>
Linking option: -lpthread -lbobcat
DESCRIPTION
When multiple programs need to access the same information (e.g., on files or in shared memory) then
accessing that information should be synchronized. While multiple programs can read the information in
parallel, only one program should be allowed to write/modify the information to avoid data corruption.
The class FBB::Flock allows program to synchronize reading/writing to files by locking access to an
existing (or newly created) lock file. Locking can be exclusive, in which case only one program can
access the information (commonly used when writing information), or shared, in which case multiple
programs can access the information (commonly used when reading information).
Using Flock’s locking facilities is comparable to using mutexes by multi-threaded programs: if programs
(or threads of multi-threaded programs) do not use locking facilities then those programs (or threads)
can break the data’s integrity. Consequently multiple programs accessing the same information should use
locking.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the
namespace FBB.
INHERITS FROM
-
CONSTRUCTORS
o Flock():
The default constructor initializes a Flock object. The object cannot yet offer synchronization
facilities since no lock file has been defined. See also the member setFilename below.
o Flock(std::string filename, mode_t mode = 0600):
This constructor initializes a an Flock object using filename as its lock file. Multiple programs
can specify the same file name, allowing them to synchronize their read/write actions. If filename
does not already exist it is created using access mode mode. Merely constructing a Flock object
does not activate locking. To (un)lock member functions are available (see below). )
Copy and move constructors (and assignment operators) are not available.
When an FBB::Flock object ceases to exist and the object has acquired a lock then the FBB::Flock’s
destructor releases the lock.
MEMBER FUNCTIONS
Requesting a shared lock succeeds if no other program has obtained an exclusive lock. Requesting an
exclusive lock succeeds if not other program has obtained eithr a shared or an exclusive lock.
o int fd() const:
The file descriptor associated with the current lock file is returned. If no lock file has been
specified -1 is returned.
o std::string const &filename() const:
The name of the lock file is returned. If no lockfile has been specified an empty string is
returned.
o void exclusive() const:
This member returns once the program has obtained an exclusive lock.
o bool exclusive(std::chrono::duration<Amount, Resolution> const &time):
Returns true when an exclusive lock was obtained within time time units, otherwise false is
returned. E.g., exclusive(4s) waits for at most four seconds to obtain a exclusive lock.
An exception is thrown if no lock file was specified.
o void setFilename(std::string const filename):
The FBB::Flock objects uses filename as its lock file name. If the object has currently acquired a
lock it is released. This member does not acquire a lock for filename.
o void shared() const:
This member returns once the program has obtained a shared lock.
o bool shared(std::chrono::duration<Amount, Resolution> const &time):
Returns true when a shared lock was obtained within time time units, otherwise false is returned.
E.g., shared(4s) waits for at most four seconds to obtain a shared lock.
An exception is thrown if no lock file was specified.
o void unlock() const:
This member releases the lock obtained by the Flock object.
An exception is thrown if no lock file was specified.
EXAMPLE
#include <iostream>
c
#include <bobcat/flock>
using namespace std;
using namespace FBB;
int main(int argc, char **argv)
try
{
if (argc < 3)
{
cerr << "need lockfile name and e or .\n";
return 1;
}
Flock flock{ argv[1] };
cout << "FD = " << flock.fd() << ’\n’;
if (string str; *argv[2] == ’e’)
{
flock.exclusive();
cout << "press Enter... ";
getline(cin, str);
}
else
{
bool ok = flock.exclusive(3s);
cout << "obtained a lock: " << ok << ’\n’;
if (ok)
{
cout << "press Enter... ";
getline(cin, str);
}
}
}
catch (...)
{
cerr << "caught an exception\n";
}
FILES
bobcat/flock - defines the class interface
SEE ALSO
bobcat(7), flock(2), the std::chrono namespace
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).
libbobcat-dev_6.11.00 2005-2025 FBB::Flock(3bobcat)