1c391d734c
The functionality that was prototyped in libglnx as glnx_fd_close
and then glnx_autofd was later added to GLib as g_autofd.
glnx_close_fd() doesn't have a direct equivalent in GLib, so keep
it intact, but using the backported _glnx_clear_fd_ignore_error as
its implementation. g_clear_fd() is the closest thing in GLib, but
g_clear_fd() guarantees to set errno on failure (making it useful for
error-checking), whereas glnx_close_fd() guarantees to leave errno
untouched, making it more useful for cleanup code paths that recover
from a syscall or similar function that sets errno:
int fd = ...;
success = (fsync (fd) == 0);
glnx_close_fd (&fd);
return success; /* if false, errno indicates why fsync failed */
(Of course in many cases, including this simple example, it would have
been easier to use g_autofd.)
glnx_autofd and glnx_fd_close are now equivalent to the backport of
g_autofd, so document them as deprecated. There's essentially no cost to
retaining them, so don't apply deprecation attributes.
Signed-off-by: Simon McVittie <smcv@collabora.com>
libglnx is the successor to libgsystem.
It is for modules which depend on both GLib and Linux, intended to be used as a git submodule.
Features:
- File APIs which use
openat()like APIs, but also take aGCancellableto support dynamic cancellation - APIs also have a
GErrorparameter - High level "shutil", somewhat inspired by Python's
- A "console" API for tty output
- A backport of the GLib cleanup macros for projects which can't yet take a dependency on 2.40.
Why?
There are multiple projects which have a hard dependency on Linux and GLib, such as NetworkManager, ostree, flatpak, etc. It makes sense for them to be able to share Linux-specific APIs.
This module also contains some code taken from systemd, which has very high quality LGPLv2+ shared library code, but most of the internal shared library is private, and not namespaced.
One could also compare this project to gnulib; the salient differences there are that at least some of this module is eventually destined for inclusion in GLib.
Adding this to your project
Meson
First, set up a Git submodule:
git submodule add https://gitlab.gnome.org/GNOME/libglnx subprojects/libglnx
Or a Git subtree:
git remote add libglnx https://gitlab.gnome.org/GNOME/libglnx.git
git fetch libglnx
git subtree add -P subprojects/libglnx libglnx/master
Then, in your top-level meson.build:
libglnx_dep = subproject('libglnx').get_variable('libglnx_dep')
# now use libglnx_dep in your dependencies
Porting from libgsystem
For all of the filesystem access code, libglnx exposes only
fd-relative API, not GFile*. It does use GCancellable where
applicable.
For local allocation macros, you should start using the g_auto
macros from GLib. A backport is included in libglnx. There are a few
APIs not defined in GLib yet, such as glnx_autofd.
gs_transfer_out_value is replaced by g_steal_pointer.
Contributing
Development happens in GNOME Gitlab: https://gitlab.gnome.org/GNOME/libglnx
(If you're seeing this on the Github mirror, we used to do development on Github but that was before GNOME deployed Gitlab.)