loc_database_reload(3)

Name

loc_database_reload, loc_database_set_reload_interval - Read the database again after it has been updated

Synopsis

#include <libloc/database.h>

int loc_database_reload(struct loc_database* db);

int loc_database_set_reload_interval(struct loc_database* db, unsigned int interval);

Description

A database is being updated by replacing its file with a new one. A process that has opened the database keeps using the old file until it is told otherwise.

loc_database_reload() checks whether the file at the path of the database is still the one that the database has been reading. If it is not, the new file is being read and used from then on.

This only works for databases that have been opened with loc_database_open() (see loc_database_new(3)), because only those know where their file is.

Those databases also do this on their own. Every five minutes, the first thread that uses the database after that time has passed checks whether there is a new file. All other threads carry on with the old file in the meantime and nobody has to wait. A database that is not being used does not check anything.

loc_database_set_reload_interval() changes how often this happens. The interval is in seconds, and zero turns it off, for those who would rather call loc_database_reload() themselves or who don’t want the database to change.

It is safe to call this function while other threads are using the database. Whoever is in the middle of looking something up finishes with the old file, which is being closed when the last one is done. An enumerator keeps the file that the database had when the enumerator has been created, so that it returns everything exactly once. Strings that have been returned by loc_database_get_vendor(), loc_database_get_description() and loc_database_get_license() remain valid until the database is being freed.

The signature of the new file is not being verified. Whoever has installed it is expected to have done that. Files that are not regular files or that everybody is allowed to write to are being refused.

The file of a database must never be changed in place. It has to be replaced, for example by writing the new database to a temporary file in the same directory and renaming that.

Return Value

Zero is returned if there was a new file which is being used now, and 1 if the file has not changed.

loc_database_set_reload_interval() returns zero on success.

On error, a negative error number (see errno(3)) is returned and the database carries on with the file that it has: -ENOTSUP if the database does not know where its file is, -EPERM if the new file is writable by everyone, or whatever was the reason why the new file could not be opened or read.

Authors