openkylin
/
glib2.0
mirror of https://gitee.com/openkylin/glib2.0.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge tag 'upstream/2.80.0' into packaging/openkylin/nile 

Upstream version 2.80.0
This commit is contained in:
Yue-Lan 2024-05-23 15:55:41 +08:00
parent a27f2d8237 64b07793cd
commit 23ccd7b431
939 changed files with 154682 additions and 63852 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

323
.gitlab-ci.yml
View File

@ -11,18 +11,19 @@ cache:
- _ccache/
variables:
FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v20"
FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v26"
COVERITY_IMAGE: "registry.gitlab.gnome.org/gnome/glib/coverity:v7"
DEBIAN_IMAGE: "registry.gitlab.gnome.org/gnome/glib/debian-stable:v14"
MINGW_IMAGE: "registry.gitlab.gnome.org/gnome/glib/mingw:v10"
DEBIAN_IMAGE: "registry.gitlab.gnome.org/gnome/glib/debian-stable:v19"
ALPINE_IMAGE: "registry.gitlab.gnome.org/gnome/glib/alpine:v3"
MINGW_IMAGE: "registry.gitlab.gnome.org/gnome/glib/mingw:v15"
MESON_TEST_TIMEOUT_MULTIPLIER: 4
G_MESSAGES_DEBUG: all
MESON_COMMON_OPTIONS: "--buildtype debug --wrap-mode=nodownload --fatal-meson-warnings"
# Default CI job setup; contrast with `.only-origin`.
#
# Don’t execute the pipeline when a merge request is merged into `main`, as it
# will have already been tested
# Don’t execute the pipeline when a merge request is merged into `origin/main`,
# as it will have already been tested
.only-default:
only:
- branches
@ -30,7 +31,16 @@ variables:
refs:
- tags
variables:
- $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PROJECT_NAMESPACE == "GNOME"
# As above, but does get executed on merge into `origin/main`. For use with
# updating code coverage results and docs builds.
.only-default-and-merges:
only:
- branches
except:
refs:
- tags
# Some jobs run on CI runners which don’t have good isolation between CI jobs,
# and don’t have much available resource. Limit those jobs to only ones on the
@ -51,61 +61,123 @@ variables:
except:
- tags
# Some jobs take a long time and are unlikely to find failures (or will find
# failures which are not merge-blockers to fix), so they’re executed on a weekly
# schedule in order to save CI resources and speed up branch pipelines.
# But for specific merge requests, one may still want to run them, so make
# possible to run them manually.
.only-schedules-or-manual:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
when: never
# As per rule before, the following rules will only apply to non MR events
- if: $CI_PIPELINE_SOURCE == "schedule"
when: always
- if: $CI_PIPELINE_SOURCE != "schedule"
when: manual
allow_failure: true
# Some jobs should be runnable only on schedules and when triggered by a branch
# in the origin repository, but without
.only-schedules-or-manual-in-default-branch:
rules:
- if: $CI_PROJECT_PATH != "GNOME/glib" || $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
when: never
# As per rule before, the following rules will apply only to GNOME/glib:main
- if: $CI_PIPELINE_SOURCE == "schedule"
when: always
- if: $CI_PIPELINE_SOURCE != "schedule"
when: manual
allow_failure: true
# Some jobs run on CI runners don’t have much available resource.
# Limit those jobs to only ones on the origin repository (GNOME/glib),
# rather than people’s forks or if ran manually.
.only-origin-or-manual:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
when: never
- if: $CI_PIPELINE_SOURCE == "schedule"
when: never
- if: $CI_PROJECT_NAMESPACE == "GNOME"
when: always
- if: $CI_PROJECT_NAMESPACE != "GNOME"
when: manual
allow_failure: true
.build-linux:
before_script:
- bash .gitlab-ci/show-execution-environment.sh
- cp -r $HOME/subprojects/* subprojects/
# FIXME: Work around https://gitlab.com/gitlab-org/gitlab/-/issues/391756
.only-default-with-git:
extends: .only-default
.with-git:
before_script:
- rm -rf subprojects/gvdb
- git config --global --add safe.directory "${PWD}"
- git submodule update --init --depth 1
variables:
GIT_SUBMODULE_STRATEGY: "none"
GIT_SUBMODULE_DEPTH: 1
style-check-advisory:
extends: .only-default-with-git
extends:
- .only-default
- .with-git
image: $DEBIAN_IMAGE
stage: style-check
allow_failure: true
script:
- .gitlab-ci/run-style-check-diff.sh
- .gitlab-ci/run-check-todos.sh
- failed=
- .gitlab-ci/run-style-check-diff.sh || failed=1
- .gitlab-ci/run-check-todos.sh || failed=1
- test -z "$failed"
sh-and-py-check:
extends: .only-default
extends:
- .only-default
- .with-git
image: $DEBIAN_IMAGE
stage: style-check
allow_failure: false
script:
- .gitlab-ci/run-shellcheck.sh
- .gitlab-ci/run-black.sh
- .gitlab-ci/run-flake8.sh
- failed=
- tests/shellcheck.sh || failed=1
- tests/black.sh || failed=1
- tests/flake8.sh || failed=1
- test -z "$failed"
variables:
LINT_WARNINGS_ARE_ERRORS: '1'
only:
changes:
- "**/*.py"
- "**/*.sh"
style-check-mandatory:
extends: .only-default-with-git
extends:
- .only-default
- .with-git
image: $DEBIAN_IMAGE
stage: style-check
allow_failure: false
script:
- .gitlab-ci/run-reuse.sh
- tests/reuse.sh
variables:
LINT_WARNINGS_ARE_ERRORS: '1'
fedora-x86_64:
extends:
- .build-linux
- .only-default
- .only-default-and-merges
- .with-git
image: $FEDORA_IMAGE
stage: build
needs: []
variables:
CFLAGS: "-coverage -ftest-coverage -fprofile-arcs"
before_script:
- !reference [".build-linux", "before_script"]
- !reference [".with-git", "before_script"]
script:
- meson setup ${MESON_COMMON_OPTIONS}
--werror
@ -116,13 +188,25 @@ fedora-x86_64:
-Dsystemtap=true
-Ddtrace=true
-Dinstalled_tests=true
-Dgtk_doc=true
-Ddocumentation=true
-Dintrospection=enabled
-Dman-pages=enabled
_build
- meson compile -C _build
- mkdir -p _coverage
- lcov --config-file .lcovrc --directory _build --capture --initial --output-file "_coverage/${CI_JOB_NAME}-baseline.lcov"
- .gitlab-ci/run-tests.sh
- lcov --config-file .lcovrc --directory _build --capture --output-file "_coverage/${CI_JOB_NAME}.lcov"
# Copy the built documentation to an artifact directory. The build for docs.gtk.org
# can then pull it from there — see https://gitlab.gnome.org/GNOME/gtk/-/blob/docs-gtk-org/README.md
- mkdir -p _reference/
- mv _build/docs/reference/glib/glib/ _reference/glib/
- mv _build/docs/reference/glib/glib-unix/ _reference/glib-unix/
- mv _build/docs/reference/gmodule/gmodule/ _reference/gmodule/
- mv _build/docs/reference/gobject/gobject/ _reference/gobject/
- mv _build/docs/reference/gio/gio/ _reference/gio/
- mv _build/docs/reference/gio/gio-unix/ _reference/gio-unix/
- mv _build/docs/reference/girepository/girepository/ _reference/girepository/
artifacts:
reports:
junit:
@ -135,24 +219,20 @@ fedora-x86_64:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
- "_build/docs/reference/glib/glib-undeclared.txt"
- "_build/docs/reference/glib/glib-undocumented.txt"
- "_build/docs/reference/glib/glib-unused.txt"
- "_build/docs/reference/gobject/gobject-undeclared.txt"
- "_build/docs/reference/gobject/gobject-undocumented.txt"
- "_build/docs/reference/gobject/gobject-unused.txt"
- "_build/docs/reference/gio/gio-undeclared.txt"
- "_build/docs/reference/gio/gio-undocumented.txt"
- "_build/docs/reference/gio/gio-unused.txt"
- "_coverage"
- "_reference"
debian-stable-x86_64:
extends:
- .build-linux
- .only-default
- .with-git
image: $DEBIAN_IMAGE
stage: build
needs: []
before_script:
- !reference [".build-linux", "before_script"]
- !reference [".with-git", "before_script"]
script:
- meson setup ${MESON_COMMON_OPTIONS}
--werror
@ -178,10 +258,81 @@ debian-stable-x86_64:
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
hurd-i386:
extends:
- .only-schedules-or-manual
- .with-git
stage: build
tags:
- hurd
needs: []
script:
# FIXME: We can’t use ${MESON_COMMON_OPTIONS} here because the Hurd runner
# has Meson 1.3 installed. See the comment below about the same problem on
# FreeBSD.
- meson setup
--buildtype debug
--wrap-mode=nodownload
--werror
--default-library=both
--prefix=$HOME/glib-installed
--localstatedir=/var
--libdir=lib
_build
- meson compile -C _build
- .gitlab-ci/run-tests.sh
artifacts:
reports:
junit:
- _build/meson-logs/testlog.junit.xml
- _build/meson-logs/testlog-*.junit.xml
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
expire_in: 1 week
paths:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
muslc-alpine-x86_64:
extends:
- .build-linux
- .only-schedules-or-manual
- .with-git
image: $ALPINE_IMAGE
stage: build
needs: []
before_script:
- !reference [".build-linux", "before_script"]
- !reference [".with-git", "before_script"]
script:
- meson setup ${MESON_COMMON_OPTIONS}
--werror
--default-library=both
--prefix=$HOME/glib-installed
--localstatedir=/var
--libdir=lib
-Dsystemtap=true
_build
- meson compile -C _build
- .gitlab-ci/run-tests.sh
artifacts:
reports:
junit:
- _build/meson-logs/testlog.junit.xml
- _build/meson-logs/testlog-*.junit.xml
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
expire_in: 1 week
paths:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
installed-tests:
extends:
- .build-linux
- .only-schedules
- .only-schedules-or-manual
image: $FEDORA_IMAGE
stage: build
needs: []
@ -219,10 +370,16 @@ installed-tests:
G_DISABLE_ASSERT:
extends:
- .build-linux
- .only-schedules
- .only-schedules-or-manual
- .with-git
image: $FEDORA_IMAGE
stage: build
needs: []
variables:
MESON_TEST_TIMEOUT_MULTIPLIER: 15
before_script:
- !reference [".build-linux", "before_script"]
- !reference [".with-git", "before_script"]
script:
- meson setup ${MESON_COMMON_OPTIONS}
--werror
@ -230,9 +387,11 @@ G_DISABLE_ASSERT:
-Ddtrace=true
-Dinstalled_tests=true
-Dglib_assert=false
-Dintrospection=enabled
_build
- meson compile -C _build
- bash -x ./.gitlab-ci/run-tests.sh
# Also take the opportunity to run the thorough tests (which are slow)
- bash -x ./.gitlab-ci/run-tests.sh --setup thorough
artifacts:
reports:
junit:
@ -249,18 +408,23 @@ G_DISABLE_ASSERT:
valgrind:
extends:
- .build-linux
- .only-schedules
- .only-schedules-or-manual
- .with-git
image: $FEDORA_IMAGE
stage: analysis
needs: []
variables:
MESON_TEST_TIMEOUT_MULTIPLIER: 15
before_script:
- !reference [".build-linux", "before_script"]
- !reference [".with-git", "before_script"]
script:
- meson setup ${MESON_COMMON_OPTIONS}
--werror
-Dsystemtap=true
-Ddtrace=true
-Dinstalled_tests=true
-Dintrospection=enabled
_build
- meson compile -C _build
# Valgrind doesn’t work when the soft FD limit is set too high
@ -329,7 +493,7 @@ cross-mingw64:
- _build/gobject/libgobject-2.0-0.dll
msys2-mingw32:
extends: .only-default
extends: .only-default-and-merges
stage: build
tags:
- win32-ps
@ -339,10 +503,6 @@ msys2-mingw32:
CHERE_INVOKING: "yes"
CFLAGS: -coverage -ftest-coverage -fprofile-arcs
PYTHONUTF8: "1"
# FIXME: For some reason enabling jit debugging "fixes" random python crashes
# see https://github.com/msys2/MINGW-packages/issues/11864 and
# https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3280#note_1678973
MSYS: "winjitdebug"
script:
- C:\msys64\usr\bin\pacman --noconfirm -Syyuu --ask 20
- C:\msys64\usr\bin\bash .gitlab-ci/show-execution-environment.sh
@ -358,9 +518,10 @@ msys2-mingw32:
paths:
- _build/meson-logs
- _coverage/
- _reference/
msys2-clang64:
extends: .only-schedules
extends: .only-schedules-or-manual
stage: build
tags:
- win32-ps
@ -369,10 +530,6 @@ msys2-clang64:
MSYSTEM: "CLANG64"
CHERE_INVOKING: "yes"
PYTHONUTF8: "1"
# FIXME: For some reason enabling jit debugging "fixes" random python crashes
# see https://github.com/msys2/MINGW-packages/issues/11864 and
# https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3280#note_1678973
MSYS: "winjitdebug"
script:
- C:\msys64\usr\bin\pacman --noconfirm -Syyuu --ask 20
- C:\msys64\usr\bin\bash .gitlab-ci/show-execution-environment.sh
@ -444,54 +601,8 @@ vs2017-x64-static:
paths:
- _build/meson-logs
freebsd-12-x86_64:
# The FreeBSD 13 build is run on each commit, so the FreeBSD 12 build can be
# run less regularly to save CI resources. The chance of a regression on
# FreeBSD 12 and not FreeBSD 13 is tiny.
extends: .only-schedules
stage: build
tags:
# To run a FreeBSD builder, install gitlab-runner package and start both
# gitlab-runner and dbus service because we need /var/lib/dbus/machine-id.
# To compile GLib, you still have to install the following packages:
# desktop-file-utils gettext libiconv meson pkgconf python3 shared-mime-info
- freebsd-12
needs: []
variables:
# CPPFLAGS is required because libintl doesn't use pkg-config.
CPPFLAGS: -I/usr/local/include
# FIXME: Workaround meson inability to set LD_LIBRARY_PATH.
# https://github.com/mesonbuild/meson/issues/1383
# https://github.com/mesonbuild/meson/issues/1635
# https://github.com/mesonbuild/meson/issues/2881
LDFLAGS: -L/usr/local/lib -Wl,--disable-new-dtags
# FreeBSD supports C.UTF-8 locale since 12.1.
LANG: C.UTF-8
before_script:
- bash .gitlab-ci/show-execution-environment.sh
script:
# We cannot use -Wl,--no-undefined because GLib uses 'environ' variable.
# FreeBSD supports xattr, but its API is different from Linux xattr.
# FIXME: extattr(2) support: https://gitlab.gnome.org/GNOME/glib/issues/1404
# localstatedir is needed for access to /var/lib/dbus/machine-id
- meson setup ${MESON_COMMON_OPTIONS} --localstatedir=/var -Db_lundef=false -Dxattr=false _build
- meson compile -C _build
- bash -x ./.gitlab-ci/run-tests.sh
artifacts:
reports:
junit:
- _build/meson-logs/testlog.junit.xml
- _build/meson-logs/testlog-*.junit.xml
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
expire_in: 1 week
paths:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
freebsd-13-x86_64:
extends: .only-origin
extends: .only-origin-or-manual
stage: build
tags:
- freebsd-13
@ -503,7 +614,14 @@ freebsd-13-x86_64:
before_script:
- bash .gitlab-ci/show-execution-environment.sh
script:
- meson setup ${MESON_COMMON_OPTIONS} --localstatedir=/var -Db_lundef=false -Dxattr=false _build
# FIXME: We can’t use ${MESON_COMMON_OPTIONS} here because the FreeBSD 13
# runner has Meson 1.3 installed. This has an API hole where previous
# methods of getting paths from files() objects are rejected as deprecated,
# but no replacements are available. Hence, we can’t build with
# --fatal-meson-warnings. This should be fixed in Meson 1.4. It’s also fine
# with Meson 1.2.3 (which is what we use on all the other CI runners).
# See https://github.com/GNOME/glib/commit/71061fdcb33b8c26f5f8467cb3ac10704d65c87d
- meson setup --buildtype debug --wrap-mode=nodownload --localstatedir=/var -Db_lundef=false -Dxattr=false _build
- meson compile -C _build
- bash -x ./.gitlab-ci/run-tests.sh
artifacts:
@ -520,6 +638,7 @@ freebsd-13-x86_64:
- "_build/meson-logs"
macos-x86_64:
# The macOS runner is not allowed in forks. This is about trust, not capacity.
extends: .only-origin
stage: build
tags:
@ -549,8 +668,9 @@ macos-x86_64:
- ln -s /opt/cmake/CMake.app/Contents/bin/cmake .venv/bin
- ln -s /opt/ccache/ccache .venv/bin
- source .venv/bin/activate
- pip3 install meson==1.2.0
- pip3 install meson==1.2.3
- pip3 install ninja==1.11.1
- pip3 install packaging==23.2
script:
# FIXME: Use --wrap-mode=default so we download dependencies each time,
# until the macOS runner is a VM where we can use a pre-made image which
@ -601,7 +721,7 @@ coverage:
scan-build:
extends:
- .build-linux
- .only-schedules
- .only-schedules-or-manual
image: $FEDORA_IMAGE
stage: analysis
needs: []
@ -615,6 +735,7 @@ scan-build:
-Dsystemtap=true
-Ddtrace=true
-Dinstalled_tests=true
-Dintrospection=enabled
_scan_build
- ninja -C _scan_build scan-build
artifacts:
@ -627,7 +748,7 @@ scan-build:
.coverity:
extends:
- .build-linux
- .only-schedules
- .only-schedules-or-manual-in-default-branch
image: $COVERITY_IMAGE
stage: analysis
needs: []
@ -644,6 +765,7 @@ scan-build:
-Dsystemtap=true
-Ddtrace=true
-Dinstalled_tests=true
-Dintrospection=enabled
_coverity_build
- $HOME/cov-analysis-linux64-*/bin/cov-build --dir cov-int meson compile -C _coverity_build
- tar cfz cov-int.tar.gz cov-int
@ -679,17 +801,22 @@ dist-job:
- git submodule update --init
- for m in $(git submodule foreach -q 'echo $path'); do git config --global --add safe.directory "${PWD}/${m}"; done
- meson subprojects download
- meson setup ${MESON_COMMON_OPTIONS} --buildtype release -Dgtk_doc=true -Dman=true _build
- meson setup ${MESON_COMMON_OPTIONS} --buildtype release -Ddocumentation=true -Dman-pages=enabled _build
- meson dist -C _build
- ninja -C _build glib-doc gobject-doc gio-doc
- tar -c -J -f "glib-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/glib html
- tar -c -J -f "gobject-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/gobject html
- tar -c -J -f "gio-docs-$CI_COMMIT_TAG.tar.xz" -C docs/reference/gio html
# Compile again to build the docs
- meson compile -C _build
- tar -c -J -f "glib-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/glib glib
- tar -c -J -f "gmodule-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gmodule gmodule
- tar -c -J -f "gobject-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gobject gobject
- tar -c -J -f "gio-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/gio gio
- tar -c -J -f "girepository-docs-$CI_COMMIT_TAG.tar.xz" -C _build/docs/reference/girepository girepository
artifacts:
paths:
- "${CI_PROJECT_DIR}/_build/glib-docs-$CI_COMMIT_TAG.tar.xz"
- "${CI_PROJECT_DIR}/_build/gmodule-docs-$CI_COMMIT_TAG.tar.xz"
- "${CI_PROJECT_DIR}/_build/gobject-docs-$CI_COMMIT_TAG.tar.xz"
- "${CI_PROJECT_DIR}/_build/gio-docs-$CI_COMMIT_TAG.tar.xz"
- "${CI_PROJECT_DIR}/_build/girepository-docs-$CI_COMMIT_TAG.tar.xz"
- "${CI_PROJECT_DIR}/_build/meson-dist/glib-*.tar.xz"
issue-bot:

38
.gitlab-ci/alpine.Dockerfile Normal file
View File

@ -0,0 +1,38 @@
FROM alpine:3.19
RUN apk add --no-cache \
bash \
build-base \
bzip2-dev \
dbus \
desktop-file-utils \
docbook-xml \
docbook-xsl \
gettext-dev \
git \
libffi-dev \
libxml2-utils \
libxslt \
meson \
musl-locales \
py3-pip \
python3 \
pcre2-dev \
shared-mime-info \
tzdata \
util-linux-dev \
zlib-dev
ENV LANG=C.UTF-8 LANGUAGE=C.UTF-8 LC_ALL=C.UTF-8 MUSL_LOCPATH=/usr/share/i18n/locales/musl
RUN pip3 install --break-system-packages meson==1.2.3
ARG HOST_USER_ID=5555
ENV HOST_USER_ID ${HOST_USER_ID}
RUN adduser -D -u $HOST_USER_ID -s /bin/bash user
USER user
WORKDIR /home/user
COPY cache-subprojects.sh .
RUN ./cache-subprojects.sh

31
.gitlab-ci/check-missing-install-tag.py
View File

@ -1,31 +0,0 @@
#!/usr/bin/env python3
"""
This script checks Meson configuration logs to verify no installed file is
missing installation tag.
"""
import argparse
import json
from pathlib import Path
def main():
parser = argparse.ArgumentParser()
parser.add_argument("builddir", type=Path)
args = parser.parse_args()
success = True
path = args.builddir / "meson-info" / "intro-install_plan.json"
with path.open(encoding="utf-8") as f:
install_plan = json.load(f)
for target in install_plan.values():
for info in target.values():
if not info["tag"]:
print("Missing install_tag for", info["destination"])
success = False
return 0 if success else 1
if __name__ == "__main__":
exit(main())

13
.gitlab-ci/debian-stable.Dockerfile
View File

@ -1,4 +1,4 @@
FROM debian:bullseye
FROM debian:bookworm
RUN apt-get update -qq && apt-get install --no-install-recommends -qq -y \
bindfs \
@ -16,8 +16,10 @@ RUN apt-get update -qq && apt-get install --no-install-recommends -qq -y \
gdb \
g++ \
gettext \
gi-docgen \
git \
libc6-dev \
gobject-introspection \
gtk-doc-tools \
itstool \
lcov \
@ -25,6 +27,7 @@ RUN apt-get update -qq && apt-get install --no-install-recommends -qq -y \
libdbus-1-dev \
libelf-dev \
libffi-dev \
libgirepository1.0-dev \
libmount-dev \
libpcre2-dev \
libselinux1-dev \
@ -34,9 +37,11 @@ RUN apt-get update -qq && apt-get install --no-install-recommends -qq -y \
locales \
ninja-build \
python3 \
python3-packaging \
python3-pip \
python3-setuptools \
python3-wheel \
reuse \
shared-mime-info \
shellcheck \
systemtap-sdt-dev \
@ -62,14 +67,12 @@ RUN locale-gen de_DE.UTF-8 \
&& locale-gen lt_LT.UTF-8 \
&& locale-gen pl_PL.UTF-8 \
&& locale-gen ru_RU.UTF-8 \
&& locale-gen th_TH.UTF-8 \
&& locale-gen tr_TR.UTF-8
ENV LANG=C.UTF-8 LANGUAGE=C.UTF-8 LC_ALL=C.UTF-8
RUN pip3 install meson==0.60.3
# FIXME: Once we use Debian Bookworm, we can just install the `reuse` package
RUN pip3 install reuse==1.0.0
RUN pip3 install --break-system-packages meson==1.2.3
ARG HOST_USER_ID=5555
ENV HOST_USER_ID ${HOST_USER_ID}

14
.gitlab-ci/fedora.Dockerfile
View File

@ -1,4 +1,4 @@
FROM fedora:34
FROM fedora:37
RUN dnf -y update \
&& dnf -y install \
@ -15,24 +15,28 @@ RUN dnf -y update \
gcc-c++ \
gdb \
gettext \
gi-docgen \
git \
glibc-devel \
glibc-gconv-extra \
glibc-headers \
glibc-langpack-de \
glibc-langpack-el \
glibc-langpack-el \
glibc-langpack-en \
glibc-langpack-es \
glibc-langpack-es \
glibc-langpack-fa \
glibc-langpack-fr \
glibc-langpack-gu \
glibc-langpack-hr \
glibc-langpack-ja \
glibc-langpack-lt \
glibc-langpack-pl \
glibc-langpack-ru \
glibc-langpack-th \
glibc-langpack-tr \
"gnome-desktop-testing >= 2018.1" \
gobject-introspection \
gobject-introspection-devel \
gtk-doc \
itstool \
lcov \
@ -45,6 +49,8 @@ RUN dnf -y update \
ninja-build \
pcre2-devel \
"python3-dbusmock >= 0.18.3-2" \
python3-docutils \
python3-packaging \
python3-pip \
python3-pygments \
python3-wheel \
@ -74,7 +80,7 @@ RUN dnf -y update \
make \
&& dnf clean all
RUN pip3 install meson==0.60.3
RUN pip3 install meson==1.2.3
COPY install-gitlab-cobertura-tools.sh .
RUN ./install-gitlab-cobertura-tools.sh

63
.gitlab-ci/mingw.Dockerfile
View File

@ -1,72 +1,17 @@
FROM fedora:34
FROM registry.gitlab.gnome.org/gnome/glib/fedora:v25
USER root
RUN dnf -y install \
bindfs \
clang \
clang-analyzer \
desktop-file-utils \
elfutils-libelf-devel \
findutils \
fuse \
gcc \
gcc-c++ \
gettext \
git \
glibc-devel \
glibc-headers \
glibc-langpack-de \
glibc-langpack-el \
glibc-langpack-el \
glibc-langpack-en \
glibc-langpack-es \
glibc-langpack-es \
glibc-langpack-fa \
glibc-langpack-fr \
glibc-langpack-hr \
glibc-langpack-ja \
glibc-langpack-lt \
glibc-langpack-pl \
glibc-langpack-ru \
glibc-langpack-tr \
gtk-doc \
itstool \
lcov \
libattr-devel \
libffi-devel \
libmount-devel \
libselinux-devel \
libxslt \
mingw64-gcc \
mingw64-gcc-c++ \
mingw64-gettext \
mingw64-libffi \
mingw64-zlib \
ncurses-compat-libs \
ninja-build \
pcre2-devel \
python3 \
python3-pip \
python3-wheel \
systemtap-sdt-devel \
unzip \
wget \
xz \
zlib-devel \
&& dnf clean all
WORKDIR /opt
COPY cross_file_mingw64.txt /opt
RUN pip3 install meson==0.60.3
ARG HOST_USER_ID=5555
ENV HOST_USER_ID ${HOST_USER_ID}
RUN useradd -u $HOST_USER_ID -ms /bin/bash user
USER user
WORKDIR /home/user
COPY cache-subprojects.sh .
RUN ./cache-subprojects.sh
ENV LANG C.UTF-8
WORKDIR /home/user

6
.gitlab-ci/run-black.sh
View File

@ -1,6 +0,0 @@
#!/bin/bash
set -e
# shellcheck disable=SC2046
black --diff --check $(git ls-files '*.py')

9
.gitlab-ci/run-flake8.sh
View File

@ -1,9 +0,0 @@
#!/bin/bash
set -e
# Disable formatting warnings in flake8, as we use `black` to handle that.
formatting_warnings=E101,E111,E114,E115,E116,E117,E12,E13,E2,E3,E401,E5,E70,W1,W2,W3,W5
# shellcheck disable=SC2046
flake8 --max-line-length=88 --ignore="$formatting_warnings" $(git ls-files '*.py')

7
.gitlab-ci/run-shellcheck.sh
View File

@ -1,7 +0,0 @@
#!/bin/bash
set -e
# Ignoring third-party directories that we don't want to parse
# shellcheck disable=SC2046
shellcheck $(git ls-files '*.sh' | grep -Ev "glib/libcharset|glib/dirent")

8
.gitlab-ci/run-style-check-diff.sh
View File

@ -2,17 +2,15 @@
set -e
ancestor_horizon=28 # days (4 weeks)
# Wrap everything in a subshell so we can propagate the exit status.
exit_status=0
(
source .gitlab-ci/search-common-ancestor.sh
git diff -U0 --no-color "${newest_common_ancestor_sha}" | .gitlab-ci/clang-format-diff.py -binary "clang-format-11" -p1
git diff -U0 --no-color "${newest_common_ancestor_sha}" | .gitlab-ci/clang-format-diff.py -binary "clang-format-14" -p1
)
exit_status=$?
) || exit_status=$?
# The style check is not infallible. The clang-format configuration cannot
# perfectly describe GLib’s coding style: in particular, it cannot align

2
.gitlab-ci/run-tests.sh
View File

@ -2,8 +2,6 @@
set -ex
./.gitlab-ci/check-missing-install-tag.py _build
meson test -v \
-C _build \
--timeout-multiplier "${MESON_TEST_TIMEOUT_MULTIPLIER}" \

12
.gitlab-ci/test-msvc.bat
View File

@ -12,25 +12,15 @@ for %%x in (%*) do (
set args=%args:~1%
:: FIXME: make warnings fatal
pip3 install --upgrade --user meson==1.0.0 || goto :error
pip3 install --upgrade --user meson==1.2.3 packaging==23.2 || goto :error
meson setup %args% _build || goto :error
python .gitlab-ci/check-missing-install-tag.py _build || goto :error
meson compile -C _build || goto :error
meson test -v -C _build --timeout-multiplier %MESON_TEST_TIMEOUT_MULTIPLIER% || goto :error
meson test -v -C _build --timeout-multiplier %MESON_TEST_TIMEOUT_MULTIPLIER% --setup=unstable_tests --suite=failing --suite=flaky
:: Workaround meson issue https://github.com/mesonbuild/meson/issues/9894
python -c "n = '_build/meson-logs/testlog.junit.xml'; c = open(n, 'rb').read().replace(b'\x1b', b''); open(n, 'wb').write(c)" || goto :error
python -c "n = '_build/meson-logs/testlog-unstable_tests.junit.xml'; c = open(n, 'rb').read().replace(b'\x1b', b''); open(n, 'wb').write(c)"
:: FIXME: can we get code coverage support?
goto :EOF
:error
:: Workaround meson issue https://github.com/mesonbuild/meson/issues/9894
python -c "n = '_build/meson-logs/testlog.junit.xml'; c = open(n, 'rb').read().replace(b'\x1b', b''); open(n, 'wb').write(c)"
python -c "n = '_build/meson-logs/testlog-unstable_tests.junit.xml'; c = open(n, 'rb').read().replace(b'\x1b', b''); open(n, 'wb').write(c)"
exit /b 1

31
.gitlab-ci/test-msys2.sh
View File

@ -11,10 +11,13 @@ pacman --noconfirm -S --needed \
lcov \
"${MINGW_PACKAGE_PREFIX}"-ccache \
"${MINGW_PACKAGE_PREFIX}"-gettext \
"${MINGW_PACKAGE_PREFIX}"-gi-docgen \
"${MINGW_PACKAGE_PREFIX}"-gobject-introspection \
"${MINGW_PACKAGE_PREFIX}"-libffi \
"${MINGW_PACKAGE_PREFIX}"-meson \
"${MINGW_PACKAGE_PREFIX}"-pcre2 \
"${MINGW_PACKAGE_PREFIX}"-python3 \
"${MINGW_PACKAGE_PREFIX}"-python-docutils \
"${MINGW_PACKAGE_PREFIX}"-python-pip \
"${MINGW_PACKAGE_PREFIX}"-toolchain \
"${MINGW_PACKAGE_PREFIX}"-zlib \
@ -26,20 +29,24 @@ CCACHE_BASEDIR="$(pwd)"
CCACHE_DIR="${CCACHE_BASEDIR}/_ccache"
export CCACHE_BASEDIR CCACHE_DIR
pip3 install --upgrade --user meson==1.0.0
pip3 install --upgrade --user packaging==23.2
PATH="$(cygpath "$USERPROFILE")/.local/bin:$HOME/.local/bin:$PATH"
DIR="$(pwd)"
export PATH CFLAGS
if [[ "$MSYSTEM" == "CLANG64" ]]; then
# FIXME: fix the clang build warnings
# shellcheck disable=SC2086
meson setup ${MESON_COMMON_OPTIONS} _build
else
# shellcheck disable=SC2086
meson setup ${MESON_COMMON_OPTIONS} --werror _build
fi
# FIXME: We can’t use ${MESON_COMMON_OPTIONS} here because this script installs
# Meson 1.3. See the comment in .gitlab-ci.yml about the same problem on
# FreeBSD.
# shellcheck disable=SC2086
meson setup \
--buildtype=debug \
--wrap-mode=nodownload \
--werror \
-Ddocumentation=true \
-Dintrospection=enabled \
-Dman-pages=enabled \
_build
meson compile -C _build
@ -65,3 +72,9 @@ if [[ "$CFLAGS" == *"-coverage"* ]]; then
--capture \
--output-file "${DIR}/_coverage/${CI_JOB_NAME}.lcov"
fi
# Copy the built documentation to an artifact directory. The build for docs.gtk.org
# can then pull it from there — see https://gitlab.gnome.org/GNOME/gtk/-/blob/docs-gtk-org/README.md
mkdir -p _reference/
mv _build/docs/reference/glib/glib-win32/ _reference/glib-win32/
mv _build/docs/reference/gio/gio-win32/ _reference/gio-win32/

22
.gitlab-ci/thorough-test-wrapper.sh Normal file
View File

@ -0,0 +1,22 @@
#!/bin/bash
#
# Copyright 2024 GNOME Foundation, Inc.
#
# SPDX-License-Identifier: LGPL-2.1-or-later
#
# Original author: Philip Withnall
set -e
# If the test is run under Python (e.g. the first argument to this script is
# /usr/bin/python3) or if it’s the special xmllint test in GLib, then don’t
# pass the GTest `-m thorough` argument to it.
if [[ "$1" == *"python"* ||
"$1" == *"xmllint" ]]; then
args=()
else
# See the documentation for g_test_init()
args=("-m" "thorough")
fi
exec "$@" "${args[@]}"

7
.lcovrc
View File

@ -1,13 +1,16 @@
# lcov and genhtml configuration
# See http://ltp.sourceforge.net/coverage/lcov/lcovrc.5.php
# See lcovrc(5)
# Always enable branch coverage
lcov_branch_coverage = 1
# Exclude precondition assertions, as we can never reasonably get full branch
# coverage of them, as they should never normally fail.
# Similarly exclude g_clear_*() functions (such as g_clear_object(),
# g_clear_pointer(), etc.) as it’s not useful to test both sides of the branch
# in them.
# See https://github.com/linux-test-project/lcov/issues/44
lcov_excl_br_line = LCOV_EXCL_BR_LINE|g_return_if_fail|g_return_val_if_fail|g_assert|g_assert_
lcov_excl_br_line = LCOV_EXCL_BR_LINE|g_return_if_fail|g_return_val_if_fail|g_assert|g_assert_|g_clear_
# Similarly for unreachable assertions.
lcov_excl_line = LCOV_EXCL_LINE|g_return_if_reached|g_return_val_if_reached|g_assert_not_reached

19
.reuse/dep5
View File

@ -41,3 +41,22 @@ License: CC0-1.0
Files: docs/reference/glib/gvariant-*.svg
Copyright: 2022 Philip Withnall
License: CC-BY-SA-3.0
# libgirepository uses cmph as a copylib. Adding copyright/license data to the
# files there would cause divergence from upstream. See
# girepository/cmph/README-CMPH-IMPORT.txt.
Files: girepository/cmph/*
Copyright: CMPH contributors
License: LGPL-2.1-only or MPL-1.1
# gnulib is a copylib. Adding copyright/license data to the files there would
# cause divergence from upstream. See glib/gnulib/README.
Files: glib/gnulib/*
Copyright: gnulib contributors
License: LGPL-2.1-or-later
# libcharset is a copylib. Adding copyright/license data to the files there
# would cause divergence from upstream. See glib/libcharset/README.
Files: glib/libcharset/*
Copyright: libcharset contributors
License: LGPL-2.1-or-later

175
LICENSES/LGPL-2.1-only.txt Normal file
View File

@ -0,0 +1,175 @@
GNU LESSER GENERAL PUBLIC LICENSE
Version 2.1, February 1999
Copyright (C) 1991, 1999 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
[This is the first released version of the Lesser GPL. It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.]
Preamble
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users.
This license, the Lesser General Public License, applies to some specially designated software packages--typically libraries--of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below.
When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things.
To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it.
For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link other code with the library, you must provide complete object files to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them these terms so they know their rights.
We protect your rights with a two-step method: (1) we copyright the library, and (2) we offer you this license, which gives you legal permission to copy, distribute and/or modify the library.
To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modified by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by others.
Finally, software patents pose a constant threat to the existence of any free program. We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license.
Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those libraries into non-free programs.
When a program is linked with a library, whether statically or using a shared library, the combination of the two is legally speaking a combined work, a derivative of the original library. The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library.
We call this license the "Lesser" General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances.
For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that a free library does the same job as widely used non-free libraries. In this case, there is little to gain by limiting the free library to free software only, so we use the Lesser General Public License.
In other cases, permission to use a particular library in non-free programs enables a greater number of people to use a large body of free software. For example, permission to use the GNU C Library in non-free programs enables many more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating system.
Although the Lesser General Public License is Less protective of the users' freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library.
The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, whereas the latter must be combined with the library in order to run.
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called "this License"). Each licensee is addressed as "you".
A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.
The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".)
"Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library.
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.
1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
a) The modified work must itself be a software library.
b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.
c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.
d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful.
(For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.
In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices.
Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of the Library into a program that is not a library.
4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange.
If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code.
5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License.
However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables.
When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.
6. As an exception to the Sections above, you may also combine or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:
a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)
b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with.
c) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution.
d) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place.
e) Verify that the user has already received a copy of these materials or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.
7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:
a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above.
b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.
8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.
10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License.
11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.
14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
NO WARRANTY
15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License).
To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.
one line to give the library's name and an idea of what it does.
Copyright (C) year name of author
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in
the library `Frob' (a library for tweaking knobs) written
by James Random Hacker.
signature of Ty Coon, 1 April 1990
Ty Coon, President of Vice
That's all there is to it!

143
LICENSES/MPL-1.1.txt Normal file
View File

@ -0,0 +1,143 @@
Mozilla Public License Version 1.1
1. Definitions.
1.0.1. "Commercial Use" means distribution or otherwise making the Covered Code available to a third party.
1.1. "Contributor" means each entity that creates or contributes to the creation of Modifications.
1.2. "Contributor Version" means the combination of the Original Code, prior Modifications used by a Contributor, and the Modifications made by that particular Contributor.
1.3. "Covered Code" means the Original Code or Modifications or the combination of the Original Code and Modifications, in each case including portions thereof.
1.4. "Electronic Distribution Mechanism" means a mechanism generally accepted in the software development community for the electronic transfer of data.
1.5. "Executable" means Covered Code in any form other than Source Code.
1.6. "Initial Developer" means the individual or entity identified as the Initial Developer in the Source Code notice required by Exhibit A.
1.7. "Larger Work" means a work which combines Covered Code or portions thereof with code not governed by the terms of this License.
1.8. "License" means this document.
1.8.1. "Licensable" means having the right to grant, to the maximum extent possible, whether at the time of the initial grant or subsequently acquired, any and all of the rights conveyed herein.
1.9. "Modifications" means any addition to or deletion from the substance or structure of either the Original Code or any previous Modifications. When Covered Code is released as a series of files, a Modification is:
Any addition to or deletion from the contents of a file containing Original Code or previous Modifications.
Any new file that contains any part of the Original Code or previous Modifications.
1.10. "Original Code" means Source Code of computer software code which is described in the Source Code notice required by Exhibit A as Original Code, and which, at the time of its release under this License is not already Covered Code governed by this License.
1.10.1. "Patent Claims" means any patent claim(s), now owned or hereafter acquired, including without limitation, method, process, and apparatus claims, in any patent Licensable by grantor.
1.11. "Source Code" means the preferred form of the Covered Code for making modifications to it, including all modules it contains, plus any associated interface definition files, scripts used to control compilation and installation of an Executable, or source code differential comparisons against either the Original Code or another well known, available Covered Code of the Contributor's choice. The Source Code can be in a compressed or archival form, provided the appropriate decompression or de-archiving software is widely available for no charge.
1.12. "You" (or "Your") means an individual or a legal entity exercising rights under, and complying with all of the terms of, this License or a future version of this License issued under Section 6.1. For legal entities, "You" includes any entity which controls, is controlled by, or is under common control with You. For purposes of this definition, "control" means (a) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (b) ownership of more than fifty percent (50%) of the outstanding shares or beneficial ownership of such entity.
2. Source Code License.
2.1. The Initial Developer Grant. The Initial Developer hereby grants You a world-wide, royalty-free, non-exclusive license, subject to third party intellectual property claims:
a. under intellectual property rights (other than patent or trademark) Licensable by Initial Developer to use, reproduce, modify, display, perform, sublicense and distribute the Original Code (or portions thereof) with or without Modifications, and/or as part of a Larger Work; and
b. under Patents Claims infringed by the making, using or selling of Original Code, to make, have made, use, practice, sell, and offer for sale, and/or otherwise dispose of the Original Code (or portions thereof).
c. the licenses granted in this Section 2.1 (a) and (b) are effective on the date Initial Developer first distributes Original Code under the terms of this License.
d. Notwithstanding Section 2.1 (b) above, no patent license is granted: 1) for code that You delete from the Original Code; 2) separate from the Original Code; or 3) for infringements caused by: i) the modification of the Original Code or ii) the combination of the Original Code with other software or devices.
2.2. Contributor Grant. Subject to third party intellectual property claims, each Contributor hereby grants You a world-wide, royalty-free, non-exclusive license
a. under intellectual property rights (other than patent or trademark) Licensable by Contributor, to use, reproduce, modify, display, perform, sublicense and distribute the Modifications created by such Contributor (or portions thereof) either on an unmodified basis, with other Modifications, as Covered Code and/or as part of a Larger Work; and
b. under Patent Claims infringed by the making, using, or selling of Modifications made by that Contributor either alone and/or in combination with its Contributor Version (or portions of such combination), to make, use, sell, offer for sale, have made, and/or otherwise dispose of: 1) Modifications made by that Contributor (or portions thereof); and 2) the combination of Modifications made by that Contributor with its Contributor Version (or portions of such combination).
c. the licenses granted in Sections 2.2 (a) and 2.2 (b) are effective on the date Contributor first makes Commercial Use of the Covered Code.
d. Notwithstanding Section 2.2 (b) above, no patent license is granted: 1) for any code that Contributor has deleted from the Contributor Version; 2) separate from the Contributor Version; 3) for infringements caused by: i) third party modifications of Contributor Version or ii) the combination of Modifications made by that Contributor with other software (except as part of the Contributor Version) or other devices; or 4) under Patent Claims infringed by Covered Code in the absence of Modifications made by that Contributor.
3. Distribution Obligations.
3.1. Application of License. The Modifications which You create or to which You contribute are governed by the terms of this License, including without limitation Section 2.2. The Source Code version of Covered Code may be distributed only under the terms of this License or a future version of this License released under Section 6.1, and You must include a copy of this License with every copy of the Source Code You distribute. You may not offer or impose any terms on any Source Code version that alters or restricts the applicable version of this License or the recipients' rights hereunder. However, You may include an additional document offering the additional rights described in Section 3.5.
3.2. Availability of Source Code. Any Modification which You create or to which You contribute must be made available in Source Code form under the terms of this License either on the same media as an Executable version or via an accepted Electronic Distribution Mechanism to anyone to whom you made an Executable version available; and if made available via Electronic Distribution Mechanism, must remain available for at least twelve (12) months after the date it initially became available, or at least six (6) months after a subsequent version of that particular Modification has been made available to such recipients. You are responsible for ensuring that the Source Code version remains available even if the Electronic Distribution Mechanism is maintained by a third party.
3.3. Description of Modifications. You must cause all Covered Code to which You contribute to contain a file documenting the changes You made to create that Covered Code and the date of any change. You must include a prominent statement that the Modification is derived, directly or indirectly, from Original Code provided by the Initial Developer and including the name of the Initial Developer in (a) the Source Code, and (b) in any notice in an Executable version or related documentation in which You describe the origin or ownership of the Covered Code.
3.4. Intellectual Property Matters
(a) Third Party Claims
If Contributor has knowledge that a license under a third party's intellectual property rights is required to exercise the rights granted by such Contributor under Sections 2.1 or 2.2, Contributor must include a text file with the Source Code distribution titled "LEGAL" which describes the claim and the party making the claim in sufficient detail that a recipient will know whom to contact. If Contributor obtains such knowledge after the Modification is made available as described in Section 3.2, Contributor shall promptly modify the LEGAL file in all copies Contributor makes available thereafter and shall take other steps (such as notifying appropriate mailing lists or newsgroups) reasonably calculated to inform those who received the Covered Code that new knowledge has been obtained.
(b) Contributor APIs
If Contributor's Modifications include an application programming interface and Contributor has knowledge of patent licenses which are reasonably necessary to implement that API, Contributor must also include this information in the LEGAL file.
(c) Representations.
Contributor represents that, except as disclosed pursuant to Section 3.4 (a) above, Contributor believes that Contributor's Modifications are Contributor's original creation(s) and/or Contributor has sufficient rights to grant the rights conveyed by this License.
3.5. Required Notices. You must duplicate the notice in Exhibit A in each file of the Source Code. If it is not possible to put such notice in a particular Source Code file due to its structure, then You must include such notice in a location (such as a relevant directory) where a user would be likely to look for such a notice. If You created one or more Modification(s) You may add your name as a Contributor to the notice described in Exhibit A. You must also duplicate this License in any documentation for the Source Code where You describe recipients' rights or ownership rights relating to Covered Code. You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations to one or more recipients of Covered Code. However, You may do so only on Your own behalf, and not on behalf of the Initial Developer or any Contributor. You must make it absolutely clear than any such warranty, support, indemnity or liability obligation is offered by You alone, and You hereby agree to indemnify the Initial Developer and every Contributor for any liability incurred by the Initial Developer or such Contributor as a result of warranty, support, indemnity or liability terms You offer.
3.6. Distribution of Executable Versions. You may distribute Covered Code in Executable form only if the requirements of Sections 3.1, 3.2, 3.3, 3.4 and 3.5 have been met for that Covered Code, and if You include a notice stating that the Source Code version of the Covered Code is available under the terms of this License, including a description of how and where You have fulfilled the obligations of Section 3.2. The notice must be conspicuously included in any notice in an Executable version, related documentation or collateral in which You describe recipients' rights relating to the Covered Code. You may distribute the Executable version of Covered Code or ownership rights under a license of Your choice, which may contain terms different from this License, provided that You are in compliance with the terms of this License and that the license for the Executable version does not attempt to limit or alter the recipient's rights in the Source Code version from the rights set forth in this License. If You distribute the Executable version under a different license You must make it absolutely clear that any terms which differ from this License are offered by You alone, not by the Initial Developer or any Contributor. You hereby agree to indemnify the Initial Developer and every Contributor for any liability incurred by the Initial Developer or such Contributor as a result of any such terms You offer.
3.7. Larger Works. You may create a Larger Work by combining Covered Code with other code not governed by the terms of this License and distribute the Larger Work as a single product. In such a case, You must make sure the requirements of this License are fulfilled for the Covered Code.
4. Inability to Comply Due to Statute or Regulation.
If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Code due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) describe the limitations and the code they affect. Such description must be included in the LEGAL file described in Section 3.4 and must be included with all distributions of the Source Code. Except to the extent prohibited by statute or regulation, such description must be sufficiently detailed for a recipient of ordinary skill to be able to understand it.
5. Application of this License.
This License applies to code to which the Initial Developer has attached the notice in Exhibit A and to related Covered Code.
6. Versions of the License.
6.1. New Versions
Netscape Communications Corporation ("Netscape") may publish revised and/or new versions of the License from time to time. Each version will be given a distinguishing version number.
6.2. Effect of New Versions
Once Covered Code has been published under a particular version of the License, You may always continue to use it under the terms of that version. You may also choose to use such Covered Code under the terms of any subsequent version of the License published by Netscape. No one other than Netscape has the right to modify the terms applicable to Covered Code created under this License.
6.3. Derivative Works
If You create or use a modified version of this License (which you may only do in order to apply it to code which is not already Covered Code governed by this License), You must (a) rename Your license so that the phrases "Mozilla", "MOZILLAPL", "MOZPL", "Netscape", "MPL", "NPL" or any confusingly similar phrase do not appear in your license (except to note that your license differs from this License) and (b) otherwise make it clear that Your version of the license contains terms which differ from the Mozilla Public License and Netscape Public License. (Filling in the name of the Initial Developer, Original Code or Contributor in the notice described in Exhibit A shall not of themselves be deemed to be modifications of this License.)
7. DISCLAIMER OF WARRANTY
COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE COVERED CODE IS FREE OF DEFECTS, MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE COVERED CODE IS WITH YOU. SHOULD ANY COVERED CODE PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL DEVELOPER OR ANY OTHER CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.
8. Termination
8.1. This License and the rights granted hereunder will terminate automatically if You fail to comply with terms herein and fail to cure such breach within 30 days of becoming aware of the breach. All sublicenses to the Covered Code which are properly granted shall survive any termination of this License. Provisions which, by their nature, must remain in effect beyond the termination of this License shall survive.
8.2. If You initiate litigation by asserting a patent infringement claim (excluding declatory judgment actions) against Initial Developer or a Contributor (the Initial Developer or Contributor against whom You file such action is referred to as "Participant") alleging that:
a. such Participant's Contributor Version directly or indirectly infringes any patent, then any and all rights granted by such Participant to You under Sections 2.1 and/or 2.2 of this License shall, upon 60 days notice from Participant terminate prospectively, unless if within 60 days after receipt of notice You either: (i) agree in writing to pay Participant a mutually agreeable reasonable royalty for Your past and future use of Modifications made by such Participant, or (ii) withdraw Your litigation claim with respect to the Contributor Version against such Participant. If within 60 days of notice, a reasonable royalty and payment arrangement are not mutually agreed upon in writing by the parties or the litigation claim is not withdrawn, the rights granted by Participant to You under Sections 2.1 and/or 2.2 automatically terminate at the expiration of the 60 day notice period specified above.
b. any software, hardware, or device, other than such Participant's Contributor Version, directly or indirectly infringes any patent, then any rights granted to You by such Participant under Sections 2.1(b) and 2.2(b) are revoked effective as of the date You first made, used, sold, distributed, or had made, Modifications made by that Participant.
8.3. If You assert a patent infringement claim against Participant alleging that such Participant's Contributor Version directly or indirectly infringes any patent where such claim is resolved (such as by license or settlement) prior to the initiation of patent infringement litigation, then the reasonable value of the licenses granted by such Participant under Sections 2.1 or 2.2 shall be taken into account in determining the amount or value of any payment or license.
8.4. In the event of termination under Sections 8.1 or 8.2 above, all end user license agreements (excluding distributors and resellers) which have been validly granted by You or any distributor hereunder prior to termination shall survive termination.
9. LIMITATION OF LIABILITY
UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL YOU, THE INITIAL DEVELOPER, ANY OTHER CONTRIBUTOR, OR ANY DISTRIBUTOR OF COVERED CODE, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. THIS LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY RESULTING FROM SUCH PARTY'S NEGLIGENCE TO THE EXTENT APPLICABLE LAW PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS EXCLUSION AND LIMITATION MAY NOT APPLY TO YOU.
10. U.S. government end users
The Covered Code is a "commercial item," as that term is defined in 48 C.F.R. 2.101 (Oct. 1995), consisting of "commercial computer software" and "commercial computer software documentation," as such terms are used in 48 C.F.R. 12.212 (Sept. 1995). Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4 (June 1995), all U.S. Government End Users acquire Covered Code with only those rights set forth herein.
11. Miscellaneous
This License represents the complete agreement concerning subject matter hereof. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. This License shall be governed by California law provisions (except to the extent applicable law, if any, provides otherwise), excluding its conflict-of-law provisions. With respect to disputes in which at least one party is a citizen of, or an entity chartered or registered to do business in the United States of America, any litigation relating to this License shall be subject to the jurisdiction of the Federal Courts of the Northern District of California, with venue lying in Santa Clara County, California, with the losing party responsible for costs, including without limitation, court costs and reasonable attorneys' fees and expenses. The application of the United Nations Convention on Contracts for the International Sale of Goods is expressly excluded. Any law or regulation which provides that the language of a contract shall be construed against the drafter shall not apply to this License.
12. Responsibility for claims
As between Initial Developer and the Contributors, each party is responsible for claims and damages arising, directly or indirectly, out of its utilization of rights under this License and You agree to work with Initial Developer and Contributors to distribute such responsibility on an equitable basis. Nothing herein is intended or shall be deemed to constitute any admission of liability.
13. Multiple-licensed code
Initial Developer may designate portions of the Covered Code as "Multiple-Licensed". "Multiple-Licensed" means that the Initial Developer permits you to utilize portions of the Covered Code under Your choice of the MPL or the alternative licenses, if any, specified by the Initial Developer in the file described in Exhibit A.
Exhibit A - Mozilla Public License.
"The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Original Code is ______________________________________.
The Initial Developer of the Original Code is ________________________.
Portions created by ______________________ are Copyright (C) ______
_______________________. All Rights Reserved.
Contributor(s): ______________________________________.
Alternatively, the contents of this file may be used under the terms of the _____ license (the "[___] License"), in which case the provisions of [______] License are applicable instead of those above. If you wish to allow use of your version of this file only under the terms of the [____] License and not to allow others to use your version of this file under the MPL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the [___] License. If you do not delete the provisions above, a recipient may use your version of this file under either the MPL or the [___] License."
NOTE: The text of this Exhibit A may differ slightly from the text of the notices in the Source Code files of the Original Code. You should use the text of this Exhibit A rather than the text found in the Original Code Source Code for Your Modifications.

573
NEWS
View File

@ -1,85 +1,518 @@
Overview of changes in GLib 2.78.3, 2023-12-06
==============================================
* Fix a crash-causing regression in xdgmime (#3191, work by Philip Withnall)
* Bugs fixed:
- #3191 Crash in __gio_xdg_cache_mime_type_subclass (Philip Withnall)
- !3747 Backport !3742 “xdgmime: Update to upstream commit c2c814d4051f232” to
glib-2-78
Overview of changes in GLib 2.78.2, 2023-12-05
Overview of changes in GLib 2.80.0, 2024-03-07
==============================================
* Bugs fixed:
- #3271 GLib: string malformed for gettext (Philip Withnall)
- !3940 tests: Don’t run check-missing-install-tag.py test under valgrind
(Philip Withnall)
- !3946 Add missing argument placeholders to several command-line tools (Simon
McVittie)
- !3947 docs: Fix a typo in the macros docs page (Philip Withnall)
- !3951 g_warn_if_fail: Document as always evaluating expr (Simon McVittie)
- !3953 docs: Specify gi-docgen as a native dependency (Bobby Rong)
- !3955 docs: Fix building with docs enabled and introspection disabled (Bobby
Rong)
- !3956 docs: Minor improvements to GSignal documentation (Philip Withnall)
* Translation updates:
- Basque (Asier Sarasua Garmendia)
- British English (Andi Chandler, Bruce Cowan)
- Chinese (China) (Luming Zh)
- Czech (Daniel Rusek)
- Georgian (Ekaterine Papava)
- Hebrew (Yaron Shahrabani)
- Hungarian (Balázs Úr)
- Kazakh (Baurzhan Muftakhidinov)
- Lithuanian (Aurimas Černius)
- Norwegian Bokmål (Brage Fuglseth)
- Persian (Danial Behzadi)
- Russian (Artur S0)
- Slovenian (Matej Urbančič)
- Spanish (Daniel Mustieles)
- Swedish (Anders Jonsson)
- Turkish (Sabri Ünal)
- Ukrainian (Yuri Chornoivan)
Overview of changes in GLib 2.79.3, 2024-02-27
==============================================
* Various consistency improvements to the command line libgirepository tools
(!3926, !3927, !3928, !3930, work by Simon McVittie)
* Bugs fixed:
- #3080 Gimp GTK file chooser hang when a remote file is open (Luca Bacci)
- #3210 Critical using Open location: GWinHttpFile doesn’t set
G_FILE_ATTRIBUTE_STANDARD_TYPE (Luca Bacci)
- #3252 [2.79.1] gdatetime installed tests fails on s390x (Simon McVittie)
- #3255 g_base_info_clear on zero-initialized stack-allocated introspection
info (Philip Withnall)
- #3258 Possible memory leak in GUnixVolumeMonitor (Ondrej Holy)
- #3260 Add man pages for girepository tools
- #3262 msys2-mingw32 build failing with error code 3221225785 (0xc0000139)
(Philip Withnall)
- #3263 Ensure girepository tools are translatable (Philip Withnall)
- #3266 Use-after-free in gsocketclient.c:connection_attempt_remove() (Philip
Withnall)
- #3271 GLib: string malformed for gettext (Philip Withnall)
- !3918 tests: Don’t run lint tests under valgrind
- !3919 tests: Speed up threaded toggle notify test unless -m slow is passed
- !3921 ci: Fix printing the execution environment
- !3922 gdatetime test: Produce more helpful output on mismatches
- !3923 girepository test: Don't assume doubles are naturally-aligned
- !3925 girwriter: Take the GIRepository as a parameter
- !3926 gi- tools: Remove unused options, improve --debug/--verbose
- !3927 g-ir-compiler: Only accept one input file
- !3928 gi-decompile-typelib: Interpret --includedir as most-important-first
- !3930 migrating-gi: Document command-line option removals
- !3935 Restrict macOS CI to origin
- !3937 girepository: Fix static build under Windows
- !3945 tests: Remove variable-length lookbehind tests for GRegex
* Translation updates:
- Basque (Asier Sarasua Garmendia)
- Catalan (Jordi Mas i Hernandez)
- Chinese (China) (Boyuan Yang)
- Czech (Daniel Rusek)
- Galician (Fran Dieguez)
- Georgian (Ekaterine Papava)
- Hebrew (Yaron Shahrabani)
- Indonesian (Andika Triwidada)
- Kazakh (Baurzhan Muftakhidinov)
- Latvian (Rūdolfs Mazurs)
- Lithuanian (Aurimas Černius)
- Persian (Danial Behzadi)
- Russian (Artur S0)
- Slovenian (Matej Urbančič)
- Spanish (Daniel Mustieles)
- Turkish (Sabri Ünal, Emin Tufan Çetin)
- Ukrainian (Yuri Chornoivan)
Overview of changes in GLib 2.79.2, 2024-02-12
==============================================
* More work to reduce lock contention and improve performance in GObject (#743,
!3869, !3873, work by Thomas Haller)
* More API changes to libgirepository, which is now stable as of this release
(#3155, #3217, #3218, #3231, #3234, #3243, #3244, #3245, #3246, work by
Philip Chimento, Evan Welsh, Philip Withnall)
* Import `g-ir-compiler`, `g-ir-generate` and `g-ir-inspect` from
gobject-introspection.git and update them to work with girepository-2.0,
renaming them to `gi-compile-repository`, `gi-decompile-typelib` and
`gi-inspect-typelib` (see docs/reference/girepository/migrating-gi.md) (!3853,
!3909, work by Evan Welsh, Philip Withnall)
* Add new `GLibUnix-2.0.gir`, `GLibWin32-2.0.gir`, `GioUnix-2.0.gir` and
`GioWin32-2.0.gir` GIRs which contain platform specific APIs, and are the
preferred way for third parties to access those APIs in future; although
platform specific APIs which were already exposed in `GLib-2.0.gir` and
`Gio-2.0.gir` continue to be listed there; the underlying `.so` files have not
changed (!3892, work by Philip Withnall)
* Bugs fixed:
- #743 GLib weak refs depend on cascade of locks, including global ones, which
makes them non-scalable
- #2887 memory-monitor-dbus.test fails in installed-tests suite (Philip
Withnall)
- #3198 Support --version in standard GApplication command line arguments
(Maxim Moskalets)
- #3217 Feedback on gobject-introspection: APIs for stack-allocated
introspection info (Philip Withnall)
- #3218 Segfault in gi_function_info_prep_invoker (Philip Withnall)
- #3231 New functions in the glib introspection data (Philip Withnall)
- #3234 Reference cycle between GIRepository and GIBaseInfos cached by it
(Philip Withnall)
- #3236 threaded_resolver_worker_cb leaks memory when lookup fails and
connection is already canceled (Philip Withnall)
- #3238 Python packaging module is missing on Hurd CI runner (Philip Withnall)
- #3240 Missing preconditions checks in GArray (Tobias Stoeckmann)
- #3242 Memory leak in gresources over libelf (Maxim Moskalets)
- #3243 Feedback on girepository 2.0: Naming of get_type_info vs load_type
(Philip Withnall)
- #3244 Feedback on girepository 2.0: Where to find uninstalled typelibs
(Philip Withnall)
- #3245 Feedback on girepository 2.0: GIBoxedInfo's place in the type
hierarchy (Philip Withnall)
- #3246 Wrong out parameter type in
gi_object_info_find_method_using_interfaces (Philip Withnall)
- #3247 safe_closefrom(), safe_fdwalk_set_cloexec() as public API (Simon
McVittie)
- !3797 Refactor GIRepository GIR generation to avoid cyclical dependency
- !3807 gprintf/gstrfuncs: Improve and port doc comments to gi-docgen
- !3824 gconvert: match GNU iconv behaviour on FreeBSD
- !3838 build: Add thorough test setup
- !3843 Add more test coverage for girepository
- !3845 gunixmounts: Use libmnt_monitor API for monitoring
- !3847 ci: Add ability to run manually some specific jobs
- !3848 Fix build with introspection on Windows
- !3849 girepository: Remove GI_FUNCTION_THROWS and GI_VFUNC_THROWS flags
- !3850 [th/strdup-in-ascii-strdown] glib: use g_strdup() in
g_ascii_strdown(),g_ascii_strup()
- !3851 ci: Fix post-merge CI pipelines
- !3853 girepository: Update gir-compiler and use it to compile GIRs
- !3854 girnode: Document ownership and element types of internal structs
- !3855 gitypelib: Replace multiple constructors with
gi_typelib_new_from_bytes()
- !3856 girepository: Drop gi_repository_get_default()
- !3859 [th/glib-private-const] glib: return const pointer from
glib__private__()
- !3860 tests: Fix typo in memory-monitor-portal.py.in
- !3861 girepository: Fix a memory leak of a mapped file
- !3865 [th/test-weak-notify] gobject/tests: add test checking that GWeakRef
is cleared in GWeakNotify
- !3866 [th/gobject-carray-comment] gobject: remove obsolete code comment
about CArray
- !3868 Link to the main context tutorial from the main loop docs
- !3869 [th/optimize-weak-ref-list] rework GObject's `WeakRefData` to track
references in an array instead of GSList
- !3870 Revert "Don't skip dbus-codegen tests on Win32"
- !3871 docs: Fix include path for the build
- !3872 gio: tests: Use slightly more explicit assert functions
- !3873 [th/datalist-shrink] shrink the interal buffer of `GData`
- !3874 Don't skip dbus-codegen tests on Win32
- !3876 build: Only override g-ir-compiler when GIR generation is enabled
- !3877 Various girepository fixes
- !3879 [th/gdataset-comment] gdataset: add code comment to
g_datalist_get_data()
- !3881 docs: Add migration guide for libgirepository
- !3886 codegen: Use `-` instead of `stdout` for output to stdout
- !3887 gtestutils: Ensure test_data is freed even if a test is skipped
- !3888 gitypes: Fix integer values of GIInfoType and add unit tests for
GIUnionInfo
- !3892 introspection: Generate separate GIR files and documentation for
platform specific APIs
- !3893 glocalfile: Support statvfs.f_type
- !3894 Minor fixes/docs changes to GFileDescriptorBased and GTask
- !3895 [th/meson-werror-fixes] some fixes for meson detection failure with
-Werror
- !3896 reuse: Add dep5 lines for gnulib and libcharset
- !3897 reuse: Fix screen-scraping expression for version 2.x
- !3898 Incorporate some lint checks into `meson test`
- !3900 gitypelib: Switch to refcounting
- !3901 girepository: Add length ‘out’ arguments to several getter methods
- !3902 gicallableinfo: Clarify docs for callables with no return type
- !3903 gibaseinfo: Rename gi_info_new() to gi_base_info_new()
- !3904 [th/meson-werror-fixes-2] more workarounds for compiler warnings in
meson compiler checks
- !3909 Rename g-ir-generate and g-ir-inspect and update to girepository-2.0
- !3911 glib/tests/unix: Mostly pass O_CLOEXEC to g_unix_pipe_open()
- !3912 glib-unix: Fix reference to FD_CLOEXEC in docs for g_unix_pipe_open()
- !3913 cmph: Fix a typo
- !3914 Revert "ci: Remove not-printable chars from generated junit file"
- !3916 tests: Skip lint tests if bash is not available
- !3917 ci: Build and tar libgirepository documentation
* Translation updates:
- Georgian (Ekaterine Papava)
- Russian (Artur S0)
Overview of changes in GLib 2.79.1, 2024-01-22
==============================================
* Fix a race condition in `g_object_unref()` (#3064, work by Thomas Haller)
* Various API and build changes to libgirepository as it is not yet API-stable
(#3216, !3780, !3805, !3823, !3833, !3840)
* Build fixes on big-endian 64-bit systems and mips64el (#3225, #3226, work by
Simon McVittie)
* Reduce contention on global locks within GObject (!3774, work by Thomas
Haller)
* Allow building man pages without the reference documentation (!3817, work by
Simon McVittie)
* Bugs fixed:
- #1010 g_get_num_processor does not respect cpuset/affinity
- #3064 Crash under g_object_unref()
- #3093 GDBusMessage: should validate the type of all known headers (Philip
Withnall)
- #3207 Add support for syslog to Structured Logging
- #3216 Feedback on gobject-introspection: Casting to and from GIBaseInfo*
(Philip Withnall)
- #3222 pthread_t usages lack type name (Emmanuele Bassi)
- #3223 CLang, GMutexLocker: error: unused variable 'locker'
[-Werror,-Wunused-variable]
- #3225 2.79 regression: gdatetime test failing on 64-bit big-endian since
#3119
- #3226 resource test fails on Debian mips64el: test5.gresource is not linked
but the test assumes it should be (Simon McVittie)
- !3774 [th/g-object-priv] add private data to GObject and use per-object
locking
- !3780 girepository: Use standard types instead of glib specific
- !3789 gdatetime: Fix title of documentation comment
- !3792 build: Tell gi-docgen where to find the GIR files
- !3793 Shorten the title for D-Bus interface docs
- !3794 Add boxed GType for GRand
- !3795 girepository: Skip GIRepository versions not matching GIRepository-3.0
- !3798 docs: Drop outdated .gitignore files
- !3799 tests: Fix a minor leak in the new GParamSpecPool test
- !3800 ci: Re-enable and fix FreeBSD CI
- !3801 gmessages: Port all doc comments to gi-docgen
- !3802 [th/g-pointer-bit-lock-ext] glib: add g_pointer_bit_unlock_and_set()
and g_pointer_bit_lock_mask_ptr()
- !3803 ci: Fix tarballing the docs on dist
- !3805 girepository: Various small API cleanups
- !3806 gsignal.c: drop an optimization that is undefined behaviour
- !3808 glib/deprecated: Skip all the deprecated gthread api
- !3809 docs: Fix links to symbols outside the allowed namsepace
- !3810 gstrfuncs: Improve and port g_set_str() docs to gi-docgen
- !3811 gvariant-parser: Mention annotated types
- !3812 brz.c: Use uintptr_t instead of a hardcoded list of 64-bit arches
- !3813 gobject: define HAVE_OPTIONAL_FLAGS for sizeof(void*) > 8
- !3814 Fix typo in GPOINTER_TO_SIZE documentation
- !3817 docs: Allow building man pages without the reference documentation
- !3818 docs: Clarify >=2.76 changes to g_module_open()
- !3821 tests: Fix a minor leak in the socket test
- !3823 girepository: Misc cleanups
- !3826 genums: use g_once_init_enter_pointer for GType initializers
- !3827 array-test: Don't assume sizeof(void*)==sizeof(gsize)
- !3831 gvariant-core: Don’t call posix_memalign() with size==0
- !3833 girepository: Change various alignments to use size_t
- !3835 build: Ignore branches in g_clear_*() functions under lcov
- !3837 tests: A couple of test isolation improvements
- !3839 gvarianttype: Fix typos
- !3840 girepository: Exclude private symbols from the ABI
- !3841 docs: Fix member names of GLib.LogLevelFlags
- !3842 gio, gmodule, gthread: compile windows resources only in shared build
* Translation updates:
- Georgian (Ekaterine Papava)
- Russian (Artur S0)
Overview of changes in GLib 2.79.0, 2023-12-22
==============================================
* Port to gi-docgen and drop gtk-doc support — dependencies have changed, and
Meson needs `-Ddocumentation` now rather than `-Dgtk_doc` (#3037, work by
multiple people)
* Move libgirepository into glib.git from gobject-introspection.git — but tools
like `g-ir-scanner` are currently still in gobject-introspection.git. For the
moment, glib.git needs to be built twice, once with `-Dintrospection=false`,
then build gobject-introspection.git, then re-build glib.git with
`-Dintrospection=true`. This process will evolve throughout the GLib 2.80
cycle. The API and ABI of libgirepository has changed, and accordingly its
version number has been bumped from 1.0 to 2.0 (note: the version number of
`GIRepository-*.gir` has been bumped from 2.0 to 3.0; see !3786). The GIR and
typelib file formats have not been changed, and are still at version 1.0.
(#3155, work by multiple people)
* Match behaviour for `GAppInfo` searches has changed (#3082, work by Nelson
Benítez León)
* Rename `GTK_USE_PORTAL` environment variable to `GIO_USE_PORTALS` (#3107,
work by Philip Withnall)
* Bump Meson dependency to 1.2.0 and depend on Python `packaging` module
(!3666, !3752)
Bugs fixed:
- #596 GApplication in Garbage Collected environments would benefit from a
g_application_command_line_exit() to enable remote instances to exit.
(Aleksandr Mezin)
- #791 Wish: Add a "nodelay" property to GSocket or GTcpConnection (Philip
Withnall)
- #2810 thread-pool-slow intermittent assertion failure in
test_thread_sort_entry_func() (Philip Withnall)
- #2824 G_REGEX_OPTIMIZE causes incorrect regex behaviour
- #2991 Drop translatable pspec nick/blurbs from properties in GIO (Sophie
Herold)
- #3082 Investigate prioritising prefix matches on GAppInfo keywords over
substring matches on names (Nelson Benítez León)
- #3087 glib doesn't cleanly unload on Windows (Luca Bacci)
- #3098 Make invalid escape sequences in GKeyFile fatal (Philip Withnall)
- #3103 mkenums: Can't parse an enum value with value ',' (Lukáš Tyrychtr)
- #3105 NetworkManager 1.44.0 crashes repeatedly with glib 2.78.0 (Philip
Withnall)
- #3107 Rename GTK_USE_PORTAL to avoid portal services being run with portals
force-enabled (Philip Withnall)
- #3111 gsubprocess-testprog.c: build error with cygwin (sys/ptrace.h: No such
file or directory) (Philip Withnall)
- #3112 Update to Unicode 15.1 (Philip Withnall)
- #3115 Support for additional strftime formatting capabilities
- #3116 gio clears modification time in microseconds when setting with
`set_modification_date_time` (Lukáš Tyrychtr)
- #3119 Add support for `%Ey` to g_date_time_format() (Philip Withnall)
- #3120 Build of glib 2.78.0 ignores -Dlibelf=disabled (Philip Withnall)
- #3128 glib-2.78.0 fails at gio/tests/gsubprocess.p/gsubprocess.c.o
- #3130 Segfault when creating GIO GPropertyAction without properties
- #3134 glib incompatible with Python 3.12 due to distutils usage
- #3135 Add GNU/Hurd CI
- #3140 Add a flag to not copy modification time when copying files (Khalid
Abu Shawarib)
- #3144 `g_file_set_contents_full()` doesn't truncate the file (without
`G_FILE_SET_CONTENTS_CONSISTENT`) (Philip Withnall)
- #3156 check for #ifdef PTRACE_O_EXITKILL will always fail since it isn't a
macro (Alessandro Bono)
- #3157 gsubprocess build-time test intermittently timing out since 2.78.1
(Simon McVittie)
- !3673 Backport !3669 “meson: Improve PTRACE_O_EXITKILL presence check” to
glib-2-78
- !3680 Backport !3677 “Make GQuark register intentional leaks” to glib-2-78
- !3681 Backport 3678 “gsignalgroup: Avoid function call with side effect in
g_return_* macro” to glib-2-78
- !3686 Backport !3685 “tests: Don't assume that sh optimizes simple commands
into exec” to glib-2-78
- !3718 Backport !3714 “xdgmime: Handle buggy type definitions with circular
inheritance” to glib-2-78
- !3727 Backport !3725 “collate: Don't segfault on bad input” to glib-2-78
* Translation updates:
- Ukrainian (Yuri Chornoivan)
Overview of changes in GLib 2.78.1, 2023-10-25
==============================================
* Fix truncating files when `g_file_set_contents_full()` is called without
`G_FILE_SET_CONTENTS_CONSISTENT` (#3144, work by Philip Withnall)
* Fix `-Dlibelf=disabled` on Linux (#3120, work by Philip Withnall)
* Bugs fixed:
- #3105 NetworkManager 1.44.0 crashes repeatedly with glib 2.78.0 (Philip
- #3158 "CRITICAL" log when using --attributes option for "gio info" (Philip
Withnall)
- #3111 gsubprocess-testprog.c: build error with cygwin (sys/ptrace.h: No such
file or directory) (Philip Withnall)
- #3116 gio clears modification time in microseconds when setting with
`set_modification_date_time` (Lukáš Tyrychtr)
- #3120 Build of glib 2.78.0 ignores -Dlibelf=disabled (Philip Withnall)
- #3128 glib-2.78.0 fails at gio/tests/gsubprocess.p/gsubprocess.c.o
- #3130 Segfault when creating GIO GPropertyAction without properties
- #3144 `g_file_set_contents_full()` doesn't truncate the file (without
`G_FILE_SET_CONTENTS_CONSISTENT`) (Philip Withnall)
- #3159 glib regex test fails JIT compiler tests under musl libc (Pablo Correa
Gómez)
- #3161 codegen installation is broken
- #3168 gvfs-udisks2-volume-monitor SIGSEGV in g_content_type_guess_for_tree()
due to filename with bad encoding (Ondrej Holy)
- #3183 g_dbus_connection_signal_subscribe with flag
G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH doesn't work with an arg0 that is an
object path (Philip Withnall)
- #3185 g_utf8_collate_key() segfaults when passed an invalid length
- #3186 [RFE] Increase gio sniff buffer for mime type magic detection to 16K
or so (Philip Withnall)
- #3187 g_vasprintf crashes when passed invalid UTF-8 (Philip Withnall)
- #3191 Crash in __gio_xdg_cache_mime_type_subclass (Philip Withnall)
- #3203 Fdo notification fails without AppID (Michael Catanzaro)
- !3143 gatomic: Use g(u)intptr where appropriate
- !3316 gobject: Separate GWeakRef from GWeakNotify
- !3394 gsocketclient: Document delays/timeouts better
- !3457 glib-unix: Add convenience API for pipes
- !3524 add muslc ci
- !3552 gutils: Use international symbol for bits
- !3566 Update annotations for GAsyncQueue and GDir
- !3567 Update annotations for GHmac
- !3568 Update GOptionContext annotations
- !3569 Small fixes and cleanups for Vectored Exception Handlers
- !3571 Update GStringChunk annotations
- !3572 Update GRand annotations
- !3573 Update GTimer annotations
- !3576 guniprop.c: Avoid creating (temporarily) out-of-bounds pointers
- !3577 gthread: introduce g_once_init_{enter,leave}_pointer
- !3578 GType: Use guintptr as the underlying storage if larger than gsize
- !3579 Fixes for integer cast warnings when targeting CHERI
- !3580 Fix test_find_program on FreeBSD
- !3589 gconstructor.h: Ensure [c|d]tor prototypes are present for MSVC (Chun-
wei Fan)
- !3581 gthread: Fix optional/nullable annotations for g_once_init_*()
- !3582 Buffer needs to be aligned correctly to receive linux_dirent64.
- !3589 gconstructor.h: Ensure [c|d]tor prototypes are present for MSVC
(Chun-wei Fan)
- !3590 gtestutils.h: Fix warning with -Wsign-conversion caused by
g_assert_cmpint
- !3591 Switch to using gi-docgen for docs (batch 1)
- !3594 Fix gutils-user-database test on macOS
- !3595 gobject: cache flags needed for g_type_create_instance()
- !3596 Add value annotation to G_TYPE_FUNDAMENTAL_MAX
- !3597 Expand security policy to cover previous stable branch
- !3598 Document NULL pointer pitfall in toolchain requirements
- !3601 meson: Fix Windows build with PCRE2 as sibling subproject
- !3604 Backport !3589 “gconstructor.h: Ensure [c|d]tor prototypes are present
for MSVC” to glib-2-78
- !3608 Backport !3587 “glocalfileinfo: Preserve microseconds for
access/modify times” to glib-2-78
- !3609 Backport !3607 “Make sure the `GTask` is freed on a graceful
disconnect” to glib-2-78 (Pavel Sobolev)
- !3614 Backport !3582 “Buffer needs to be aligned correctly to receive
linux_dirent64.” to glib-2-78
- !3616 Backport !3590 “gtestutils.h: Fix warning with -Wsign-conversion
caused by g_assert_cmpint” to glib-2-78
- !3619 Backport !3617 “tests: Drop unnecessary include from gsubprocess-
testprog.c” to glib-2-78
- !3622 Backport !3621 “wakeup: do single read when using eventfd()” to
glib-2-78
- !3625 Backport !3624 “wakeup: Fix g_wakeup_acknowledge if signal comes in”
to glib-2-78
- !3644 Backport !3633 “Use g_task_return in task threads” to glib-2-78
- !3649 Backport !3648 “build: Fix -Dlibelf=disabled on Linux” to glib-2-78
- !3659 Backport !3650 “gfileutils: Add a missing ftruncate() call when
writing files” to glib-2-78
- !3603 Add GBytes variants for GSocket receive methods
- !3605 build: Post-release version bump
- !3607 Make sure the `GTask` is freed on a graceful disconnect
- !3610 gdesktopappinfo: Do not search Comment field
- !3611 tests/constructor: Fix "unknown pragma ignored" warning on clang
- !3612 Update GStrv annotations
- !3613 tests: Fix gdatetime test on non-UTC systems
- !3620 gmain: avoid a GList traversal when removing source
- !3621 wakeup: do single read when using eventfd()
- !3623 Windows: Compile with the UNICODE / _UNICODE macros
- !3624 wakeup: Fix g_wakeup_acknowledge if signal comes in
- !3627 Add Hurd code owners
- !3628 glib-unix: Use full path to gstdio.h include
- !3629 glib/tests/meson.build: remove identical build targets
- !3630 glib-compile-resources: ensure alignment is at least sizeof(void *)
- !3632 Stop using enums in bitfields
- !3633 Use g_task_return in task threads
- !3634 Switch to using gi-docgen for docs (batch 2)
- !3635 Fix warnings with Clang on Windows and enable --Werror in CI
- !3636 Generate introspection data
- !3637 gstrvbuilder: Add g_strv_builder_take
- !3638 Cleanup and add content to glib debugging using gdb scripts
- !3640 GIO/tests: skip test_resources_binary on MIPS platforms
- !3641 build: Simplify MIPS test check
- !3645 Switch to using gi-docgen for docs (batch 3)
- !3646 ci: Update from clang-format-11 to clang-format-14
- !3647 Switch to using gi-docgen for docs (batch 4)
- !3652 GApplicationCommandLine: add print[err]_literal()
- !3654 gdatetime: Fix minor leaks from strup/strdown calls
- !3655 gdatetime: Fix incorrect alt-digits being used after changing locale
- !3656 gmodule-dl: Use RTLD_DEFAULT on FreeBSD too
- !3660 Switch to using gi-docgen for docs (batch 5)
- !3661 Switch to using gi-docgen for docs (batch 6)
- !3662 Switch to using gi-docgen for docs (batch 7)
- !3663 gdbusconnection: don't cache G_IO_ERROR_CANCELLED errors
- !3664 gmain: optimize "context->sources" hash table to use as set
- !3665 ci: Remove .build-linux from Hurd CI scheduled job
- !3666 build: Bump Meson dependency to 1.2.0
- !3667 Switch to using gi-docgen for docs (batch 8)
- !3668 Socket & readiness fixes
- !3671 gio/tests: Add test generated txt as the resources test dependency
- !3672 glib-private: Check for LSAN support at runtime when controlling it
- !3674 gtask: Add g_task_return_prefixed_error()
- !3677 Make GQuark register intentional leaks
- !3678 gsignalgroup: Avoid function call with side effect in g_return_* macro
- !3679 gmessages: fix dropping irrelevant log domains
- !3682 tests: Fix dependency of test.gresource on test-generated.txt
- !3683 glib: Disable dynamic asan loading on macOS
- !3687 fix: about libproc.h and PROC_PIDLISTFD_SIZE
- !3688 build: Fix the inclusion paths for GIR files in gi-docgen
- !3689 meson: Add missing dependencies for utility files for gdbus-codegen
- !3690 Switch to using gi-docgen for docs (batch 9)
- !3695 gvalue: add "steal_string"
- !3699 [th/prgname] use atomic pointers for g_prgname/g_application_name and
add g_set_prgname_once()
- !3701 tests: Fix gio-tool.py test on macOS
- !3702 glib.supp: Suppress the global_mime_dirs allocations
- !3703 Port GIRepository to GTypeInstance and add introspection
- !3704 girepository: Rename symbols to the GI namespace
- !3707 girepository: Ignore set-but-not-used warnings with G_DISABLE_ASSERT
- !3708 Fix various leaks in cmph-bdz-test and gutils
- !3709 Switch to using gi-docgen for docs (batch 10)
- !3710 gmessages: introduce g_log_writer_default_set_debug_domains()
- !3711 ghmac: Add a boxed type for GHmac and fix introspection build
accordingly
- !3712 Switch to using gi-docgen for docs (batch 11)
- !3713 gfileutils: Fix g_file_get_contents() silent under-read of large files
when off_t is wider than size_t
- !3714 xdgmime: Handle buggy type definitions with circular inheritance
- !3715 goption: Fix a typo
- !3716 tests: Improve build of cmph tests in girepository
- !3717 tests: provide reason for disabling convert test under musl
- !3721 gtestutils: Add g_test_trap_subprocess_with_envp() for testing envs
- !3722 gdir, gstrvbuilder: Add refcounting support and a boxed type
- !3723 gwin32: Un-hide symbols when building GIR
- !3726 tests: Fix fileutils build on FreeBSD and macOS
- !3731 tests: Fix string test failure on BSDs
- !3732 gspawn: Stop spewing debug messages
- !3733 ci: Make the Alpine CI name more consistent
- !3734 gdatetime: Disable ERA support on platforms which don’t support this
- !3735 ci: Fix printing info message at end of run-style-check-diff.sh
- !3736 build: Rename -Dgtk_doc option to -Ddocumentation and fix some
g-ir-scanner warnings
- !3739 Documentation only: Added clarification about GWeakNotify and removed
ambiguous text
- !3741 hash: Explicitly annotate key in iter_next as nullable
- !3743 ci: Install correct version of Meson on Alpine CI image
- !3745 tests: Assert there no errors first in gdbus-test-codegen
- !3751 Fix generated RST anchors for methods, signals and properties
- !3752 build: Make packaging module required
- !3753 gobject_gdb.py: Do not break bt on optimized build
- !3755 tests: Use textwrap.dedent to indent expected strings pleasingly
- !3757 ci: Re-add explicit Meson version to Alpine CI image
- !3758 docs: Add a section on version checking macros
- !3760 girepository: Various API cleanups
- !3761 gerror: Fix an old allow-none annotation
- !3762 [th/notify-queue] some optimization around
g_object_freeze_notify()/g_object_thaw_notify()
- !3763 girepository: Drop libgio dependency from gdump.c
- !3764 gsignal: fix reference to signals documentation page
- !3765 gapplication: Fix minor typo in docs
- !3767 girepository: Port documentation to gi-docgen and update
- !3768 ci: Build docs artifacts for deployment to docs.gtk.org
- !3770 GDateTime: Add usec precision API for unix time
- !3771 gtask: Add g_task_return_new_error_literal()
- !3772 gobject: Make GLib-2.0 gir build depend on GObject dependency
- !3773 girepository: Return enumerated versions and search paths as a GStrv
- !3776 glocalvfs: Remove unnecessary and buggy code
- !3777 Fix detecting size_t size when `-Wmissing-prototypes` is in CFLAGS
- !3779 gtypemodule: Add assertions in finalize()
- !3782 docs: fix a typo
- !3786 girepository: Re-number GIR file from 2.0 to 3.0
- !3787 docs: Install the gi-docgen docs
* Translation updates:
- Catalan (Jordi Mas i Hernandez)
@ -87,15 +520,15 @@ Overview of changes in GLib 2.78.1, 2023-10-25
- Czech (Daniel Rusek)
- Esperanto (Kristjan SCHMIDT)
- French (Alexandre Franke)
- Georgian (Ekaterine Papava)
- Italian (Milo Casagrande)
- Latvian (Rūdolfs Mazurs)
- Portuguese (Brazil) (Rafael Fontenelle)
- Romanian (Daniel Șerbănescu)
- Romanian (Florentina Mușat)
- Russian (Artur S0)
- Slovenian (Matej Urbančič)
- Spanish (Daniel Mustieles)
- Turkish (Sabri Ünal)
- Ukrainian (Yuri Chornoivan)
Overview of changes in GLib 2.78.0, 2023-09-08

7
README.md
View File

@ -19,9 +19,10 @@ GLib on Windows.
## Supported versions
Only the most recent unstable and stable release series are supported. All
older versions are not supported upstream and may contain bugs, some of
which may be exploitable security vulnerabilities.
Upstream GLib only supports the most recent stable release series, the previous
stable release series, and the current development release series. All
older versions are not supported upstream and may contain bugs, some of which
may be exploitable security vulnerabilities.
See [SECURITY.md](SECURITY.md) for more details.

15
SECURITY.md
View File

@ -7,11 +7,16 @@
## Supported Versions
Upstream GLib only supports the most recent stable release series, and the
current development release series. Any older stable release series are no
longer supported, although they may still receive backported security updates
in long-term support distributions. Such support is up to the distributions,
though.
Upstream GLib only supports the most recent stable release series, the previous
stable release series, and the current development release series. Any older
stable release series are no longer supported, although they may still receive
backported security updates in long-term support distributions. Such support is
up to the distributions, though.
The previous stable release series will generally receive fixes only for high
impact security issues, at maintainer discretion. Since such issues are rare,
it's expected that there may be no backports or releases on the previous stable
branch.
Under GLib’s versioning scheme, stable release series have an *even* minor
component (for example, 2.66.0, 2.66.1, 2.68.3), and development release series

3
docs/CODEOWNERS
View File

@ -53,6 +53,9 @@ subprojects/ @xclaesse @nirbheek @pwithnall
*bsd* @jmatthew @ajacoutot @lantw @pwithnall
*kqueue* @jmatthew @ajacoutot @lantw @pwithnall
# GNU Hurd support
*hurd* @bugaevc @sthibaul
# flatpak portals
gio/*portal* @matthiasc @alexl @pwithnall

16
docs/reference/.gitignore vendored
View File

@ -1,16 +0,0 @@
*-decl-list.txt
*-decl.txt
*-unused.txt
*-undocumented.txt
*-undeclared.txt
*.args
*.hierarchy
*.interfaces
*.prerequisites
*.signals
*.stamp
html
xml
*.bak
version.xml
*.1

3
docs/reference/gio/.gitignore vendored
View File

@ -1,3 +0,0 @@
*.1
gio-overrides.txt
tmpl

36
docs/reference/gio/concat-files-helper.py
View File

@ -1,36 +0,0 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Copyright (C) 2018 Collabora Inc.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General
# Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
#
# Author: Xavier Claessens <xavier.claessens@collabora.com>
import os
import sys
if len(sys.argv) < 3:
print(
"Usage: {} <output file> <input file 1> ...".format(
os.path.basename(sys.argv[0])
)
)
sys.exit(1)
with open(sys.argv[1], "w") as outfile:
for fname in sys.argv[2:]:
with open(fname) as infile:
for line in infile:
outfile.write(line)

79
docs/reference/gio/dbus-error.md Normal file
View File

@ -0,0 +1,79 @@
Title: D-Bus Error Handling
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 David Zeuthen
SPDX-FileCopyrightText: 2012 Aleksander Morgado
# D-Bus Error Handling
All facilities that return errors from remote methods (such as
[method@Gio.DBusConnection.call_sync]) use [type@GLib.Error] to represent both
D-Bus errors (e.g. errors returned from the other peer) and locally in-process
generated errors.
To check if a returned [type@GLib.Error] is an error from a remote peer, use
[func@Gio.DBusError.is_remote_error]. To get the actual D-Bus error name,
use [func@Gio.DBusError.get_remote_error]. Before presenting an error, always
use [func@Gio.DBusError.strip_remote_error].
In addition, facilities used to return errors to a remote peer also use
[type@GLib.Error]. See [method@Gio.DBusMethodInvocation.return_error] for
discussion about how the D-Bus error name is set.
Applications can associate a [type@GLib.Error] error domain with a set of D-Bus
errors in order to automatically map from D-Bus errors to [type@GLib.Error] and
back. This is typically done in the function returning the [type@GLib.Quark] for
the error domain:
```c
// foo-bar-error.h:
#define FOO_BAR_ERROR (foo_bar_error_quark ())
GQuark foo_bar_error_quark (void);
typedef enum
{
FOO_BAR_ERROR_FAILED,
FOO_BAR_ERROR_ANOTHER_ERROR,
FOO_BAR_ERROR_SOME_THIRD_ERROR,
FOO_BAR_N_ERRORS / *< skip >* /
} FooBarError;
// foo-bar-error.c:
static const GDBusErrorEntry foo_bar_error_entries[] =
{
{FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
{FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
{FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
};
// Ensure that every error code has an associated D-Bus error name
G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
GQuark
foo_bar_error_quark (void)
{
static gsize quark = 0;
g_dbus_error_register_error_domain ("foo-bar-error-quark",
&quark,
foo_bar_error_entries,
G_N_ELEMENTS (foo_bar_error_entries));
return (GQuark) quark;
}
```
With this setup, a D-Bus peer can transparently pass e.g.
`FOO_BAR_ERROR_ANOTHER_ERROR` and other peers will see the D-Bus error name
`org.project.Foo.Bar.Error.AnotherError`.
If the other peer is using GDBus, and has registered the association with
[func@Gio.DBusError.register_error_domain] in advance (e.g. by invoking the
`FOO_BAR_ERROR` quark generation itself in the previous example) the peer will
see also `FOO_BAR_ERROR_ANOTHER_ERROR` instead of `G_IO_ERROR_DBUS_ERROR`. Note
that GDBus clients can still recover `org.project.Foo.Bar.Error.AnotherError`
using [func@Gio.DBusError.get_remote_error].
Note that the `G_DBUS_ERROR` error domain is intended only for returning errors
from a remote message bus process. Errors generated locally in-process by e.g.
[class@Gio.DBusConnection] should use the `G_IO_ERROR` domain.

23
docs/reference/gio/dbus-introspection.md Normal file
View File

@ -0,0 +1,23 @@
Title: D-Bus Introspection Data
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 David Zeuthen
SPDX-FileCopyrightText: 2010 Matthias Clasen
# D-Bus Introspection Data
Various data structures and convenience routines to parse and
generate D-Bus introspection XML. Introspection information is
used when registering objects with [method@Gio.DBusConnection.register_object].
The format of D-Bus introspection XML is specified in the
[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format).
The main introspection data structures are:
* [type@Gio.DBusNodeInfo]
* [type@Gio.DBusInterfaceInfo]
* [type@Gio.DBusPropertyInfo]
* [type@Gio.DBusMethodInfo]
* [type@Gio.DBusSignalInfo]
* [type@Gio.DBusArgInfo]
* [type@Gio.DBusAnnotationInfo]

14
docs/reference/gio/dbus-name-owning.md Normal file
View File

@ -0,0 +1,14 @@
Title: D-Bus Name Owning
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 David Zeuthen
# D-Bus Name Owning
Convenience API for owning bus names.
A simple example for owning a name can be found in
[`gdbus-example-own-name.c`](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-own-name.c).
The main API for owning names is:
* [func@Gio.bus_own_name]
* [func@Gio.bus_unown_name]

14
docs/reference/gio/dbus-name-watching.md Normal file
View File

@ -0,0 +1,14 @@
Title: D-Bus Name Watching
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 David Zeuthen
# D-Bus Name Watching
Convenience API for watching bus names.
A simple example for watching a name can be found in
[`gdbus-example-watch-name.c`](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-name.c).
The main API for watching names is:
* [func@Gio.bus_watch_name]
* [func@Gio.bus_unwatch_name]

28
docs/reference/gio/dbus-utils.md Normal file
View File

@ -0,0 +1,28 @@
Title: D-Bus Utilities
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 David Zeuthen
# D-Bus Utilities
Various utility routines related to D-Bus.
GUID support:
* [func@Gio.dbus_is_guid]
* [func@Gio.dbus_generate_guid]
Name validation:
* [func@Gio.dbus_is_name]
* [func@Gio.dbus_is_unique_name]
* [func@Gio.dbus_is_member_name]
* [func@Gio.dbus_is_interface_name]
* [func@Gio.dbus_is_error_name]
Conversion between [type@GLib.Variant] and [type@GObject.Value]:
* [func@Gio.dbus_gvariant_to_gvalue]
* [func@Gio.dbus_gvalue_to_gvariant]
Path escaping:
* [func@Gio.dbus_escape_object_path_bytestring]
* [func@Gio.dbus_escape_object_path]
* [func@Gio.dbus_unescape_object_path]

12
docs/reference/gio/error.md Normal file
View File

@ -0,0 +1,12 @@
Title: GIOError
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007 A. Walton
# GIOError
Contains helper functions for reporting errors to the user.
Functions for converting between different error reporting mechanisms:
* [func@Gio.io_error_from_errno]
* [func@Gio.io_error_from_file_error]

111
docs/reference/gio/file-attributes.md Normal file
View File

@ -0,0 +1,111 @@
Title: File Attributes
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007 Andrew Walton
SPDX-FileCopyrightText: 2007 Alexander Larsson
SPDX-FileCopyrightText: 2008, 2014 Matthias Clasen
SPDX-FileCopyrightText: 2011 Murray Cumming
SPDX-FileCopyrightText: 2012 David King
# File Attributes
File attributes in GIO consist of a list of key-value pairs.
Keys are strings that contain a key namespace and a key name, separated
by a colon, e.g. `namespace::keyname`. Namespaces are included to sort
key-value pairs by namespaces for relevance. Keys can be retrieved
using wildcards, e.g. `standard::*` will return all of the keys in the
`standard` namespace.
The list of possible attributes for a filesystem (pointed to by a
[iface@Gio.File]) is available as a [struct@Gio.FileAttributeInfoList]. This
list is queryable by key names as indicated earlier.
Information is stored within the list in [struct@Gio.FileAttributeInfo]
structures. The info structure can store different types, listed in the enum
[type@Gio.FileAttributeType]. Upon creation of a [struct@Gio.FileAttributeInfo],
the type will be set to `G_FILE_ATTRIBUTE_TYPE_INVALID`.
Classes that implement [iface@Gio.File] will create a
[struct@Gio.FileAttributeInfoList] and install default keys and values for their
given file system, architecture, and other possible implementation details
(e.g., on a UNIX system, a file attribute key will be registered for the user ID
for a given file).
## Default Namespaces
- `"standard"`: The ‘Standard’ namespace. General file information that
any application may need should be put in this namespace. Examples
include the file’s name, type, and size.
- `"etag`: The [Entity Tag](gfile.html#entity-tags) namespace. Currently, the
only key in this namespace is `value`, which contains the value of the current
entity tag.
- `"id"`: The ‘Identification’ namespace. This namespace is used by file
managers and applications that list directories to check for loops and
to uniquely identify files.
- `"access"`: The ‘Access’ namespace. Used to check if a user has the
proper privileges to access files and perform file operations. Keys in
this namespace are made to be generic and easily understood, e.g. the
`can_read` key is true if the current user has permission to read the
file. UNIX permissions and NTFS ACLs in Windows should be mapped to
these values.
- `"mountable"`: The ‘Mountable’ namespace. Includes simple boolean keys
for checking if a file or path supports mount operations, e.g. mount,
unmount, eject. These are used for files of type `G_FILE_TYPE_MOUNTABLE`.
- `"time"`: The ‘Time’ namespace. Includes file access, changed, created
times.
- `"unix"`: The ‘Unix’ namespace. Includes UNIX-specific information and
may not be available for all files. Examples include the UNIX UID,
GID, etc.
- `"dos"`: The ‘DOS’ namespace. Includes DOS-specific information and may
not be available for all files. Examples include `is_system` for checking
if a file is marked as a system file, and `is_archive` for checking if a
file is marked as an archive file.
- `"owner"`: The ‘Owner’ namespace. Includes information about who owns a
file. May not be available for all file systems. Examples include `user`
for getting the user name of the file owner. This information is often
mapped from some backend specific data such as a UNIX UID.
- `"thumbnail"`: The ‘Thumbnail’ namespace. Includes information about file
thumbnails and their location within the file system. Examples of keys in
this namespace include `path` to get the location of a thumbnail, `failed`
to check if thumbnailing of the file failed, and `is-valid` to check if
the thumbnail is outdated.
- `"filesystem"`: The ‘Filesystem’ namespace. Gets information about the
file system where a file is located, such as its type, how much space is
left available, and the overall size of the file system.
- `"gvfs"`: The ‘GVFS’ namespace. Keys in this namespace contain information
about the current GVFS backend in use.
- `"xattr"`: The ‘xattr’ namespace. Gets information about extended user
attributes. See [`attr(5)`](man:attr(5)). The `user.` prefix of the extended
user attribute name is stripped away when constructing keys in this namespace,
e.g. `xattr::mime_type` for the extended attribute with the name
`user.mime_type`. Note that this information is only available if
GLib has been built with extended attribute support.
- `"xattr-sys"`: The ‘xattr-sys’ namespace. Gets information about
extended attributes which are not user-specific. See [`attr(5)`](man:attr(5)).
Note that this information is only available if GLib has been built with
extended attribute support.
- `"selinux"`: The ‘SELinux’ namespace. Includes information about the
SELinux context of files. Note that this information is only available
if GLib has been built with SELinux support.
Please note that these are not all of the possible namespaces.
More namespaces can be added from GIO modules or by individual applications.
For more information about writing GIO modules, see [class@Gio.IOModule].
<!-- TODO: Implementation note about using extended attributes on supported
file systems -->
## Default Keys
For a list of the built-in keys and their types, see the [class@Gio.FileInfo]
documentation.
Note that there are no predefined keys in the `xattr` and `xattr-sys`
namespaces. Keys for the `xattr` namespace are constructed by stripping
away the `user.` prefix from the extended user attribute, and prepending
`xattr::`. Keys for the `xattr-sys` namespace are constructed by
concatenating `xattr-sys::` with the extended attribute name. All extended
attribute values are returned as hex-encoded strings in which bytes outside
the ASCII range are encoded as escape sequences of the form `\xnn`
where `nn` is a 2-digit hexadecimal number.

195
docs/reference/gio/gapplication.rst Normal file
View File

@ -0,0 +1,195 @@
.. _gapplication(1):
.. meta::
:copyright: Copyright 2013 Allison Karlitskaya
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2013 Allison Karlitskaya
SPDX-License-Identifier: LGPL-2.1-or-later
============
gapplication
============
--------------------------
D-Bus application launcher
--------------------------
SYNOPSIS
--------
| **gapplication** help [COMMAND]
| **gapplication** version
| **gapplication** list-apps
| **gapplication** launch <APP-ID>
| **gapplication** launch <APP-ID> [FILE…]
| **gapplication** list-actions <APP-ID>
| **gapplication** action <APP-ID> <ACTION> [PARAMETER]
DESCRIPTION
-----------
``gapplication`` is a commandline implementation of the client-side of the
``org.freedesktop.Application`` interface as specified by the freedesktop.org
Desktop Entry Specification.
``gapplication`` can be used to start applications that have ``DBusActivatable``
set to ``true`` in their ``.desktop`` files and can be used to send messages to
already-running instances of other applications.
It is possible for applications to refer to ``gapplication`` in the ``Exec``
line of their ``.desktop`` file to maintain backwards compatibility with
implementations that do not directly support ``DBusActivatable``.
``gapplication`` ships as part of GLib.
COMMANDS
--------
``help [COMMAND]``
Displays a short synopsis of the available commands or provides detailed help
on a specific command.
``version``
Prints the GLib version whence ``gapplication`` came.
``list-apps``
Prints a list of all application IDs that are known to support D-Bus
activation. This list is generated by scanning ``.desktop`` files as per the
current ``XDG_DATA_DIRS``.
``launch <APP-ID> [FILE…]``
Launches an application.
The first parameter is the application ID in the familiar ‘reverse DNS’ style
(e.g. ``org.gnome.app``) without the ``.desktop`` suffix.
Optionally, if additional parameters are given, they are treated as the names
of files to open and may be filenames or URIs. If no files are given then the
application is simply activated.
``list-actions <APP-ID>``
List the actions declared in the application’s ``.desktop`` file. The
parameter is the application ID, as above.
``action <APP-ID> <ACTION> [PARAMETER]``
Invokes the named action (in the same way as would occur when activating an
action specified in the ``.desktop`` file).
The application ID (as above) is the first parameter. The action name
follows.
Optionally, following the action name can be one parameter, in GVariant
format, given as a single argument. Make sure to use sufficient quoting.
EXAMPLES
--------
From the commandline
^^^^^^^^^^^^^^^^^^^^
Launching an application::
gapplication launch org.example.fooview
Opening a file with an application::
gapplication launch org.example.fooview ~/file.foo
Opening many files with an application::
gapplication launch org.example.fooview ~/foos/*.foo
Invoking an action on an application::
gapplication action org.example.fooview create
Invoking an action on an application, with an action::
gapplication action org.example.fooview show-item '"item_id_828739"'
From the ``Exec`` lines of a ``.desktop`` file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The commandline interface of ``gapplication`` was designed so that it could be
used directly from the ``Exec`` line of a ``.desktop`` file.
You might want to do this to allow for backwards compatibility with
implementations of the specification that do not understand how to do D-Bus
activation, without having to install a separate utility program.
Consider the following example::
[Desktop Entry]
Version=1.1
Type=Application
Name=Foo Viewer
DBusActivatable=true
MimeType=image/x-foo;
Exec=gapplication launch org.example.fooview %F
Actions=gallery;create;
[Desktop Action gallery]
Name=Browse Gallery
Exec=gapplication action org.example.fooview gallery
[Desktop Action create]
Name=Create a new Foo!
Exec=gapplication action org.example.fooview create
From a script
^^^^^^^^^^^^^
If installing an application that supports D-Bus activation you may still want
to put a file in ``/usr/bin`` so that your program can be started from a
terminal.
It is possible for this file to be a shell script. The script can handle
arguments such as ``--help`` and ``--version`` directly. It can also parse
other command line arguments and convert them to uses of ``gapplication`` to
activate the application, open files, or invoke actions.
Here is a simplified example, as may be installed in ``/usr/bin/fooview``::
#!/bin/sh
case "$1" in
--help)
echo "see ‘man fooview’ for more information"
;;
--version)
echo "fooview 1.2"
;;
--gallery)
gapplication action org.example.fooview gallery
;;
--create)
gapplication action org.example.fooview create
;;
-*)
echo "unrecognised commandline argument"
exit 1
;;
*)
gapplication launch org.example.fooview "$@"
;;
esac
SEE ALSO
--------
`Desktop Entry Specification <https://specifications.freedesktop.org/desktop-entry-spec/latest/>`_,
`gdbus(1) <man:gdbus(1)>`_,
`xdg-open(1) <man:xdg-open(1)>`_,
`desktop-file-validate(1) <man:desktop-file-validate(1)>`_

352
docs/reference/gio/gapplication.xml
View File

@ -1,352 +0,0 @@
<refentry id="gapplication-tool" lang="en">
<refentryinfo>
<title>gapplication</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Ryan</firstname>
<surname>Lortie</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gapplication</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gapplication</refname>
<refpurpose>D-Bus application launcher</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">version</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">list-apps</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">launch</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">launch</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">list-actions</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gapplication</command>
<arg choice="plain">action</arg>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="plain"><replaceable>ACTION</replaceable></arg>
<arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>gapplication</command> is a commandline implementation of the client-side of the
<interfacename>org.freedesktop.Application</interfacename> interface as specified by the freedesktop.org
Desktop Entry Specification.
</para>
<para>
<command>gapplication</command> can be used to start applications that have
<varname>DBusActivatable</varname> set to <literal>true</literal> in their <filename>.desktop</filename>
files and can be used to send messages to already-running instances of other applications.
</para>
<para>
It is possible for applications to refer to <command>gapplication</command> in the <varname>Exec</varname>
line of their <filename class='extension'>.desktop</filename> file to maintain backwards compatibility
with implementations that do not directly support <varname>DBusActivatable</varname>.
</para>
<para>
<command>gapplication</command> ships as part of <application>GLib</application>.
</para>
</refsect1>
<refsect1>
<title>Commands</title>
<refsect2>
<title>Global commands</title>
<variablelist>
<varlistentry>
<term>
<command>help</command>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</term>
<listitem>
<para>
Displays a short synopsis of the available commands or provides detailed help on a specific
command.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>version</command>
</term>
<listitem>
<para>
Prints the GLib version whence <command>gapplication</command> came.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>list-apps</command>
</term>
<listitem>
<para>
Prints a list of all application IDs that are known to support D-Bus activation. This list is
generated by scanning <filename class='extension'>.desktop</filename> files as per the current
<envar>XDG_DATA_DIRS</envar>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>launch</command>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>FILE</replaceable></arg>
</term>
<listitem>
<para>
Launches an application.
</para>
<para>
The first parameter is the application ID in the familiar "reverse DNS" style (eg:
'<literal>org.gnome.app</literal>') without the <filename class='extension'>.desktop</filename>
suffix.
</para>
<para>
Optionally, if additional parameters are given, they are treated as the names of files to open and
may be filenames or URIs. If no files are given then the application is simply activated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>list-actions</command>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
</term>
<listitem>
<para>
List the actions declared in the application's <filename class='extension'>.desktop</filename>
file. The parameter is the application ID, as above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>action</command>
<arg choice="plain"><replaceable>APPID</replaceable></arg>
<arg choice="plain"><replaceable>ACTION</replaceable></arg>
<arg choice="opt"><replaceable>PARAMETER</replaceable></arg>
</term>
<listitem>
<para>
Invokes the named action (in the same way as would occur when activating an action specified in
the <filename class='extension'>.desktop</filename> file).
</para>
<para>
The application ID (as above) is the first parameter. The action name follows.
</para>
<para>
Optionally, following the action name can be one parameter, in GVariant format, given as a single
argument. Make sure to use sufficient quoting.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>Examples</title>
<refsect2>
<title>From the commandline</title>
<para>
Launching an application:
</para>
<programlisting>
gapplication launch org.example.fooview
</programlisting>
<para>
Opening a file with an application:
</para>
<programlisting>
gapplication launch org.example.fooview ~/file.foo
</programlisting>
<para>
Opening many files with an application:
</para>
<programlisting>
gapplication launch org.example.fooview ~/foos/*.foo
</programlisting>
<para>
Invoking an action on an application:
</para>
<programlisting>
gapplication action org.example.fooview create
</programlisting>
<para>
Invoking an action on an application, with an action:
</para>
<programlisting>
gapplication action org.example.fooview show-item '"item_id_828739"'
</programlisting>
</refsect2>
<refsect2>
<title>
From the <varname>Exec</varname> lines of a <filename class='extension'>.desktop</filename> file
</title>
<para>
The commandline interface of <command>gapplication</command> was designed so that it could be used
directly from the <varname>Exec</varname> line of a <filename class='extension'>.desktop</filename>
file.
</para>
<para>
You might want to do this to allow for backwards compatibility with implementations of the specification
that do not understand how to do D-Bus activation, without having to install a separate utility program.
</para>
<para>
Consider the following example:
</para>
<programlisting>
[Desktop Entry]
Version=1.1
Type=Application
Name=Foo Viewer
DBusActivatable=true
MimeType=image/x-foo;
Exec=gapplication launch org.example.fooview %F
Actions=gallery;create;
[Desktop Action gallery]
Name=Browse Gallery
Exec=gapplication action org.example.fooview gallery
[Desktop Action create]
Name=Create a new Foo!
Exec=gapplication action org.example.fooview create
</programlisting>
</refsect2>
<refsect2>
<title>From a script</title>
<para>
If installing an application that supports D-Bus activation you may still want to put a file in
<filename class='directory'>/usr/bin</filename> so that your program can be started from a terminal.
</para>
<para>
It is possible for this file to be a shell script. The script can handle arguments such as --help and
--version directly. It can also parse other command line arguments and convert them to uses of
<command>gapplication</command> to activate the application, open files, or invoke actions.
</para>
<para>
Here is a simplified example, as may be installed in <filename>/usr/bin/fooview</filename>:
</para>
<programlisting>
#!/bin/sh
case "$1" in
--help)
echo "see 'man fooview' for more information"
;;
--version)
echo "fooview 1.2"
;;
--gallery)
gapplication action org.example.fooview gallery
;;
--create)
gapplication action org.example.fooview create
;;
-*)
echo "unrecognised commandline argument"
exit 1
;;
*)
gapplication launch org.example.fooview "$@"
;;
esac
</programlisting>
</refsect2>
</refsect1>
<refsect1>
<title>See also</title>
<para>
<ulink url='http://standards.freedesktop.org/desktop-entry-spec/latest/'>Desktop Entry Specification</ulink>,
<citerefentry>
<refentrytitle>gdbus</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>xdg-open</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>desktop-file-validate</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

821
docs/reference/gio/gdbus-codegen.rst Normal file
View File

@ -0,0 +1,821 @@
.. _gdbus-codegen(1):
.. meta::
:copyright: Copyright 2011, 2013, 2016 Red Hat, Inc.
:copyright: Copyright 2013, 2022 Emmanuele Bassi
:copyright: Copyright 2017 Patrick Griffis
:copyright: Copyright 2018 Iñigo Martínez
:copyright: Copyright 2018, 2019 Endless Mobile, Inc.
:copyright: Copyright 2020 Endless OS Foundation, LLC
:copyright: Copyright 2020 Chun-wei Fan
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2011, 2013, 2016 Red Hat, Inc.
SPDX-FileCopyrightText: 2013, 2022 Emmanuele Bassi
SPDX-FileCopyrightText: 2017 Patrick Griffis
SPDX-FileCopyrightText: 2018 Iñigo Martínez
SPDX-FileCopyrightText: 2018, 2019 Endless Mobile, Inc.
SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC
SPDX-FileCopyrightText: 2020 Chun-wei Fan
SPDX-License-Identifier: LGPL-2.1-or-later
=============
gdbus-codegen
=============
--------------------------------------
D-Bus code and documentation generator
--------------------------------------
SYNOPSIS
--------
| **gdbus-codegen**
| [--help]
| [--interface-prefix *org.project.Prefix*]
| [--header | --body | --interface-info-header | --interface-info-body | --generate-c-code *OUTFILES*]
| [--c-namespace *YourProject*]
| [--c-generate-object-manager]
| [--c-generate-autocleanup none|objects|all]
| [--output-directory *OUTDIR* | --output *OUTFILE*]
| [--generate-docbook *OUTFILES*]
| [--generate-rst *OUTFILES*]
| [--pragma-once]
| [--xml-files *FILE*]
| [--symbol-decorator *DECORATOR* [--symbol-decorator-header *HEADER*] [--symbol-decorator-define *DEFINE*]]
| [--annotate *ELEMENT* *KEY* *VALUE*]…
| [--glib-min-required *VERSION*]
| [--glib-max-allowed *VERSION*]
| *FILE*…
DESCRIPTION
-----------
``gdbus-codegen`` is used to generate code and/or documentation for one or more
D-Bus interfaces.
``gdbus-codegen`` reads
`D-Bus Introspection XML <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>`_
from files passed as additional arguments on the command line and generates
output files. It currently supports generating C source code (via ``--body``) or
header (via ``--header``) and DocBook XML (via ``--generate-docbook``).
Alternatively, more restricted C source code and headers can be generated, which
just contain the interface information (as ``GDBusInterfaceInfo`` structures)
using ``--interface-info-body`` and ``--interface-info-header``.
GENERATING C CODE
-----------------
When generating C code, a ``GInterface`` derived type is generated for each
D-Bus interface. Additionally, for every generated type, ``FooBar``, two
concrete instantiatable types, ``FooBarProxy`` and ``FooBarSkeleton``,
implementing said interface are also generated. The former is derived from
``GDBusProxy`` and intended for use on the client side while the latter is
derived from the ``GDBusInterfaceSkeleton`` type making it easy to export on a
``GDBusConnection`` either directly or via a ``GDBusObjectManagerServer``
instance.
For C code generation either ``--body`` that generates source code, ``--header``
that generates headers, ``--interface-info-body`` that generates interface
information source code, or ``--interface-info-header`` that generates interface
information headers, can be used. These options must be used along with
``--output``, which is used to specify the file to output to.
Both files can be generated at the same time by using ``--generate-c-code``, but
this option is deprecated. In this case ``--output`` cannot be used due to the
generation of multiple files. Instead pass ``--output-directory`` to specify the
directory to put the output files in. By default the current directory will be
used.
The name of each generated C type is derived from the D-Bus interface name
stripped with the prefix given with ``--interface-prefix`` and with the dots
removed and initial characters capitalized. For example, for the D-Bus
interface ``com.acme.Coyote`` the name used is ``ComAcmeCoyote``. For the D-Bus
interface ``org.project.Bar.Frobnicator`` with ``--interface-prefix`` set to
``org.project.``, the name used is ``BarFrobnicator``.
For methods, signals and properties, if not specified, the name defaults to the
name of the method, signal or property.
Two forms of the name are used — the CamelCase form and the lower-case form. The
CamelCase form is used for the ``GType`` and struct name, while lower-case form
is used in function names. The lower-case form is calculated by converting from
CamelCase to lower-case and inserting underscores at word boundaries (using
certain heuristics).
If the value given by the ``org.gtk.GDBus.C.Name`` annotation or the
``--c-namespace`` option contains an underscore (sometimes called *Ugly_Case*),
then the camel-case name is derived by removing all underscores, and the
lower-case name is derived by lower-casing the string. This is useful in some
situations where abbreviations are used. For example, if the annotation is used
on the interface ``net.MyCorp.MyApp.iSCSITarget`` with the value
``iSCSI_Target`` the CamelCase form is ``iSCSITarget`` while the lower-case form
is ``iscsi_target``. If the annotation is used on the method ``EjectTheiPod``
with the value ``Eject_The_iPod``, the lower-case form is ``eject_the_ipod``.
GENERATING DOCBOOK DOCUMENTATION
--------------------------------
Each generated DocBook XML file (see the ``--generate-docbook`` option for
details) is a ``RefEntry`` article describing the D-Bus interface. (See the
`DocBook documentation <https://tdg.docbook.org/tdg/4.5/refentry.html>`_.)
GENERATING RESTRUCTUREDTEXT DOCUMENTATION
-----------------------------------------
Each generated reStructuredText file (see the ``--generate-rst`` option for
details) is a plain text
`reStructuredText <https://docutils.sourceforge.io/rst.html>`_ document
describing the D-Bus interface.
OPTIONS
-------
The following options are supported:
``-h``, ``--help``
Show help and exit.
``--xml-files`` *FILE*
This option is deprecated; use positional arguments instead. The D-Bus
introspection XML file.
``--interface-prefix`` *org.project.Prefix.*
A prefix to strip from all D-Bus interface names when
calculating the type name for the C binding and the DocBook ``sortas``
`attribute <https://tdg.docbook.org/tdg/4.5/primary.html>`_.
``--generate-docbook`` *OUTFILES*
Generate DocBook Documentation for each D-Bus interface and put it in
``OUTFILES-NAME.xml`` where ``NAME`` is a placeholder for the interface
name, e.g. ``net.Corp.FooBar`` and so on.
Pass ``--output-directory`` to specify the directory to put the output files
in. By default the current directory will be used.
``--generate-rst`` *OUTFILES*
Generate reStructuredText Documentation for each D-Bus interface and put it in
``OUTFILES-NAME.rst`` where ``NAME`` is a placeholder for the interface
name, e.g. ``net.Corp.FooBar`` and so on.
Pass ``--output-directory`` to specify the directory to put the output files
in. By default the current directory will be used.
``--generate-c-code`` *OUTFILES*
Generate C code for all D-Bus interfaces and put it in ``OUTFILES.c`` and
``OUTFILES.h`` including any sub-directories. If you want the files to be
output in a different location use ``--output-directory`` as ``OUTFILES.h``
including sub-directories will be referenced from ``OUTFILES.c``.
The full paths would then be
``$(OUTDIR)/$(dirname $OUTFILES)/$(basename $OUTFILES).{c,h}``.
``--c-namespace`` *YourProject*
The namespace to use for generated C code. This is expected to be in
`CamelCase <https://en.wikipedia.org/wiki/Camel_case>`_ or *Ugly_Case* (see
above).
``--pragma-once``
If this option is passed, the
`#pragma once <https://en.wikipedia.org/wiki/Pragma_once>`_ preprocessor
directive is used instead of include guards.
``--c-generate-object-manager``
If this option is passed, suitable ``GDBusObject``, ``GDBusObjectProxy``,
``GDBusObjectSkeleton`` and ``GDBusObjectManagerClient`` subclasses are
generated.
``--c-generate-autocleanup`` none|objects|all
This option influences what types autocleanup functions are
generated for. ``none`` means to not generate any autocleanup functions.
``objects`` means to generate them for object types, and ``all`` means to
generate them for object types and interfaces. The default is ``objects``
due to a corner case in backwards compatibility with a few projects,
but you should likely switch your project to use ``all``.
This option was added in GLib 2.50.
``--output-directory`` *OUTDIR*
Directory to output generated source to. Equivalent to changing directory
before generation.
This option cannot be used with ``--body``, ``--header``,
``--interface-info-body`` or ``--interface-info-header``; and ``--output``
must be used.
``--header``
If this option is passed, it will generate the header code and write it to the
disk by using the path and file name provided by ``--output``.
Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
are not allowed to be used along with ``--header`` and ``--body`` options,
because these options are used to generate only one file.
``--body``
If this option is passed, it will generate the source code and write it to the
disk by using the path and file name provided by ``--output``.
Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
are not allowed to be used along with ``--header`` and ``--body`` options,
because these options are used to generate only one file.
``--interface-info-header``
If this option is passed, it will generate the header code for the
``GDBusInterfaceInfo`` structures only and will write it to the disk by using
the path and file name provided by ``--output``.
Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
are not allowed to be used along with the ``--interface-info-header`` and
``--interface-info-body`` options, because these options are used to generate
only one file.
``--interface-info-body``
If this option is passed, it will generate the source code for the
``GDBusInterfaceInfo`` structures only and will write it to the disk by using
the path and file name provided by ``--output``.
Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
are not allowed to be used along with the ``--interface-info-header`` and
``--interface-info-body`` options, because these options are used to generate
only one file.
``--symbol-decorator`` *DECORATOR*
If a ``DECORATOR`` is passed in with this option, all the generated function
prototypes in the generated header will be marked with ``DECORATOR``. This can
be used, for instance, to export symbols from code generated with
``gdbus-codegen``.
This option was added in GLib 2.66.
``--symbol-decorator-header`` *HEADER*
If a ``HEADER`` is passed in with this option, the generated header will put a
``#include HEADER`` before the rest of the items, except for the inclusion
guards or ``#pragma once`` (if ``--pragma-once`` is used). This is used if
using another header file is needed for the decorator passed in via
``--symbol-decorator`` to be defined.
This option was added in GLib 2.66.
This option can only be used if ``--symbol-decorator`` is used.
``--symbol-decorator-define`` *DEFINE*
If a ``DEFINE`` is passed in with this option, the generated source will add a
``#define DEFINE`` before the rest of the items. This is used if a particular
macro is needed to ensure the decorator passed in via ``--symbol-decorator``
uses the correct definition when the generated source is being compiled.
This option was added in GLib 2.66.
This option can only be used if ``--symbol-decorator`` is used.
``--output`` *OUTFILE*
The full path where the header (``--header``, ``--interface-info-header``) or
the source code (``--body``, ``--interface-info-body``) will be written, using
the path and filename provided by ``--output``. The full path could be
something like ``$($OUTFILE).{c,h}``.
Using ``--generate-c-code``, ``--generate-docbook`` or ``--output-directory``
is not allowed along with ``--output``, because the latter is used to generate
only one file.
Since GLib 2.80, if *OUTFILE* is the literal string ``-``, the header
or source code will be written to standard output.
For ``--body`` and ``--interface-info-body``, the generated code will not
automatically ``#include`` a corresponding header file when writing to
standard output, because there is no obvious name for that header file.
This might make it necessary to use ``cc -include foo.h``, or generate a
filename like ``foo-impl.h`` and ``#include`` it into a wrapper ``.c`` file.
For ``--header`` and ``--interface-info-header``, there is no obvious
name for a traditional multiple-inclusion guard when writing to standard
output, so using the ``--pragma-once`` option is recommended.
In the rare situation that the intended output filename starts with ``-``,
it should be prefixed with ``./``.
``--annotate`` *ELEMENT* *KEY* *VALUE*
Used to inject D-Bus annotations into the given XML files. It can be used with
interfaces, methods, signals, properties and arguments in the following way::
gdbus-codegen --c-namespace MyApp \
--generate-c-code myapp-generated \
--annotate "org.project.InterfaceName" \
org.gtk.GDBus.C.Name MyFrobnicator \
--annotate "org.project.InterfaceName:Property" \
bar bat \
--annotate "org.project.InterfaceName.Method()" \
org.freedesktop.DBus.Deprecated true \
--annotate "org.project.InterfaceName.Method()[arg_name]" \
snake hiss \
--annotate "org.project.InterfaceName::Signal" \
cat meow \
--annotate "org.project.InterfaceName::Signal[arg_name]" \
dog wuff \
myapp-dbus-interfaces.xml
Any UTF-8 string can be used for *KEY* and *VALUE*.
``--glib-min-required`` *VERSION*
Specifies the minimum version of GLib which the code generated by
``gdbus-codegen`` can depend on. This may be used to make
backwards-incompatible changes in the output or behaviour of ``gdbus-codegen``
in future, which users may opt in to by increasing the value they pass for
``--glib-min-required``. If this option is not passed, the output from
``gdbus-codegen`` is guaranteed to be compatible with all versions of GLib
from 2.30 upwards, as that is when ``gdbus-codegen`` was first released.
Note that some version parameters introduce incompatible changes: all callers
of the generated code might need to be updated, and if the generated code is
part of a library’s API or ABI, then increasing the version parameter can
result in an API or ABI break.
The version number must be of the form ``MAJOR.MINOR.MICRO``, where all parts
are integers. ``MINOR`` and ``MICRO`` are optional. The version number may not
be smaller than ``2.30``.
If the version number is ``2.64`` or greater, the generated code will
have the following features:
1. If a method has ``h`` (file descriptor) parameter(s), a ``GUnixFDList``
parameter will exist in the generated code for it (whereas previously the
annotation ``org.gtk.GDBus.C.UnixFD`` was required), and
2. Method call functions will have two additional arguments to allow the user
to specify ``GDBusCallFlags`` and a timeout value, as is possible when
using ``g_dbus_proxy_call()``.
``--glib-max-allowed`` *VERSION*
Specifies the maximum version of GLib which the code generated by
``gdbus-codegen`` can depend on. This may be used to ensure that code
generated by ``gdbus-codegen`` is compilable with specific older versions of
GLib that your software has to support.
The version number must be of the form ``MAJOR.MINOR.MICRO``, where all parts
are integers. ``MINOR`` and ``MICRO`` are optional. The version number must be
greater than or equal to that passed to ``--glib-min-required``.
It defaults to the version of GLib which provides this ``gdbus-codegen``.
SUPPORTED D-BUS ANNOTATIONS
---------------------------
The following D-Bus annotations are supported by ``gdbus-codegen``:
``org.freedesktop.DBus.Deprecated``
Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and
``<property>`` element to specify that the element is deprecated if its value
is ``true``. Note that this annotation is defined in the
`D-Bus specification <https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format>`_
and can only assume the values ``true`` and ``false``. In particular, you
cannot specify the version that the element was deprecated in nor any helpful
deprecation message. Such information should be added to the element
documentation instead.
When generating C code, this annotation is used to add ``G_GNUC_DEPRECATED``
to generated functions for the element.
When generating DocBook XML, a deprecation warning will appear along the
documentation for the element.
``org.gtk.GDBus.Since``
Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and
``<property>`` element to specify the version (any free-form string but
compared using a version-aware sort function) the element appeared in.
When generating C code, this field is used to ensure
function pointer order for preserving ABI/API, see ‘STABILITY GUARANTEES’.
When generating DocBook XML, the value of this tag appears in the
documentation.
``org.gtk.GDBus.DocString``
A string with DocBook content for documentation. This annotation can
be used on ``<interface>``, ``<method>``, ``<signal>``, ``<property>`` and
``<arg>`` elements.
``org.gtk.GDBus.DocString.Short``
A string with DocBook content for short/brief documentation. This annotation
can only be used on ``<interface>`` elements.
``org.gtk.GDBus.C.Name``
Can be used on any ``<interface>``, ``<method>``, ``<signal>`` and
``<property>`` element to specify the name to use when generating C code. The
value is expected to be in
`CamelCase <https://en.wikipedia.org/wiki/Camel_case>`_ or *Ugly_Case* (see
above).
``org.gtk.GDBus.C.ForceGVariant``
If set to a non-empty string, a ``GVariant`` instance will be used instead of
the natural C type. This annotation can be used on any ``<arg>`` and
``<property>`` element.
``org.gtk.GDBus.C.UnixFD``
If set to a non-empty string, the generated code will include parameters to
exchange file descriptors using the ``GUnixFDList`` type. This annotation can
be used on ``<method>`` elements.
As an easier alternative to using the ``org.gtk.GDBus.DocString`` annotation,
note that parser used by ``gdbus-codegen`` parses XML comments in a way similar
to `gtk-doc <https://developer-old.gnome.org/gtk-doc-manual/stable/>`_::
<!--
net.Corp.Bar:
@short_description: A short description
A <emphasis>longer</emphasis> description.
This is a new paragraph.
-->
<interface name="net.corp.Bar">
<!--
FooMethod:
@greeting: The docs for greeting parameter.
@response: The docs for response parameter.
The docs for the actual method.
-->
<method name="FooMethod">
<arg name="greeting" direction="in" type="s"/>
<arg name="response" direction="out" type="s"/>
</method>
<!--
BarSignal:
@blah: The docs for blah parameter.
@boo: The docs for boo parameter.
@since: 2.30
The docs for the actual signal.
-->
<signal name="BarSignal">
<arg name="blah" type="s"/>
<arg name="boo" type="s"/>
</signal>
<!-- BazProperty: The docs for the property. -->
<property name="BazProperty" type="s" access="read"/>
</interface>
Note that ``@since`` can be used in any inline documentation bit (e.g. for
interfaces, methods, signals and properties) to set the ``org.gtk.GDBus.Since``
annotation. For the ``org.gtk.GDBus.DocString`` annotation (and inline
comments), note that substrings of the form ``#net.Corp.Bar``,
``net.Corp.Bar.FooMethod()``, ``#net.Corp.Bar::BarSignal`` and
``#net.Corp.InlineDocs:BazProperty`` are all expanded to links to the respective
interface, method, signal and property. Additionally, substrings starting with
``@`` and ``%`` characters are rendered as
`parameter <https://tdg.docbook.org/tdg/4.5/parameter.html>`_ and
`constant <https://tdg.docbook.org/tdg/4.5/constant.html>`_ respectively.
If both XML comments and ``org.gtk.GDBus.DocString`` or
``org.gtk.GDBus.DocString.Short`` annotations are present, the latter wins.
EXAMPLE
-------
Consider the following D-Bus Introspection XML::
<node>
<interface name="net.Corp.MyApp.Frobber">
<method name="HelloWorld">
<arg name="greeting" direction="in" type="s"/>
<arg name="response" direction="out" type="s"/>
</method>
<signal name="Notification">
<arg name="icon_blob" type="ay"/>
<arg name="height" type="i"/>
<arg name="messages" type="as"/>
</signal>
<property name="Verbose" type="b" access="readwrite"/>
</interface>
</node>
If ``gdbus-codegen`` is used on this file like this::
gdbus-codegen --generate-c-code myapp-generated \
--c-namespace MyApp \
--interface-prefix net.corp.MyApp. \
net.Corp.MyApp.Frobber.xml
two files called ``myapp-generated.[ch]`` are generated. The files provide an
abstract ``GTypeInterface`` derived type called ``MyAppFrobber`` as well as two
instantiatable types with the same name but suffixed with ``Proxy`` and
``Skeleton``. The generated file, roughly, contains the following facilities::
/* GType macros for the three generated types */
#define MY_APP_TYPE_FROBBER (my_app_frobber_get_type ())
#define MY_APP_TYPE_FROBBER_SKELETON (my_app_frobber_skeleton_get_type ())
#define MY_APP_TYPE_FROBBER_PROXY (my_app_frobber_proxy_get_type ())
typedef struct _MyAppFrobber MyAppFrobber; /* Dummy typedef */
typedef struct
{
GTypeInterface parent_iface;
/* Signal handler for the ::notification signal */
void (*notification) (MyAppFrobber *proxy,
GVariant *icon_blob,
gint height,
const gchar* const *messages);
/* Signal handler for the ::handle-hello-world signal */
gboolean (*handle_hello_world) (MyAppFrobber *proxy,
GDBusMethodInvocation *invocation,
const gchar *greeting);
} MyAppFrobberIface;
/* Asynchronously calls HelloWorld() */
void
my_app_frobber_call_hello_world (MyAppFrobber *proxy,
const gchar *greeting,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gp ointer user_data);
gboolean
my_app_frobber_call_hello_world_finish (MyAppFrobber *proxy,
gchar **out_response,
GAsyncResult *res,
GError **error);
/* Synchronously calls HelloWorld(). Blocks calling thread. */
gboolean
my_app_frobber_call_hello_world_sync (MyAppFrobber *proxy,
const gchar *greeting,
gchar **out_response,
GCancellable *cancellable,
GError **error);
/* Completes handling the HelloWorld() method call */
void
my_app_frobber_complete_hello_world (MyAppFrobber *object,
GDBusMethodInvocation *invocation,
const gchar *response);
/* Emits the ::notification signal / Notification() D-Bus signal */
void
my_app_frobber_emit_notification (MyAppFrobber *object,
GVariant *icon_blob,
gint height,
const gchar* const *messages);
/* Gets the :verbose GObject property / Verbose D-Bus property.
* Does no blocking I/O.
*/
gboolean my_app_frobber_get_verbose (MyAppFrobber *object);
/* Sets the :verbose GObject property / Verbose D-Bus property.
* Does no blocking I/O.
*/
void my_app_frobber_set_verbose (MyAppFrobber *object,
gboolean value);
/* Gets the interface info */
GDBusInterfaceInfo *my_app_frobber_interface_info (void);
/* Creates a new skeleton object, ready to be exported */
MyAppFrobber *my_app_frobber_skeleton_new (void);
/* Client-side proxy constructors.
*
* Additionally, _new_for_bus(), _new_for_bus_finish() and
* _new_for_bus_sync() proxy constructors are also generated.
*/
void
my_app_frobber_proxy_new (GDBusConnection *connection,
GDBusProxyFlags flags,
const gchar *name,
const gchar *object_path,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
MyAppFrobber *
my_app_frobber_proxy_new_finish (GAsyncResult *res,
GError **error);
MyAppFrobber *
my_app_frobber_proxy_new_sync (GDBusConnection *connection,
GDBusProxyFlags flags,
const gchar *name,
const gchar *object_path,
GCancellable *cancellable,
GError **error);
Thus, for every D-Bus method, there will be three C functions for calling the
method, one ``GObject`` signal for handling an incoming call and one C function
for completing an incoming call. For every D-Bus signal, there’s one ``GObject``
signal and one C function for emitting it. For every D-Bus property, two C
functions are generated (one setter, one getter) and one ``GObject`` property.
The following table summarizes the generated facilities and where they are
applicable:
.. table::
:widths: auto
==================== ========================================================= =================================================================================================================
Symbol type Client Server
==================== ========================================================= =================================================================================================================
Types Use ``MyAppFrobberProxy``. Any type implementing the ``MyAppFrobber`` interface.
Methods Use ``m_a_f_hello_world()`` to call. Receive via the ``handle_hello_world()`` signal handler. Complete the call with ``m_a_f_complete_hello_world()``.
Signals Connect to the ``::notification`` signal. Use ``m_a_f_emit_notification()`` to emit signal.
Properties (Reading) Use ``m_a_f_get_verbose()`` or the ``:verbose`` property. Implement the ``get_property()`` vfunc of ``GObject``.
Properties (writing) Use ``m_a_f_set_verbose()`` or the ``:verbose`` property. Implement the ``set_property()`` vfunc of ``GObject``.
==================== ========================================================= =================================================================================================================
Client-side usage
^^^^^^^^^^^^^^^^^
You can use the generated proxy type with the generated constructors::
MyAppFrobber *proxy;
GError *error;
error = NULL;
proxy = my_app_frobber_proxy_new_for_bus_sync (
G_BUS_TYPE_SESSION,
G_DBUS_PROXY_FLAGS_NONE,
"net.Corp.MyApp", /* bus name */
"/net/Corp/MyApp/SomeFrobber", /* object */
NULL, /* GCancellable* */
&error);
/* do stuff with proxy */
g_object_unref (proxy);
Instead of using the generic ``GDBusProxy`` facilities, one can use the
generated methods such as ``my_app_frobber_call_hello_world()`` to invoke
the ``net.Corp.MyApp.Frobber.HelloWorld()`` D-Bus method, connect to the
``::notification`` ``GObject`` signal to receive the
``net.Corp.MyApp.Frobber::Notification`` D-Bus signal and get/set the
``net.Corp.MyApp.Frobber:Verbose`` D-Bus Property using either the ``GObject``
property ``:verbose`` or the ``my_app_get_verbose()`` and
``my_app_set_verbose()`` methods. Use the standard ``GObject::notify`` signal to
listen to property changes.
Note that all property access is via the ``GDBusProxy`` property cache so no I/O
is ever done when reading properties. Also note that setting a property will
cause the ``org.freedesktop.DBus.Properties.Set`` method
(`documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>`_)
to be called on the remote object. This call, however, is asynchronous so
setting a property won’t block. Further, the change is delayed and no error
checking is possible.
Server-side usage
^^^^^^^^^^^^^^^^^
The generated ``MyAppFrobber`` interface is designed so it is easy to implement
it in a ``GObject`` subclass. For example, to handle ``HelloWorld()`` method
invocations, set the vfunc for ``handle_hello_hello_world()`` in the
``MyAppFrobberIface`` structure. Similarly, to handle the
``net.Corp.MyApp.Frobber:Verbose`` property override the ``:verbose``
``GObject`` property from the subclass. To emit a signal, use e.g.
``my_app_emit_signal()`` or ``g_signal_emit_by_name()``.
Instead of subclassing, it is often easier to use the generated
``MyAppFrobberSkeleton`` subclass. To handle incoming method calls, use
``g_signal_connect()`` with the ``::handle-*`` signals and instead of
overriding the ``get_property()`` and ``set_property()`` vfuncs from
``GObject``, use ``g_object_get()`` and ``g_object_set()`` or the generated
property getters and setters (the generated class has an internal property bag
implementation).
For example::
static gboolean
on_handle_hello_world (MyAppFrobber *interface,
GDBusMethodInvocation *invocation,
const gchar *greeting,
gpointer user_data)
{
if (g_strcmp0 (greeting, "Boo") != 0)
{
gchar *response;
response = g_strdup_printf ("Word! You said ‘%s’.", greeting);
my_app_complete_hello_world (interface, invocation, response);
g_free (response);
}
else
{
g_dbus_method_invocation_return_error (invocation,
MY_APP_ERROR,
MY_APP_ERROR_NO_WHINING,
"Hey, %s, there will be no whining!",
g_dbus_method_invocation_get_sender (invocation));
}
return TRUE;
}
[…]
interface = my_app_frobber_skeleton_new ();
my_app_frobber_set_verbose (interface, TRUE);
g_signal_connect (interface,
"handle-hello-world",
G_CALLBACK (on_handle_hello_world),
some_user_data);
[…]
error = NULL;
if (!g_dbus_interface_skeleton_export (G_DBUS_INTERFACE_SKELETON (interface),
connection,
"/path/of/dbus_object",
&error))
{
/* handle error */
}
To facilitate atomic changesets (multiple properties changing at the same time),
``GObject::notify`` signals are queued up when received. The queue is drained in
an idle handler (which is called from the thread-default main loop of the thread
where the skeleton object was constructed) and will cause emissions of the
``org.freedesktop.DBus.Properties::PropertiesChanged``
(`documentation <https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>`_)
signal with all the properties that have changed. Use
``g_dbus_interface_skeleton_flush()`` or ``g_dbus_object_skeleton_flush()`` to
empty the queue immediately. Use ``g_object_freeze_notify()`` and
``g_object_thaw_notify()`` for atomic changesets if on a different thread.
C TYPE MAPPING
--------------
Scalar types (type strings ``b``, ``y``, ``n``, ``q``, ``i``, ``u``, ``x``,
``t`` and ``d``), strings (type strings ``s``, ``ay``, ``o`` and ``g``) and
arrays of strings (type strings ``as``, ``ao`` and ``aay``) are mapped to the
natural types, e.g. ``gboolean``, ``gdouble``, ``gint``, ``gchar*``, ``gchar**``
and so on. Everything else is mapped to the ``GVariant`` type.
This automatic mapping can be turned off by using the annotation
``org.gtk.GDBus.C.ForceGVariant`` — if used then a ``GVariant`` is always
exchanged instead of the corresponding native C type. This annotation may be
convenient to use when using bytestrings (type string ``ay``) for data that
could have embedded nul bytes.
STABILITY GUARANTEES
--------------------
The generated C functions are guaranteed to not change their ABI. That is, if a
method, signal or property does not change its signature in the introspection
XML, the generated C functions will not change their C ABI either. The ABI of
the generated instance and class structures will be preserved as well.
The ABI of the generated ``GType`` instances will be preserved only if the
``org.gtk.GDBus.Since`` annotation is used judiciously — this is because the
VTable for the ``GInterface`` relies on function pointers for signal handlers.
Specifically, if a D-Bus method, property or signal or is added to a D-Bus
interface, then ABI of the generated ``GInterface`` type is preserved if, and
only if, each added method, property signal is annotated with the
``org.gtk.GDBus.Since`` annotation using a greater version number than previous
versions.
The generated C code currently happens to be annotated with
`gtk-doc <https://developer-old.gnome.org/gtk-doc-manual/stable/>`_ and
`GObject Introspection <https://gi.readthedocs.io/en/latest/>`_ comments and
annotations. The layout and contents might change in the future so no guarantees
about e.g. ``SECTION`` usage etc. are given.
While the generated DocBook for D-Bus interfaces isn’t expected to change, no
guarantees are given at this point.
It is important to note that the generated code should not be checked into
version control systems, nor it should be included in distributed source
archives.
BUGS
----
Please send bug reports to either the distribution bug tracker or the
`upstream bug tracker <https://gitlab.gnome.org/GNOME/glib/issues/new>`_.
SEE ALSO
--------
`gdbus(1) <man:gdbus(1)>`_

1193
docs/reference/gio/gdbus-codegen.xml
View File

File diff suppressed because it is too large Load Diff

1
docs/reference/gio/gdbus-object-manager-example/.gitignore vendored
View File

@ -1 +0,0 @@
gdbus-object-manager-example-overrides.txt

19
docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-docs.xml
View File

@ -1,19 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<book lang="en" xmlns:xi="http://www.w3.org/2003/XInclude">
<part>
<title>GDBus ObjctManager Example</title>
<chapter>
<title>Interfaces</title>
<xi:include href="xml/ExampleAnimal.xml"/>
<xi:include href="xml/ExampleCat.xml"/>
<xi:include href="xml/ExampleObject.xml"/>
<xi:include href="xml/ExampleObjectManagerClient.xml"/>
</chapter>
</part>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

161
docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-sections.txt
View File

@ -1,161 +0,0 @@
<SECTION>
<FILE>ExampleAnimal</FILE>
<TITLE>ExampleAnimal</TITLE>
ExampleAnimal
ExampleAnimalIface
example_animal_interface_info
example_animal_override_properties
example_animal_call_poke
example_animal_call_poke_finish
example_animal_call_poke_sync
example_animal_complete_poke
example_animal_emit_jumped
example_animal_get_mood
example_animal_get_foo
example_animal_get_bar
example_animal_dup_mood
example_animal_dup_foo
example_animal_dup_bar
example_animal_set_mood
example_animal_set_foo
example_animal_set_bar
ExampleAnimalProxy
ExampleAnimalProxyClass
example_animal_proxy_new
example_animal_proxy_new_finish
example_animal_proxy_new_sync
example_animal_proxy_new_for_bus
example_animal_proxy_new_for_bus_finish
example_animal_proxy_new_for_bus_sync
ExampleAnimalSkeleton
ExampleAnimalSkeletonClass
example_animal_skeleton_new
<SUBSECTION Standard>
example_animal_get_type
example_animal_proxy_get_type
example_animal_skeleton_get_type
ExampleAnimalSkeletonPrivate
ExampleAnimalProxyPrivate
EXAMPLE_TYPE_ANIMAL
EXAMPLE_TYPE_ANIMAL_PROXY
EXAMPLE_TYPE_ANIMAL_SKELETON
EXAMPLE_ANIMAL
EXAMPLE_ANIMAL_GET_IFACE
EXAMPLE_ANIMAL_PROXY
EXAMPLE_ANIMAL_PROXY_CLASS
EXAMPLE_ANIMAL_PROXY_GET_CLASS
EXAMPLE_ANIMAL_SKELETON
EXAMPLE_ANIMAL_SKELETON_CLASS
EXAMPLE_ANIMAL_SKELETON_GET_CLASS
EXAMPLE_IS_ANIMAL
EXAMPLE_IS_ANIMAL_PROXY
EXAMPLE_IS_ANIMAL_PROXY_CLASS
EXAMPLE_IS_ANIMAL_SKELETON
EXAMPLE_IS_ANIMAL_SKELETON_CLASS
</SECTION>
<SECTION>
<FILE>ExampleCat</FILE>
<TITLE>ExampleCat</TITLE>
ExampleCat
ExampleCatIface
example_cat_interface_info
example_cat_override_properties
ExampleCatProxy
ExampleCatProxyClass
example_cat_proxy_new
example_cat_proxy_new_finish
example_cat_proxy_new_sync
example_cat_proxy_new_for_bus
example_cat_proxy_new_for_bus_finish
example_cat_proxy_new_for_bus_sync
ExampleCatSkeleton
ExampleCatSkeletonClass
example_cat_skeleton_new
<SUBSECTION Standard>
example_cat_get_type
example_cat_proxy_get_type
example_cat_skeleton_get_type
ExampleCatProxyPrivate
ExampleCatSkeletonPrivate
EXAMPLE_TYPE_CAT
EXAMPLE_TYPE_CAT_PROXY
EXAMPLE_TYPE_CAT_SKELETON
EXAMPLE_CAT
EXAMPLE_CAT_GET_IFACE
EXAMPLE_CAT_PROXY
EXAMPLE_CAT_PROXY_CLASS
EXAMPLE_CAT_PROXY_GET_CLASS
EXAMPLE_CAT_SKELETON
EXAMPLE_CAT_SKELETON_CLASS
EXAMPLE_CAT_SKELETON_GET_CLASS
EXAMPLE_IS_CAT
EXAMPLE_IS_CAT_PROXY
EXAMPLE_IS_CAT_PROXY_CLASS
EXAMPLE_IS_CAT_SKELETON
EXAMPLE_IS_CAT_SKELETON_CLASS
</SECTION>
<SECTION>
<FILE>ExampleObject</FILE>
<TITLE>ExampleObject</TITLE>
ExampleObject
ExampleObjectIface
example_object_get_animal
example_object_get_cat
example_object_peek_animal
example_object_peek_cat
ExampleObjectProxy
ExampleObjectProxyClass
example_object_proxy_new
ExampleObjectSkeleton
ExampleObjectSkeletonClass
example_object_skeleton_new
example_object_skeleton_set_animal
example_object_skeleton_set_cat
<SUBSECTION Standard>
example_object_get_type
example_object_proxy_get_type
example_object_skeleton_get_type
ExampleObjectProxyPrivate
ExampleObjectSkeletonPrivate
EXAMPLE_IS_OBJECT
EXAMPLE_IS_OBJECT_PROXY
EXAMPLE_IS_OBJECT_PROXY_CLASS
EXAMPLE_IS_OBJECT_SKELETON
EXAMPLE_IS_OBJECT_SKELETON_CLASS
EXAMPLE_OBJECT
EXAMPLE_OBJECT_GET_IFACE
EXAMPLE_OBJECT_PROXY
EXAMPLE_OBJECT_PROXY_CLASS
EXAMPLE_OBJECT_PROXY_GET_CLASS
EXAMPLE_OBJECT_SKELETON
EXAMPLE_OBJECT_SKELETON_CLASS
EXAMPLE_OBJECT_SKELETON_GET_CLASS
EXAMPLE_TYPE_OBJECT
EXAMPLE_TYPE_OBJECT_PROXY
EXAMPLE_TYPE_OBJECT_SKELETON
</SECTION>
<SECTION>
<FILE>ExampleObjectManagerClient</FILE>
<TITLE>ExampleObjectManagerClient</TITLE>
ExampleObjectManagerClient
ExampleObjectManagerClientClass
example_object_manager_client_get_proxy_type
example_object_manager_client_new
example_object_manager_client_new_finish
example_object_manager_client_new_sync
example_object_manager_client_new_for_bus
example_object_manager_client_new_for_bus_finish
example_object_manager_client_new_for_bus_sync
<SUBSECTION Standard>
example_object_manager_client_get_type
EXAMPLE_IS_OBJECT_MANAGER_CLIENT
EXAMPLE_IS_OBJECT_MANAGER_CLIENT_CLASS
EXAMPLE_OBJECT_MANAGER_CLIENT
EXAMPLE_OBJECT_MANAGER_CLIENT_CLASS
EXAMPLE_OBJECT_MANAGER_CLIENT_GET_CLASS
EXAMPLE_TYPE_OBJECT_MANAGER_CLIENT
ExampleObjectManagerClientPrivate
</SECTION>

11
docs/reference/gio/gdbus-object-manager-example/meson.build
View File

@ -1,11 +0,0 @@
gdbus_object_manager_example_doc = gnome.gtkdoc('gdbus-object-manager-example',
main_xml : 'gdbus-object-manager-example-docs.xml',
namespace : 'example',
dependencies : [libgdbus_example_objectmanager_dep],
src_dir : 'gio/tests/gdbus-object-manager-example',
scan_args : [
'--rebuild-types',
],
install : false,
)

278
docs/reference/gio/gdbus.rst Normal file
View File

@ -0,0 +1,278 @@
.. _gdbus(1):
.. meta::
:copyright: Copyright 2010, 2011, 2012, 2020 Red Hat, Inc.
:copyright: Copyright 2015 Collabora, Ltd.
:copyright: Copyright 2021 Endless OS Foundation, LLC
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2010, 2011, 2012, 2020 Red Hat, Inc.
SPDX-FileCopyrightText: 2015 Collabora, Ltd.
SPDX-FileCopyrightText: 2021 Endless OS Foundation, LLC
SPDX-License-Identifier: LGPL-2.1-or-later
=====
gdbus
=====
-----------------------------------
Tool for working with D-Bus objects
-----------------------------------
SYNOPSIS
--------
| **gdbus** introspect [--system | --session | --address *address*] --dest *bus_name* --object-path */path/to/object* [--xml] [--recurse] [--only-properties]
| **gdbus** monitor [--system | --session | --address *address*] --dest *bus_name* [--object-path */path/to/object*]
| **gdbus** call [--system | --session | --address *address*] --dest *bus_name* --object-path */path/to/object* --method *org.project.InterfaceName.MethodName* [--timeout *seconds* | --interactive] [*ARG*…]
| **gdbus** emit [--system | --session | --address *address*] --object-path */path/to/object* --signal *org.project.InterfaceName.SignalName* [--dest *unique_bus_name*] [*ARG*…]
| **gdbus** wait [--system | --session | --address *address*] --activate *bus_name* [--timeout *seconds*] *bus_name*
| **gdbus** help
DESCRIPTION
-----------
``gdbus`` is a simple tool for working with D-Bus objects.
COMMANDS
--------
``introspect``
Prints out interfaces and property values for a remote object. For this to
work, the owner of the object needs to implement the
``org.freedesktop.DBus.Introspectable`` interface. If the ``--xml`` option is
used, the returned introspection XML is printed, otherwise a parsed pretty
representation is printed. The ``--recurse`` option can be used to introspect
children (and their children and so on) and the ``--only-properties`` option
can be used to only print the interfaces with properties.
``monitor``
Monitors one or all objects owned by the owner of ``bus_name``.
``call``
Invokes a method on a remote object. Each argument to pass to the method must
be specified as a serialized ``GVariant`` except that strings do not need
explicit quotes. The return values are printed out as serialized ``GVariant``
values.
``emit``
Emits a signal. Each argument to include in the signal must be specified as a
serialized ``GVariant`` except that strings do not need explicit quotes.
``wait``
Waits until ``bus_name`` is owned by some process on the bus. If the
``--activate`` is specified, that bus name will be auto-started first. It may
be the same as the bus name being waited for, or different.
``help``
Prints help and exits.
BASH COMPLETION
---------------
``gdbus`` ships with a bash completion script to complete commands,
destinations, bus names, object paths and interface/method names.
EXAMPLES
--------
This shows how to introspect an object — note that the value of each property is
displayed::
$ gdbus introspect --system \
--dest org.freedesktop.NetworkManager \
--object-path /org/freedesktop/NetworkManager/Devices/0
node /org/freedesktop/NetworkManager/Devices/0 {
interface org.freedesktop.DBus.Introspectable {
methods:
Introspect(out s data);
};
interface org.freedesktop.DBus.Properties {
methods:
Get(in s interface,
in s propname,
out v value);
Set(in s interface,
in s propname,
in v value);
GetAll(in s interface,
out a{sv} props);
};
interface org.freedesktop.NetworkManager.Device.Wired {
signals:
PropertiesChanged(a{sv} arg_0);
properties:
readonly b Carrier = false;
readonly u Speed = 0;
readonly s HwAddress = '00:1D:72:88:BE:97';
};
interface org.freedesktop.NetworkManager.Device {
methods:
Disconnect();
signals:
StateChanged(u arg_0,
u arg_1,
u arg_2);
properties:
readonly u DeviceType = 1;
readonly b Managed = true;
readwrite o Ip6Config = '/';
readwrite o Dhcp4Config = '/';
readwrite o Ip4Config = '/';
readonly u State = 2;
readwrite u Ip4Address = 0;
readonly u Capabilities = 3;
readonly s Driver = 'e1000e';
readwrite s Interface = 'eth0';
readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
};
};
The ``--recurse`` and ``--only-properties`` options can be useful when wanting
to inspect all objects owned by a particular process::
$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse --only-properties
node / {
node /org {
node /org/freedesktop {
node /org/freedesktop/UPower {
interface org.freedesktop.UPower {
properties:
readonly b IsDocked = true;
readonly b LidForceSleep = false;
readonly b LidIsPresent = false;
readonly b LidIsClosed = false;
readonly b OnLowBattery = false;
readonly b OnBattery = false;
readonly b CanHibernate = true;
readonly b CanSuspend = true;
readonly s DaemonVersion = '0.9.10';
};
node /org/freedesktop/UPower/Policy {
};
node /org/freedesktop/UPower/Wakeups {
interface org.freedesktop.UPower.Wakeups {
properties:
readonly b HasCapability = true;
};
};
};
};
};
};
In a similar fashion, the ``introspect`` command can be used to learn details
about the ``Notify`` method::
[…]
interface org.freedesktop.Notifications {
methods:
GetServerInformation(out s return_name,
out s return_vendor,
out s return_version,
out s return_spec_version);
GetCapabilities(out as return_caps);
CloseNotification(in u id);
Notify(in s app_name,
in u id,
in s icon,
in s summary,
in s body,
in as actions,
in a{sv} hints,
in i timeout,
out u return_id);
};
[…]
With this information, it’s easy to use the ``call`` command to display a
notification::
$ gdbus call --session \
--dest org.freedesktop.Notifications \
--object-path /org/freedesktop/Notifications \
--method org.freedesktop.Notifications.Notify \
my_app_name \
42 \
gtk-dialog-info \
"The Summary" \
"Here’s the body of the notification" \
[] \
{} \
5000
(uint32 12,)
Call a method with file handle argument::
$ gdbus call --session \
--dest org.example.foo \
--object-path /org/example/foo \
--method SendFDs \
1 \
10 \
10<file.foo
Monitoring all objects on a service::
$ gdbus monitor --system --dest org.freedesktop.ConsoleKit
Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
The name org.freedesktop.ConsoleKit is owned by :1.15
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
Monitoring a single object on a service::
$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
The name org.freedesktop.NetworkManager is owned by :1.5
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5c>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5e>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},)
Emitting a signal::
$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
Emitting a signal to a specific process::
$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
Waiting for a well-known name to be owned on the bus; this will *not* auto-start
the service::
$ gdbus wait --session org.bar.SomeName
Auto-starting then waiting for a well-known name to be owned on the bus::
$ gdbus wait --session --activate org.bar.SomeName
Auto-starting a different service, then waiting for a well-known name to be
owned on the bus. This is useful in situations where ``SomeName`` is not
directly activatable::
$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
Waiting for a well-known name and giving up after 30 seconds. By default, the
timeout is disabled; or set ``--timeout`` to ``0`` to disable it::
$ gdbus wait --session --timeout 30 org.bar.SomeName
BUGS
----
Please send bug reports to either the distribution bug tracker or the
`upstream bug tracker <https://gitlab.gnome.org/GNOME/glib/issues/new>`_.
SEE ALSO
--------
`dbus-send(1) <man:dbus-send(1)>`_

429
docs/reference/gio/gdbus.xml
View File

@ -1,429 +0,0 @@
<refentry id="gdbus" lang="en">
<refentryinfo>
<title>gdbus</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>David</firstname>
<surname>Zeuthen</surname>
<email>zeuthen@gmail.com</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gdbus</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gdbus</refname>
<refpurpose>Tool for working with D-Bus objects</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">introspect</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
<group>
<arg choice="plain">--xml</arg>
</group>
<group>
<arg choice="plain">--recurse</arg>
</group>
<group>
<arg choice="plain">--only-properties</arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">monitor</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<group>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">call</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--dest <replaceable>bus_name</replaceable></arg>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
<arg choice="plain">--method <replaceable>org.project.InterfaceName.MethodName</replaceable></arg>
<group>
<arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
<arg choice="plain">--interactive</arg>
</group>
<arg choice="plain">ARG1</arg>
<arg choice="plain" rep="repeat">ARG2</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">emit</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg>
<arg choice="plain">--signal <replaceable>org.project.InterfaceName.SignalName</replaceable></arg>
<group>
<arg choice="plain">--dest <replaceable>unique_bus_name</replaceable></arg>
</group>
<arg choice="plain">ARG1</arg>
<arg choice="plain" rep="repeat">ARG2</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">wait</arg>
<group>
<arg choice="plain">--system</arg>
<arg choice="plain">--session</arg>
<arg choice="plain">--address <replaceable>address</replaceable></arg>
</group>
<arg choice="plain">--activate <replaceable>bus_name</replaceable></arg>
<group>
<arg choice="plain">--timeout <replaceable>seconds</replaceable></arg>
</group>
<arg choice="plain"><replaceable>bus_name</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gdbus</command>
<arg choice="plain">help</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>gdbus</command> is a simple tool for working with D-Bus objects.
</para>
</refsect1>
<refsect1>
<title>Commands</title>
<variablelist>
<varlistentry>
<term><option>introspect</option></term>
<listitem><para>
Prints out interfaces and property values for a remote object.
For this to work, the owner of the object needs to implement the
<literal>org.freedesktop.DBus.Introspectable</literal> interface.
If the <option>--xml</option> option is used, the returned
introspection XML is printed, otherwise a parsed pretty
representation is printed.
The <option>--recurse</option> option can be used to
introspect children (and their children and so on) and the
<option>--only-properties</option> option can be used to
only print the interfaces with properties.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>monitor</option></term>
<listitem><para>
Monitors one or all objects owned by the owner of
<replaceable>bus_name</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>call</option></term>
<listitem><para>
Invokes a method on a remote object. Each argument to pass to the
method must be specified as a serialized
<link linkend="GVariant"><type>GVariant</type></link> except that strings do
not need explicit quotes. The return values are printed out as
serialized <link linkend="GVariant"><type>GVariant</type></link>
values.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>emit</option></term>
<listitem><para>
Emits a signal. Each argument to include in the signal must be specified as a serialized
<link linkend="GVariant"><type>GVariant</type></link> except that strings do
not need explicit quotes.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>wait</option></term>
<listitem><para>
Waits until <replaceable>bus_name</replaceable> is owned by some
process on the bus. If the <option>--activate</option> is specified,
that bus name will be auto-started first. It may be the same as the
bus name being waited for, or different.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exit.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Bash Completion</title>
<para>
<command>gdbus</command> ships with a bash completion script to
complete commands, destinations, bus names, object paths and
interface/method names.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
This shows how to introspect an object - note that the value of each
property is displayed:
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.NetworkManager \
--object-path /org/freedesktop/NetworkManager/Devices/0
node /org/freedesktop/NetworkManager/Devices/0 {
interface org.freedesktop.DBus.Introspectable {
methods:
Introspect(out s data);
};
interface org.freedesktop.DBus.Properties {
methods:
Get(in s interface,
in s propname,
out v value);
Set(in s interface,
in s propname,
in v value);
GetAll(in s interface,
out a{sv} props);
};
interface org.freedesktop.NetworkManager.Device.Wired {
signals:
PropertiesChanged(a{sv} arg_0);
properties:
readonly b Carrier = false;
readonly u Speed = 0;
readonly s HwAddress = '00:1D:72:88:BE:97';
};
interface org.freedesktop.NetworkManager.Device {
methods:
Disconnect();
signals:
StateChanged(u arg_0,
u arg_1,
u arg_2);
properties:
readonly u DeviceType = 1;
readonly b Managed = true;
readwrite o Ip6Config = '/';
readwrite o Dhcp4Config = '/';
readwrite o Ip4Config = '/';
readonly u State = 2;
readwrite u Ip4Address = 0;
readonly u Capabilities = 3;
readonly s Driver = 'e1000e';
readwrite s Interface = 'eth0';
readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
};
};
</programlisting>
<para>
The <option>--recurse</option> and <option>--only-properties</option> options can be useful when wanting to inspect all objects owned by a particular process:
</para>
<programlisting>
$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse --only-properties
node / {
node /org {
node /org/freedesktop {
node /org/freedesktop/UPower {
interface org.freedesktop.UPower {
properties:
readonly b IsDocked = true;
readonly b LidForceSleep = false;
readonly b LidIsPresent = false;
readonly b LidIsClosed = false;
readonly b OnLowBattery = false;
readonly b OnBattery = false;
readonly b CanHibernate = true;
readonly b CanSuspend = true;
readonly s DaemonVersion = '0.9.10';
};
node /org/freedesktop/UPower/Policy {
};
node /org/freedesktop/UPower/Wakeups {
interface org.freedesktop.UPower.Wakeups {
properties:
readonly b HasCapability = true;
};
};
};
};
};
};
</programlisting>
<para>
In a similar fashion, the <option>introspect</option> command can be
used to learn details about the <literal>Notify</literal> method:
</para>
<programlisting>
[...]
interface org.freedesktop.Notifications {
methods:
GetServerInformation(out s return_name,
out s return_vendor,
out s return_version,
out s return_spec_version);
GetCapabilities(out as return_caps);
CloseNotification(in u id);
Notify(in s app_name,
in u id,
in s icon,
in s summary,
in s body,
in as actions,
in a{sv} hints,
in i timeout,
out u return_id);
};
[...]
</programlisting>
<para>
With this information, it's easy to use the <option>call</option>
command to display a notification
</para>
<programlisting>
$ gdbus call --session \
--dest org.freedesktop.Notifications \
--object-path /org/freedesktop/Notifications \
--method org.freedesktop.Notifications.Notify \
my_app_name \
42 \
gtk-dialog-info \
"The Summary" \
"Here's the body of the notification" \
[] \
{} \
5000
(uint32 12,)
</programlisting>
<para>
Call a method with file handle argument:
</para>
<programlisting>
$ gdbus call --session \
--dest org.example.foo \
--object-path /org/example/foo \
--method SendFDs \
1 \
10 \
10&lt;file.foo
</programlisting>
<para>
Monitoring all objects on a service:
</para>
<programlisting>
$ gdbus monitor --system --dest org.freedesktop.ConsoleKit
Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
The name org.freedesktop.ConsoleKit is owned by :1.15
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
</programlisting>
<para>
Monitoring a single object on a service:
</para>
<programlisting>
$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
The name org.freedesktop.NetworkManager is owned by :1.5
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5c&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x5e&gt;},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': &lt;byte 0x64&gt;},)
</programlisting>
<para>
Emitting a signal:
</para>
<programlisting>
$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
</programlisting>
<para>
Emitting a signal to a specific process:
</para>
<programlisting>
$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
</programlisting>
<para>
Waiting for a well-known name to be owned on the bus; this will
<emphasis>not</emphasis> auto-start the service:
</para>
<programlisting>
$ gdbus wait --session org.bar.SomeName
</programlisting>
<para>
Auto-starting then waiting for a well-known name to be owned on the bus:
</para>
<programlisting>
$ gdbus wait --session --activate org.bar.SomeName
</programlisting>
<para>
Auto-starting a different service, then waiting for a well-known name to be
owned on the bus. This is useful in situations where
<replaceable>SomeName</replaceable> is not directly activatable:
</para>
<programlisting>
$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
</programlisting>
<para>
Waiting for a well-known name and giving up after 30 seconds. By default,
the timeout is disabled; or set <option>--timeout</option> to 0 to disable it:
</para>
<programlisting>
$ gdbus wait --session --timeout 30 org.bar.SomeName
</programlisting>
</refsect1>
<refsect1>
<title>Bugs</title>
<para>
Please send bug reports to either the distribution bug tracker
or the upstream bug tracker at
<ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new"/>.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry>
<refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

3
docs/reference/gio/gio-docs-unix.xml
View File

@ -1,3 +0,0 @@
<chapter id='unix-support'>
<!--FIXME: fill this with unix APIs that cannot build on Windows -->
</chapter>

6
docs/reference/gio/gio-docs-win32.xml
View File

@ -1,6 +0,0 @@
<chapter id='win32-support'>
<title>Win32 support</title>
<xi:include href="xml/gwin32registrykey.xml"/>
<xi:include href="xml/gwin32inputstream.xml"/>
<xi:include href="xml/gwin32outputstream.xml"/>
</chapter>

418
docs/reference/gio/gio-docs.xml
View File

@ -1,418 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<book lang="en" id="gio" xmlns:xi="http://www.w3.org/2003/XInclude">
<title>GIO Reference Manual</title>
<bookinfo>
<title>GIO Reference Manual</title>
<releaseinfo>
for GIO &version;
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="https://developer.gnome.org/gio/unstable/">https://developer.gnome.org/gio/unstable/</ulink>.
</releaseinfo>
</bookinfo>
<xi:include href="xml/overview.xml"/>
<part>
<title>API Reference</title>
<chapter id="file_ops">
<title>File Operations</title>
<xi:include href="xml/gfile.xml"/>
<xi:include href="xml/gfileattribute.xml"/>
<xi:include href="xml/gfileinfo.xml"/>
<xi:include href="xml/gfileenumerator.xml"/>
<xi:include href="xml/gioerror.xml"/>
<xi:include href="xml/gmountoperation.xml"/>
</chapter>
<chapter id="file_mon">
<title>File System Monitoring</title>
<xi:include href="xml/gfilemonitor.xml"/>
</chapter>
<chapter id="utils">
<title>File-related Utilities</title>
<xi:include href="xml/gfilenamecompleter.xml"/>
</chapter>
<chapter id="async">
<title>Asynchronous I/O</title>
<xi:include href="xml/gcancellable.xml"/>
<xi:include href="xml/gasyncresult.xml"/>
<xi:include href="xml/gtask.xml"/>
<xi:include href="xml/gioscheduler.xml"/>
<xi:include href="xml/gsimpleasyncresult.xml"/>
</chapter>
<chapter id="conversion">
<title>Data conversion</title>
<xi:include href="xml/gconverter.xml"/>
<xi:include href="xml/gcharsetconverter.xml"/>
<xi:include href="xml/gzlibcompressor.xml"/>
<xi:include href="xml/gzlibdecompressor.xml"/>
</chapter>
<chapter id="streaming">
<title>Streaming I/O</title>
<xi:include href="xml/gseekable.xml"/>
<xi:include href="xml/ginputstream.xml"/>
<xi:include href="xml/goutputstream.xml"/>
<xi:include href="xml/giostream.xml"/>
<xi:include href="xml/gsimpleiostream.xml"/>
<xi:include href="xml/gfileinputstream.xml"/>
<xi:include href="xml/gfileoutputstream.xml"/>
<xi:include href="xml/gfileiostream.xml"/>
<xi:include href="xml/gfiledescriptorbased.xml"/>
<xi:include href="xml/gfilterinputstream.xml"/>
<xi:include href="xml/gfilteroutputstream.xml"/>
<xi:include href="xml/gmemoryinputstream.xml"/>
<xi:include href="xml/gmemoryoutputstream.xml"/>
<xi:include href="xml/gbufferedinputstream.xml"/>
<xi:include href="xml/gbufferedoutputstream.xml"/>
<xi:include href="xml/gdatainputstream.xml"/>
<xi:include href="xml/gdataoutputstream.xml"/>
<xi:include href="xml/gunixinputstream.xml"/>
<xi:include href="xml/gunixoutputstream.xml"/>
<xi:include href="xml/gconverterinputstream.xml"/>
<xi:include href="xml/gconverteroutputstream.xml"/>
<xi:include href="xml/gpollableinputstream.xml"/>
<xi:include href="xml/gpollableoutputstream.xml"/>
<xi:include href="xml/gpollableutils.xml"/>
</chapter>
<chapter id="types">
<title>File types and applications</title>
<xi:include href="xml/gcontenttype.xml"/>
<xi:include href="xml/gappinfo.xml"/>
<xi:include href="xml/gappinfomonitor.xml"/>
<xi:include href="xml/gdesktopappinfo.xml"/>
</chapter>
<chapter id="volume_mon">
<title>Volumes and Drives</title>
<xi:include href="xml/gvolumemonitor.xml"/>
<xi:include href="xml/gvolume.xml"/>
<xi:include href="xml/gmount.xml"/>
<xi:include href="xml/gdrive.xml"/>
<xi:include href="xml/gunixmounts.xml"/>
</chapter>
<chapter id="icons">
<title>Icons</title>
<xi:include href="xml/gicon.xml"/>
<xi:include href="xml/gfileicon.xml"/>
<xi:include href="xml/gbytesicon.xml"/>
<xi:include href="xml/gloadableicon.xml"/>
<xi:include href="xml/gthemedicon.xml"/>
<xi:include href="xml/gemblemedicon.xml"/>
<xi:include href="xml/gemblem.xml"/>
</chapter>
<chapter id="failable_initialization">
<title>Failable Initialization</title>
<xi:include href="xml/ginitable.xml"/>
<xi:include href="xml/gasyncinitable.xml"/>
</chapter>
<chapter id="subprocesses">
<title>Subprocesses</title>
<xi:include href="xml/gsubprocess.xml"/>
<xi:include href="xml/gsubprocesslauncher.xml"/>
</chapter>
<chapter id="networking">
<title>Low-level network support</title>
<xi:include href="xml/gsocket.xml"/>
<xi:include href="xml/gdatagrambased.xml"/>
<xi:include href="xml/ginetaddress.xml"/>
<xi:include href="xml/ginetaddressmask.xml"/>
<xi:include href="xml/gsocketaddress.xml"/>
<xi:include href="xml/ginetsocketaddress.xml"/>
<xi:include href="xml/gunixsocketaddress.xml"/>
<xi:include href="xml/gnativesocketaddress.xml"/>
<xi:include href="xml/gsocketcontrolmessage.xml"/>
<xi:include href="xml/gunixfdlist.xml"/>
<xi:include href="xml/gunixfdmessage.xml"/>
<xi:include href="xml/gcredentials.xml"/>
<xi:include href="xml/gunixcredentialsmessage.xml"/>
<xi:include href="xml/gproxy.xml"/>
<xi:include href="xml/gproxyaddress.xml"/>
<xi:include href="xml/gnetworking.xml"/>
</chapter>
<chapter id="highlevel-socket">
<title>High-level network functionality</title>
<xi:include href="xml/gsocketclient.xml"/>
<xi:include href="xml/gsocketconnection.xml"/>
<xi:include href="xml/gunixconnection.xml"/>
<xi:include href="xml/gtcpconnection.xml"/>
<xi:include href="xml/gtcpwrapperconnection.xml"/>
<xi:include href="xml/gsocketlistener.xml"/>
<xi:include href="xml/gsocketservice.xml"/>
<xi:include href="xml/gthreadedsocketservice.xml"/>
<xi:include href="xml/gnetworkmonitor.xml"/>
</chapter>
<chapter id="tls">
<title>TLS (SSL) support</title>
<xi:include href="xml/gtls.xml"/>
<xi:include href="xml/gtlscertificate.xml"/>
<xi:include href="xml/gtlsconnection.xml"/>
<xi:include href="xml/gtlsclientconnection.xml"/>
<xi:include href="xml/gtlsserverconnection.xml"/>
<xi:include href="xml/gdtlsconnection.xml"/>
<xi:include href="xml/gdtlsclientconnection.xml"/>
<xi:include href="xml/gdtlsserverconnection.xml"/>
<xi:include href="xml/gtlsbackend.xml"/>
<xi:include href="xml/gtlsdatabase.xml"/>
<xi:include href="xml/gtlsfiledatabase.xml"/>
<xi:include href="xml/gtlsinteraction.xml"/>
<xi:include href="xml/gtlspassword.xml"/>
</chapter>
<chapter id="resolver">
<title>DNS resolution</title>
<xi:include href="xml/gresolver.xml"/>
<xi:include href="xml/gproxyresolver.xml"/>
<xi:include href="xml/gsimpleproxyresolver.xml"/>
<xi:include href="xml/gsocketconnectable.xml"/>
<xi:include href="xml/gsocketaddressenumerator.xml"/>
<xi:include href="xml/gproxyaddressenumerator.xml"/>
<xi:include href="xml/gnetworkaddress.xml"/>
<xi:include href="xml/gnetworkservice.xml"/>
<xi:include href="xml/gsrvtarget.xml"/>
</chapter>
<chapter id="gdbus-lowlevel">
<title>Low-level D-Bus Support</title>
<xi:include href="xml/gdbusutils.xml"/>
<xi:include href="xml/gdbusaddress.xml"/>
<xi:include href="xml/gdbusintrospection.xml"/>
<xi:include href="xml/gdbuserror.xml"/>
<xi:include href="xml/gdbusmessage.xml"/>
<xi:include href="xml/gdbusconnection.xml"/>
<xi:include href="xml/gdbusmethodinvocation.xml"/>
<xi:include href="xml/gdbusserver.xml"/>
<xi:include href="xml/gdbusauthobserver.xml"/>
</chapter>
<chapter id="gdbus-convenience">
<title>High-level D-Bus Support</title>
<xi:include href="xml/gdbusnameowning.xml"/>
<xi:include href="xml/gdbusnamewatching.xml"/>
<xi:include href="xml/gdbusinterface.xml"/>
<xi:include href="xml/gdbusinterfaceskeleton.xml"/>
<xi:include href="xml/gdbusproxy.xml"/>
<xi:include href="xml/gdbusobject.xml"/>
<xi:include href="xml/gdbusobjectskeleton.xml"/>
<xi:include href="xml/gdbusobjectproxy.xml"/>
<xi:include href="xml/gdbusobjectmanager.xml"/>
<xi:include href="xml/gdbusobjectmanagerserver.xml"/>
<xi:include href="xml/gdbusobjectmanagerclient.xml"/>
</chapter>
<chapter id="settings">
<title>Settings</title>
<xi:include href="xml/gsettings.xml"/>
<xi:include href="xml/gsettingsbackend.xml"/>
<xi:include href="xml/gsettingsschema.xml"/>
</chapter>
<chapter id="resources">
<title>Resources</title>
<xi:include href="xml/gresource.xml"/>
</chapter>
<chapter id='permissions'>
<title>Permissions</title>
<xi:include href="xml/gpermission.xml"/>
<xi:include href="xml/gsimplepermission.xml"/>
</chapter>
<chapter id='data-models'>
<title>Data Models</title>
<xi:include href="xml/glistmodel.xml"/>
<xi:include href="xml/gliststore.xml"/>
</chapter>
<chapter id="application">
<title>Application support</title>
<xi:include href="xml/gapplication.xml"/>
<xi:include href="xml/gapplicationcommandline.xml"/>
<xi:include href="xml/gactiongroup.xml"/>
<xi:include href="xml/gactionmap.xml"/>
<xi:include href="xml/gsimpleactiongroup.xml"/>
<xi:include href="xml/gaction.xml"/>
<xi:include href="xml/gsimpleaction.xml"/>
<xi:include href="xml/gpropertyaction.xml"/>
<xi:include href="xml/gremoteactiongroup.xml"/>
<xi:include href="xml/gactiongroupexporter.xml"/>
<xi:include href="xml/gdbusactiongroup.xml"/>
<xi:include href="xml/gdebugcontroller.xml"/>
<xi:include href="xml/gdebugcontrollerdbus.xml"/>
<xi:include href="xml/gmemorymonitor.xml"/>
<xi:include href="xml/gmenumodel.xml"/>
<xi:include href="xml/gmenu.xml"/>
<xi:include href="xml/gmenuexporter.xml"/>
<xi:include href="xml/gdbusmenumodel.xml"/>
<xi:include href="xml/gnotification.xml"/>
<xi:include href="xml/gpowerprofilemonitor.xml"/>
</chapter>
<chapter id="extending">
<title>Extending GIO</title>
<xi:include href="xml/gvfs.xml"/>
<xi:include href="xml/giomodule.xml"/>
<xi:include href="xml/extensionpoints.xml"/>
</chapter>
<chapter id="tools">
<title>GIO Tools</title>
<xi:include href="gio-querymodules.xml"/>
<xi:include href="gsettings.xml"/>
<xi:include href="glib-compile-schemas.xml"/>
<xi:include href="glib-compile-resources.xml"/>
<xi:include href="gdbus.xml"/>
<xi:include href="xml/gdbus-codegen.xml"/>
<xi:include href="gresource.xml"/>
<xi:include href="gapplication.xml"/>
<xi:include href="gio.xml"/>
</chapter>
<chapter id="testing">
<title>GIO Testing</title>
<xi:include href="xml/gtestdbus.xml"/>
</chapter>
<xi:include href="gio-docs-platform.xml"/>
</part>
<part id="migrating">
<title>Migrating to GIO</title>
<xi:include href="xml/migrating-posix.xml"/>
<xi:include href="xml/migrating-gnome-vfs.xml"/>
<xi:include href="xml/migrating-gconf.xml"/>
<xi:include href="xml/migrating-gdbus.xml"/>
</part>
<chapter id="gio-hierarchy">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
<chapter id="api-index-full">
<title id="index-all">Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-deprecated" role="deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-18" role="2.18">
<title>Index of new symbols in 2.18</title>
<xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-20" role="2.20">
<title>Index of new symbols in 2.20</title>
<xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-22" role="2.22">
<title>Index of new symbols in 2.22</title>
<xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-24" role="2.24">
<title>Index of new symbols in 2.24</title>
<xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-26" role="2.26">
<title>Index of new symbols in 2.26</title>
<xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-28" role="2.28">
<title>Index of new symbols in 2.28</title>
<xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-30" role="2.30">
<title>Index of new symbols in 2.30</title>
<xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-32" role="2.32">
<title>Index of new symbols in 2.32</title>
<xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-34" role="2.34">
<title>Index of new symbols in 2.34</title>
<xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-36" role="2.36">
<title>Index of new symbols in 2.36</title>
<xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-38" role="2.38">
<title>Index of new symbols in 2.38</title>
<xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-40" role="2.40">
<title>Index of new symbols in 2.40</title>
<xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-42" role="2.42">
<title>Index of new symbols in 2.42</title>
<xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-44" role="2.44">
<title>Index of new symbols in 2.44</title>
<xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-46" role="2.46">
<title>Index of new symbols in 2.46</title>
<xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-48" role="2.48">
<title>Index of new symbols in 2.48</title>
<xi:include href="xml/api-index-2.48.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-50" role="2.50">
<title>Index of new symbols in 2.50</title>
<xi:include href="xml/api-index-2.50.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-52" role="2.52">
<title>Index of new symbols in 2.52</title>
<xi:include href="xml/api-index-2.52.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-54" role="2.54">
<title>Index of new symbols in 2.54</title>
<xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-56" role="2.56">
<title>Index of new symbols in 2.56</title>
<xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-58" role="2.58">
<title>Index of new symbols in 2.58</title>
<xi:include href="xml/api-index-2.58.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-60" role="2.60">
<title>Index of new symbols in 2.60</title>
<xi:include href="xml/api-index-2.60.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-62" role="2.62">
<title>Index of new symbols in 2.62</title>
<xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-64" role="2.64">
<title>Index of new symbols in 2.64</title>
<xi:include href="xml/api-index-2.64.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-66" role="2.66">
<title>Index of new symbols in 2.66</title>
<xi:include href="xml/api-index-2.66.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-68" role="2.68">
<title>Index of new symbols in 2.68</title>
<xi:include href="xml/api-index-2.68.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-70" role="2.70">
<title>Index of new symbols in 2.70</title>
<xi:include href="xml/api-index-2.70.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-72" role="2.72">
<title>Index of new symbols in 2.72</title>
<xi:include href="xml/api-index-2.72.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-74" role="2.74">
<title>Index of new symbols in 2.74</title>
<xi:include href="xml/api-index-2.74.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-76" role="2.76">
<title>Index of new symbols in 2.76</title>
<xi:include href="xml/api-index-2.76.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-78" role="2.78">
<title>Index of new symbols in 2.78</title>
<xi:include href="xml/api-index-2.78.xml"><xi:fallback /></xi:include>
</chapter>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

31
docs/reference/gio/gio-querymodules.rst Normal file
View File

@ -0,0 +1,31 @@
.. _gio-querymodules(1):
.. meta::
:copyright: Copyright 2010, 2012 Red Hat, Inc.
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2010, 2012 Red Hat, Inc.
SPDX-License-Identifier: LGPL-2.1-or-later
================
gio-querymodules
================
-------------------------
GIO module cache creation
-------------------------
SYNOPSIS
--------
| **gio-querymodules** *DIRECTORY*…
DESCRIPTION
-----------
``gio-querymodules`` creates a ``giomodule.cache`` file in the listed
directories. This file lists the implemented extension points for each module
that has been found. It is used by GIO at runtime to avoid opening all modules
just to find out which extension points they are implementing.
GIO modules are usually installed in the ``gio/modules`` subdirectory of libdir.

45
docs/reference/gio/gio-querymodules.xml
View File

@ -1,45 +0,0 @@
<refentry id="gio-querymodules" lang="en">
<refentryinfo>
<title>glib-compile-schemas</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Alexander</firstname>
<surname>Larsson</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gio-querymodules</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gio-querymodules</refname>
<refpurpose>GIO module cache creation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gio-querymodules</command>
<arg choice="req" rep="repeat">DIRECTORY</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gio-querymodules</command> creates a
<filename>giomodule.cache</filename> file in the listed directories.
This file lists the implemented extension points for each module
that has been found. It is used by GIO at runtime to avoid opening
all modules just to find out which extension points they are implementing.
</para>
<para>
GIO modules are usually installed in the <filename>gio/modules</filename>
subdirectory of libdir.
</para>
</refsect1>
</refentry>

4808
docs/reference/gio/gio-sections-common.txt
View File

File diff suppressed because it is too large Load Diff

122
docs/reference/gio/gio-sections-win32.txt
View File

@ -1,122 +0,0 @@
<SECTION>
<FILE>gwin32inputstream</FILE>
<TITLE>GWin32InputStream</TITLE>
GWin32InputStream
g_win32_input_stream_new
g_win32_input_stream_set_close_handle
g_win32_input_stream_get_close_handle
g_win32_input_stream_get_handle
<SUBSECTION Standard>
GWin32InputStreamClass
G_WIN32_INPUT_STREAM
G_IS_WIN32_INPUT_STREAM
G_TYPE_WIN32_INPUT_STREAM
G_WIN32_INPUT_STREAM_CLASS
G_IS_WIN32_INPUT_STREAM_CLASS
G_WIN32_INPUT_STREAM_GET_CLASS
<SUBSECTION Private>
g_win32_input_stream_get_type
GWin32InputStreamPrivate
</SECTION>
<SECTION>
<FILE>gwin32outputstream</FILE>
<TITLE>GWin32OutputStream</TITLE>
GWin32OutputStream
g_win32_output_stream_new
g_win32_output_stream_set_close_handle
g_win32_output_stream_get_close_handle
g_win32_output_stream_get_handle
<SUBSECTION Standard>
GWin32OutputStreamClass
G_WIN32_OUTPUT_STREAM
G_IS_WIN32_OUTPUT_STREAM
G_TYPE_WIN32_OUTPUT_STREAM
G_WIN32_OUTPUT_STREAM_CLASS
G_IS_WIN32_OUTPUT_STREAM_CLASS
G_WIN32_OUTPUT_STREAM_GET_CLASS
<SUBSECTION Private>
g_win32_output_stream_get_type
GWin32OutputStreamPrivate
</SECTION>
<SECTION>
<FILE>gwin32registrykey</FILE>
<SUBSECTION>
GWin32RegistrySubkeyIter
g_win32_registry_subkey_iter_copy
g_win32_registry_subkey_iter_free
g_win32_registry_subkey_iter_assign
<SUBSECTION>
GWin32RegistryValueIter
g_win32_registry_value_iter_copy
g_win32_registry_value_iter_free
g_win32_registry_value_iter_assign
<SUBSECTION>
GWin32RegistryKey
g_win32_registry_key_new
g_win32_registry_key_new_w
g_win32_registry_key_get_child
g_win32_registry_key_get_child_w
<SUBSECTION>
g_win32_registry_subkey_iter_init
g_win32_registry_subkey_iter_clear
g_win32_registry_subkey_iter_n_subkeys
g_win32_registry_subkey_iter_next
g_win32_registry_subkey_iter_get_name
g_win32_registry_subkey_iter_get_name_w
<SUBSECTION>
g_win32_registry_value_iter_init
g_win32_registry_value_iter_clear
g_win32_registry_value_iter_n_values
g_win32_registry_value_iter_next
GWin32RegistryValueType
g_win32_registry_value_iter_get_value_type
g_win32_registry_value_iter_get_name
g_win32_registry_value_iter_get_name_w
g_win32_registry_value_iter_get_data
g_win32_registry_value_iter_get_data_w
<SUBSECTION>
g_win32_registry_key_get_value
g_win32_registry_key_get_value_w
g_win32_registry_key_get_path
g_win32_registry_key_get_path_w
GWin32RegistryKeyWatchCallbackFunc
GWin32RegistryKeyWatcherFlags
g_win32_registry_key_watch
g_win32_registry_key_has_changed
g_win32_registry_key_erase_change_indicator
<SUBSECTION Standard>
GWin32RegistryKeyClass
<SUBSECTION Private>
GWin32RegistryKeyPrivate
g_win32_registry_key_get_type
g_win32_registry_subkey_iter_get_type
g_win32_registry_value_iter_get_type
G_TYPE_WIN32_REGISTRY_KEY
G_WIN32_REGISTRY_KEY
G_WIN32_REGISTRY_KEY_CLASS
G_IS_WIN32_REGISTRY_KEY
G_IS_WIN32_REGISTRY_KEY_CLASS
G_WIN32_REGISTRY_KEY_GET_CLASS
G_TYPE_WIN32_REGISTRY_SUBKEY_ITER
G_TYPE_WIN32_REGISTRY_VALUE_ITER
</SECTION>
<SECTION>
<FILE>gregistrysettingsbackend</FILE>
<TITLE>GRegistrySettingsBackend</TITLE>
GRegistrySettingsBackend
g_registry_settings_backend_new
<SUBSECTION Private>
g_registry_settings_backend_get_type
</SECTION>

50
docs/reference/gio/gio-unix.toml.in Normal file
View File

@ -0,0 +1,50 @@
# SPDX-License-Identifier: LGPL-2.1-or-later
# Copyright 2023 Matthias Clasen
# Copyright 2023 Philip Withnall
[library]
name = "GioUnix"
version = "@VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/glib/"
repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
website_url = "https://www.gtk.org"
docs_urls = "https://docs.gtk.org/gio-unix/"
authors = "GLib Development Team"
license = "LGPL-2.1-or-later"
description = "Unix-specific APIs in Gio"
dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
devhelp = true
search_index = true
[dependencies."GLib-2.0"]
name = "GLib"
description = "The base utility library"
docs_url = "https://docs.gtk.org/glib/"
[dependencies."GModule-2.0"]
name = "GModule"
description = "Portable API for dynamically loading modules"
docs_url = "https://docs.gtk.org/gmodule/"
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."Gio-2.0"]
name = "Gio"
description = "A library of useful classes for I/O, networking and IPC"
docs_url = "https://docs.gtk.org/gio/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[extra]
urlmap_file = "../urlmap.js"
# The same order will be used when generating the index
content_files = [
"unix-mounts.md",
]
content_images = []

48
docs/reference/gio/gio-win32.toml.in Normal file
View File

@ -0,0 +1,48 @@
# SPDX-License-Identifier: LGPL-2.1-or-later
# Copyright 2023 Matthias Clasen
# Copyright 2023 Philip Withnall
[library]
name = "GioWin32"
version = "@VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/glib/"
repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
website_url = "https://www.gtk.org"
docs_urls = "https://docs.gtk.org/gio-win32/"
authors = "GLib Development Team"
license = "LGPL-2.1-or-later"
description = "Windows-specific APIs in Gio"
dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
devhelp = true
search_index = true
[dependencies."GLib-2.0"]
name = "GLib"
description = "The base utility library"
docs_url = "https://docs.gtk.org/glib/"
[dependencies."GModule-2.0"]
name = "GModule"
description = "Portable API for dynamically loading modules"
docs_url = "https://docs.gtk.org/gmodule/"
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."Gio-2.0"]
name = "Gio"
description = "A library of useful classes for I/O, networking and IPC"
docs_url = "https://docs.gtk.org/gio/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[extra]
urlmap_file = "../urlmap.js"
# The same order will be used when generating the index
content_files = []
content_images = []

528
docs/reference/gio/gio.rst Normal file
View File

@ -0,0 +1,528 @@
.. _gio(1):
.. meta::
:copyright: Copyright 2015, 2019, 2020 Red Hat, Inc.
:copyright: Copyright 2018, 2019 Endless Mobile, Inc.
:copyright: Copyright 2018 segfault
:copyright: Copyright 2020 Frederic Martinsons
:copyright: Copyright 2022 Marco Trevisan
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2015, 2019, 2020 Red Hat, Inc.
SPDX-FileCopyrightText: 2018, 2019 Endless Mobile, Inc.
SPDX-FileCopyrightText: 2018 segfault
SPDX-FileCopyrightText: 2020 Frederic Martinsons
SPDX-FileCopyrightText: 2022 Marco Trevisan
SPDX-License-Identifier: LGPL-2.1-or-later
===
gio
===
--------------------
GIO commandline tool
--------------------
SYNOPSIS
--------
| **gio** help [*COMMAND*]
| **gio** version
| **gio** cat *LOCATION*…
| **gio** copy [*OPTION*…] *SOURCE*… *DESTINATION*
| **gio** info [*OPTION*…] *LOCATION*…
| **gio** launch *DESKTOP-FILE* [*FILE-ARG*…]
| **gio** list [*OPTION*…] [*LOCATION*…]
| **gio** mime *MIME-TYPE* [*HANDLER*]
| **gio** mkdir [*OPTION*…] *LOCATION*…
| **gio** monitor [*OPTION*…] [*LOCATION*…]
| **gio** mount [*OPTION*…] [*LOCATION*…]
| **gio** move [*OPTION*…] *SOURCE*… *DESTINATION*
| **gio** open *LOCATION*…
| **gio** rename *LOCATION* *NAME*
| **gio** remove [*OPTION*…] *LOCATION*…
| **gio** save [*OPTION*…] *DESTINATION*
| **gio** set [*OPTION*…] *LOCATION* *ATTRIBUTE* *VALUE*…
| **gio** trash [*OPTION*…] [*LOCATION*…]
| **gio** tree [*OPTION*…] [*LOCATION*…]
DESCRIPTION
-----------
``gio`` is a utility that makes many of the GIO features available from the
commandline. In doing so, it provides commands that are similar to traditional
utilities, but let you use GIO locations instead of local files: for example you
can use something like ``smb://server/resource/file.txt`` as a location.
Plain filenames which contain a colon will be interpreted as URIs with an
unknown protocol. To avoid this, prefix them with a path such as ``./``, or with
the ``file:`` protocol.
COMMANDS
--------
``help`` *COMMAND*
Displays a short synopsis of the available commands or provides detailed help
on a specific command.
``version``
Prints the GLib version to which ``gio`` belongs.
``cat`` *LOCATION*…
Concatenates the given files and prints them to the standard output.
The ``cat`` command works just like the traditional ``cat`` utility.
Mote: just pipe through ``cat`` if you need its formatting options like
``-n``, ``-T`` or other.
``copy`` [*OPTION*…] *SOURCE*… *DESTINATION*
Copies one or more files from ``SOURCE`` to ``DESTINATION``. If more than one
source is specified, the destination must be a directory.
The ``copy`` command is similar to the traditional ``cp`` utility.
**Options**
``-T``, ``--no-target-directory``
Don’t copy into ``DESTINATION`` even if it is a directory.
``-p``, ``--progress``
Show progress.
``-i``, ``--interactive``
Prompt for confirmation before overwriting files.
``--preserve``
Preserve all attributes of copied files.
``-b``, ``--backup``
Create backups of existing destination files.
``-P``, ``--no-dereference``
Never follow symbolic links.
``--default-permissions``
Use the default permissions of the current process for the destination file,
rather than copying the permissions of the source file.
``info`` [*OPTION*…] *LOCATION*…
Shows information about the given locations.
The ``info`` command is similar to the traditional ``ls`` utility.
**Options**
``-w``, ``--query-writable``
List writable attributes.
``-f``, ``--filesystem``
Show information about the filesystem that the given locations reside on.
``-a``, ``--attributes=<ATTRIBUTES>``
The attributes to get.
Attributes can be specified with their GIO name, e.g. ``standard::icon``,
or just by namespace, e.g. ``unix``, or by ``*``, which matches all
attributes. Several attributes or groups of attributes can be specified,
separated by commas.
By default, all attributes are listed.
``-n``, ``--nofollow-symlinks``
Don’t follow symbolic links.
``launch`` *DESKTOP-FILE* [*FILE-ARG*…]
Launch a desktop file from any location given.
The ``launch`` command extends the behavior of the ``open`` command by
allowing any desktop file to be launched, not only those registered as file
handlers.
``list`` [*OPTION*…] [*LOCATION*…]
Lists the contents of the given locations. If no location is given, the
contents of the current directory are shown.
The ``list`` command is similar to the traditional ``ls`` utility.
**Options**
``-a``, ``--attributes=<ATTRIBUTES>``
The attributes to get.
Attributes can be specified with their GIO name, e.g. ``standard::icon``, or
just by namespace, e.g. ``unix``, or by ``*``, which matches all attributes.
Several attributes or groups of attributes can be specified, separated by
commas.
By default, all attributes are listed.
``-h``, ``--hidden``
Show hidden files.
``-l``, ``--long``
Use a long listing format.
``-n``, ``--nofollow-symlinks``
Don’t follow symbolic links.
``-d``, ``--print-display-names``
Print display names.
``-u``, ``--print-uris``
Print full URIs.
``mime`` *MIME-TYPE* [*HANDLER*]
If no handler is given, the ``mime`` command lists the registered and
recommended applications for the MIME type. If a handler is given, it is set
as the default handler for the MIME type.
Handlers must be specified by their desktop file name, including the
extension. Example: ``org.gnome.gedit.desktop``.
``mkdir`` [*OPTION*…] *LOCATION*…
Creates directories.
The ``mkdir`` command is similar to the traditional ``mkdir`` utility.
**Options**
``-p``, ``--parent``
Create parent directories when necessary.
``monitor`` [*OPTION*…] [*LOCATION*…]
Monitors files or directories for changes, such as creation deletion, content
and attribute changes, and mount and unmount operations affecting the
monitored locations.
The ``monitor`` command uses the GIO file monitoring APIs to do its job. GIO
has different implementations for different platforms. The most common
implementation on Linux uses inotify.
**Options**
``-d``, ``--dir=<LOCATION>``
Monitor the given location as a directory. Normally, the file type is used
to determine whether to monitor as a file or as a directory.
``-f``, ``--file=<LOCATION>``
Monitor the given location as a file. Normally, the file type is used to
determine whether to monitor as a file or as a directory.
``-D``, ``--direct=<LOCATION>``
Monitor the file directly. This allows changes made via hardlinks to be
captured.
``-s``, ``--silent=<LOCATION>``
Monitor the file directly, but don’t report changes.
``-n``, ``--no-moves``
Report moves and renames as simple deleted/created events.
``-m``, ``--mounts``
Watch for mount events.
``mount`` [*OPTION*…] [*LOCATION*…]
Provides commandline access to various aspects of GIO’s mounting
functionality.
Mounting refers to the traditional concept of arranging multiple file systems
and devices in a single tree, rooted at ``/``. Classical mounting happens in
the kernel and is controlled by the mount utility. GIO expands this concept by
introducing mount daemons that can make file systems available to GIO
applications without kernel involvement.
GIO mounts can require authentication, and the ``mount`` command may ask for
user IDs, passwords, and so on, when required.
**Options**
``-m``, ``--mountable``
Mount as mountable.
``-d``, ``--device=<ID>``
Mount volume with device file, or other identifier.
``-u``, ``--unmount``
Unmount the location.
``-e``, ``--eject``
Eject the location.
``-t``, ``--stop=<DEVICE>``
Stop drive with device file.
``-s``, ``--unmount-scheme=<SCHEME>``
Unmount all mounts with the given scheme.
``-f``, ``--force``
Ignore outstanding file operations when unmounting or ejecting.
``-a``, ``--anonymous``
Use an anonymous user when authenticating.
``-l``, ``--list``
List all GIO mounts.
``-o``, ``--monitor``
Monitor mount-related events.
``-i``, ``--detail``
Show extra information.
``--tcrypt-pim``
The numeric PIM when unlocking a VeraCrypt volume.
``--tcrypt-hidden``
Mount a TCRYPT hidden volume.
``--tcrypt-system``
Mount a TCRYPT system volume.
``move`` [*OPTION*…] *SOURCE*… *DESTINATION*
Moves one or more files from ``SOURCE`` to ``DESTINATION``. If more than one
source is specified, the destination must be a directory.
The ``move`` command is similar to the traditional ``mv`` utility.
**Options**
``-T``, ``--no-target-directory``
Don’t copy into ``DESTINATION`` even if it is a directory.
``-p``, ``--progress``
Show progress.
``-i``, ``--interactive``
Prompt for confirmation before overwriting files.
``-b``, ``--backup``
Create backups of existing destination files.
``-C``, ``--no-copy-fallback``
Don’t use copy and delete fallback.
``open`` *LOCATION*…
Opens files with the default application that is registered to handle files of
this type.
GIO obtains this information from the shared-mime-info database, with per-user
overrides stored in ``$XDG_DATA_HOME/applications/mimeapps.list``.
The ``mime`` command can be used to change the default handler for a MIME
type.
Environment variables will not be set on the application, as it may be an
existing process which is activated to handle the new file.
``rename`` *LOCATION* *NAME*
Renames a file.
The ``rename`` command is similar to the traditional ``rename`` utility.
``remove`` [*OPTION*…] *LOCATION*…
Deletes each given file.
This command removes files irreversibly. If you want a reversible way to
remove files, see the ``trash`` command.
Note that not all URI schemes that are supported by GIO may allow deletion of
files.
The ``remove`` command is similar to the traditional ``rm`` utility.
**Options**
``-f``, ``--force``
Ignore non-existent and non-deletable files.
``save`` [*OPTION*…] *DESTINATION*
Reads from standard input and saves the data to the given location.
This is similar to just redirecting output to a file using traditional shell
syntax, but the ``save`` command allows saving to location that GIO can write
to.
**Options**
``-b``, ``--backup``
Back up existing destination files.
``-c``, ``--create``
Only create the destination if it doesn’t exist yet.
``-a``, ``--append``
Append to the end of the file.
``-p``, ``--private``
When creating, restrict access to the current user.
``-u``, ``--unlink``
When replacing, replace as if the destination did not exist.
``-v``, ``--print-etag``
Print the new ETag in the end.
``-e``, ``--etag=<ETAG>``
The ETag of the file that is overwritten.
``set`` [*OPTION*…] *LOCATION* *ATTRIBUTE* *VALUE*…
Sets a file attribute on a file.
File attributes can be specified with their GIO name, e.g ``standard::icon``.
Note that not all GIO file attributes are writable. Use the
``--query-writable`` option of the ``info`` command to list writable file
attributes.
If the ``TYPE`` is unset, ``VALUE`` does not have to be specified. If the
``TYPE`` is ``stringv``, multiple values can be given.
**Options**
``-t``, ``--type=<TYPE>``
Specifies the type of the attribute. Supported types are ``string``,
``stringv``, ``bytestring``, ``boolean``, ``uint32``, ``int32``, ``uint64``,
``int64`` and ``unset``.
If the type is not specified, ``string`` is assumed.
``-d``, ``--delete``
Unsets an attribute (same as setting its type to ``unset``).
``-n``, ``--nofollow-symlinks``
Don’t follow symbolic links.
``trash`` [*OPTION*…] [*LOCATION*…]
Sends files or directories to the ‘Trashcan’ or restore them from ‘Trashcan’.
This can be a different folder depending on where the file is located, and not
all file systems support this concept. In the common case that the file lives
inside a user’s home directory, the trash folder is ``$XDG_DATA_HOME/Trash``.
Note that moving files to the trash does not free up space on the file system
until the ‘Trashcan’ is emptied. If you are interested in deleting a file
irreversibly, see the ``remove`` command.
Inspecting and emptying the ‘Trashcan’ is normally supported by graphical file
managers such as Nautilus, but you can also see the trash with the command:
``gio trash --list`` or ``gio list trash://``.
**Options**
``-f``, ``--force``
Ignore non-existent and non-deletable files.
``--empty``
Empty the trash.
``--list``
List files in the trash with their original locations.
``--restore``
Restore a file from trash to its original location. A URI beginning with
``trash://`` is expected here. If the original directory doesn’t exist, it
will be recreated.
``tree`` [*OPTION*…] [*LOCATION*…]
Lists the contents of the given locations recursively, in a tree-like format.
If no location is given, it defaults to the current directory.
The ``tree`` command is similar to the traditional ``tree`` utility.
**Options**
``-h``, ``--hidden``
Show hidden files.
``-l``, ``--follow-symlinks``
Follow symbolic links.
EXIT STATUS
-----------
On success, ``0`` is returned, a non-zero failure code otherwise.
SEE ALSO
--------
`cat(1) <man:cat(1)>`_, `cp(1) <man:cp(1)>`_, `ls(1) <man:ls(1)>`_,
`mkdir(1) <man:mkdir(1)>`_, `mv(1) <man:mv(1)>`_, `rm(1) <man:rm(1)>`_,
`tree(1) <man:tree(1)>`_

71
docs/reference/gio/gio.toml.in Normal file
View File

@ -0,0 +1,71 @@
# SPDX-License-Identifier: LGPL-2.1-or-later
# Copyright 2023 Matthias Clasen
# Copyright 2023 Philip Withnall
[library]
name = "Gio"
version = "@VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/glib/"
repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
website_url = "https://www.gtk.org"
docs_urls = "https://docs.gtk.org/gio/"
authors = "GLib Development Team"
license = "LGPL-2.1-or-later"
description = "Gio is a library providing useful classes for general purpose I/O, networking, IPC, settings, and other high level application functionality"
dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0" ]
devhelp = true
search_index = true
[dependencies."GLib-2.0"]
name = "GLib"
description = "The base utility library"
docs_url = "https://docs.gtk.org/glib/"
[dependencies."GModule-2.0"]
name = "GModule"
description = "Portable API for dynamically loading modules"
docs_url = "https://docs.gtk.org/gmodule/"
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[extra]
urlmap_file = "../urlmap.js"
# The same order will be used when generating the index
content_files = [
"overview.md",
"file-attributes.md",
"tls-overview.md",
"error.md",
"pollable-utils.md",
"dbus-error.md",
"dbus-introspection.md",
"dbus-name-owning.md",
"dbus-name-watching.md",
"dbus-utils.md",
"menu-exporter.md",
"networking.md",
"migrating-gdbus.md",
"migrating-gconf.md",
"migrating-gnome-vfs.md",
"migrating-posix.md",
"io-scheduler.md",
]
content_images = [
"gvfs-overview.png",
"menu-example.png",
"menu-model.png",
]

809
docs/reference/gio/gio.xml
View File

@ -1,809 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<refentry id="gio">
<refentryinfo>
<title>gio</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
<email>mclasen@redhat.com</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gio</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gio</refname>
<refpurpose>GIO commandline tool</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">version</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">cat</arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">copy</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">info</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">launch</arg>
<arg choice="plain"><replaceable>DESKTOP-FILE</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>FILE-ARG</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">list</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">mime</arg>
<arg choice="plain"><replaceable>MIMETYPE</replaceable></arg>
<arg choice="opt"><replaceable>HANDLER</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">mkdir</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">monitor</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">mount</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">move</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">open</arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">rename</arg>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>NAME</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">remove</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">save</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">set</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>ATTRIBUTE</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>VALUE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">trash</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gio</command>
<arg choice="plain">tree</arg>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>gio</command> is a utility that makes many of the GIO
features available from the commandline. In doing so, it provides
commands that are similar to traditional utilities, but let you
use GIO locations instead of local files: for example you can use
something like <filename>smb://server/resource/file.txt</filename>
as a location.</para>
<para>Plain filenames which contain a colon will be interpreted as URIs
with an unknown protocol. To avoid this, prefix them with a path such as
<filename>./</filename>, or with the <literal>file:</literal> protocol.</para>
</refsect1>
<refsect1>
<title>Commands</title>
<variablelist>
<varlistentry>
<term>
<command>help</command>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</term>
<listitem>
<para>Displays a short synopsis of the available commands or provides
detailed help on a specific command.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>version</command>
</term>
<listitem>
<para>Prints the GLib version to which <command>gio</command>
belongs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>cat</command>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Concatenates the given files and prints them to the standard
output.</para>
<para>The <command>cat</command> command works just like the traditional <command>cat</command> utility.</para>
<para>Note: just pipe through <command>cat</command> if you need its formatting options
like <option>-n</option>, <option>-T</option> or other.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>copy</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</term>
<listitem>
<para>Copies one or more files from <replaceable>SOURCE</replaceable>
to <replaceable>DESTINATION</replaceable>. If more than one source
is specified, the destination must be a directory.</para>
<para>The <command>copy</command> command is similar to the traditional <command>cp</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-T</option>, <option>--no-target-directory</option></term>
<listitem><para>Don’t copy into <replaceable>DESTINATION</replaceable> even if it is a directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option>, <option>--progress</option></term>
<listitem><para>Show progress.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option>, <option>--interactive</option></term>
<listitem><para>Prompt for confirmation before overwriting files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--preserve</option></term>
<listitem><para>Preserve all attributes of copied files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-b</option>, <option>--backup</option></term>
<listitem><para>Create backups of existing destination files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-P</option>, <option>--no-dereference</option></term>
<listitem><para>Never follow symbolic links.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--default-permissions</option></term>
<listitem><para>Use the default permissions of the current process for the destination file, rather than copying the permissions of the source file.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>info</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Shows information about the given locations.</para>
<para>The <command>info</command> command is similar to the traditional <command>ls</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-w</option>, <option>--query-writable</option></term>
<listitem><para>List writable attributes.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--filesystem</option></term>
<listitem><para>Show information about the filesystem that the given
locations reside on.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option> <option>--attributes=<replaceable>ATTRIBUTES</replaceable></option></term>
<listitem><para>The attributes to get.</para>
<para>Attributes can be specified with their GIO name, e.g.
<literal>standard::icon</literal>, or just by namespace, e.g. <literal>unix</literal>, or by <literal>*</literal>,
which matches all attributes. Several attributes or groups
of attributes can be specified, separated by comma.</para>
<para>By default, all attributes are listed.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--nofollow-symlinks</option></term>
<listitem><para>Don’t follow symbolic links.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>launch</command>
<arg choice="plain"><replaceable>DESKTOP-FILE</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>FILE-ARG</replaceable></arg>
</term>
<listitem>
<para>Launch a desktop file from any location given.</para>
<para>The <command>launch</command> command extends the behavior of the <command>open</command> command by allowing
any desktop file to be launched, not only those registered as file handlers.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>list</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Lists the contents of the given locations. If no location is
given, the contents of the current directory are shown.</para>
<para>The <command>list</command> command is similar to the traditional <command>ls</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-a</option> <option>--attributes=<replaceable>ATTRIBUTES</replaceable></option></term>
<listitem><para>The attributes to get.</para>
<para>Attributes can be specified with their GIO name, e.g.
<literal>standard::icon</literal>, or just by namespace, e.g. <literal>unix</literal>, or by <literal>*</literal>,
which matches all attributes. Several attributes or groups
of attributes can be specified, separated by comma.</para>
<para>By default, all attributes are listed.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-h</option>, <option>--hidden</option></term>
<listitem><para>Show hidden files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--long</option></term>
<listitem><para>Use a long listing format.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--nofollow-symlinks</option></term>
<listitem><para>Don’t follow symbolic links.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>, <option>--print-display-names</option></term>
<listitem><para>Print display names.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option>, <option>--print-uris</option></term>
<listitem><para>Print full URIs.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>mime</command>
<arg choice="plain"><replaceable>MIMETYPE</replaceable></arg>
<arg choice="opt"><replaceable>HANDLER</replaceable></arg>
</term>
<listitem>
<para>If no handler is given, the <command>mime</command> command lists the
registered and recommended applications for the mimetype.
If a handler is given, it is set as the default handler for
the mimetype.</para>
<para>Handlers must be specified by their desktop file name,
including the extension. Example: <literal>org.gnome.gedit.desktop</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>mkdir</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Creates directories.</para>
<para>The <command>mkdir</command> command is similar to the traditional <command>mkdir</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-p</option>, <option>--parent</option></term>
<listitem><para>Create parent directories when necessary.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>monitor</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Monitors files or directories for changes, such as creation
deletion, content and attribute changes, and mount and unmount
operations affecting the monitored locations.</para>
<para>The <command>monitor</command> command uses the GIO file monitoring APIs to do
its job. GIO has different implementations for different platforms.
The most common implementation on Linux uses inotify.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-d</option>, <option>--dir=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the given location as a directory. Normally,
the file type is used to determine whether to monitor a file or directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--file=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the given location as a file. Normally,
the file type is used to determine whether to monitor a file or directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-D</option>, <option>--direct=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the file directly. This allows changes made via hardlinks to be captured.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--silent=<replaceable>LOCATION</replaceable></option></term>
<listitem><para>Monitor the file directly, but don’t report changes.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--no-moves</option></term>
<listitem><para>Report moves and renames as simple deleted/created events.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-m</option>, <option>--mounts</option></term>
<listitem><para>Watch for mount events.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>mount</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Provides commandline access to various aspects of GIO’s mounting
functionality.</para>
<para>Mounting refers to the traditional concept of arranging multiple
file systems and devices in a single tree, rooted at <filename>/</filename>. Classical
mounting happens in the kernel and is controlled by the mount utility.
GIO expands this concept by introducing mount daemons that can make
file systems available to GIO applications without kernel
involvement.</para>
<para>GIO mounts can require authentication, and the <command>mount</command> command
may ask for user IDs, passwords, and so on, when required.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-m</option>, <option>--mountable</option></term>
<listitem><para>Mount as mountable.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>, <option>--device=<replaceable>ID</replaceable></option></term>
<listitem><para>Mount volume with device file, or other identifier.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option>, <option>--unmount</option></term>
<listitem><para>Unmount the location.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option>, <option>--eject</option></term>
<listitem><para>Eject the location.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option>, <option>--stop=<replaceable>DEVICE</replaceable></option></term>
<listitem><para>Stop drive with device file.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--unmount-scheme=<replaceable>SCHEME</replaceable></option></term>
<listitem><para>Unmount all mounts with the given scheme.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>Ignore outstanding file operations when unmounting or ejecting.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option>, <option>--anonymous</option></term>
<listitem><para>Use an anonymous user when authenticating.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--list</option></term>
<listitem><para>List all GIO mounts.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-o</option>, <option>--monitor</option></term>
<listitem><para>Monitor mount-related events.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option>, <option>--detail</option></term>
<listitem><para>Show extra information.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tcrypt-pim</option></term>
<listitem><para>The numeric PIM when unlocking a VeraCrypt volume.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tcrypt-hidden</option></term>
<listitem><para>Mount a TCRYPT hidden volume.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tcrypt-system</option></term>
<listitem><para>Mount a TCRYPT system volume.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>move</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>SOURCE</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</term>
<listitem>
<para>Moves one or more files from <replaceable>SOURCE</replaceable>
to <replaceable>DESTINATION</replaceable>. If more than one source
is specified, the destination must be a directory.</para>
<para>The <command>move</command> command is similar to the traditional <command>mv</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-T</option>, <option>--no-target-directory</option></term>
<listitem><para>Don’t copy into <replaceable>DESTINATION</replaceable> even if it is a directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option>, <option>--progress</option></term>
<listitem><para>Show progress.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-i</option>, <option>--interactive</option></term>
<listitem><para>Prompt for confirmation before overwriting files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-b</option>, <option>--backup</option></term>
<listitem><para>Create backups of existing destination files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-C</option>, <option>--no-copy-fallback</option></term>
<listitem><para>Don’t use copy and delete fallback.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>open</command>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Opens files with the default application that is registered
to handle files of this type.</para>
<para>GIO obtains this information from the shared-mime-info
database, with per-user overrides stored in
<filename><envar>$XDG_DATA_HOME</envar>/applications/mimeapps.list</filename>.</para>
<para>The <command>mime</command> command can be used to change the default handler for
a mimetype.</para>
<para>Environment variables will not be set on the application, as it
may be an existing process which is activated to handle the new file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>rename</command>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>NAME</replaceable></arg>
</term>
<listitem>
<para>Renames a file.</para>
<para>The <command>rename</command> command is similar to the traditional <command>rename</command> utility.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>remove</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Deletes each given file.</para>
<para>This command removes files irreversibly. If you want a reversible
way to remove files, see the <command>trash</command> command.</para>
<para>Note that not all URI schemes that are supported by GIO may
allow deletion of files.</para>
<para>The <command>remove</command> command is similar to the traditional <command>rm</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>Ignore non-existent and non-deletable files.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>save</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="plain"><replaceable>DESTINATION</replaceable></arg>
</term>
<listitem>
<para>Reads from standard input and saves the data to the given
location.</para>
<para>This is similar to just redirecting output to a file using
traditional shell syntax, but the <command>save</command> command allows saving to
location that GIO can write to.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-b</option>, <option>--backup</option></term>
<listitem><para>Back up existing destination files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-c</option>, <option>--create</option></term>
<listitem><para>Only create the destination if it doesn’t exist yet.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-a</option>, <option>--append</option></term>
<listitem><para>Append to the end of the file.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p</option>, <option>--private</option></term>
<listitem><para>When creating, restrict access to the current user.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-u</option>, <option>--unlink</option></term>
<listitem><para>When replacing, replace as if the destination did not exist.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--print-etag</option></term>
<listitem><para>Print the new ETag in the end.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-e</option>, <option>--etag=<replaceable>ETAG</replaceable></option></term>
<listitem><para>The ETag of the file that is overwritten.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>set</command>
<arg choice="plain"><replaceable>LOCATION</replaceable></arg>
<arg choice="plain"><replaceable>ATTRIBUTE</replaceable></arg>
<arg choice="plain" rep="repeat"><replaceable>VALUE</replaceable></arg>
</term>
<listitem>
<para>Sets a file attribute on a file.</para>
<para>File attributes can be specified with their GIO name, e.g
<literal>standard::icon</literal>. Note that not all GIO file attributes are writable.
Use the <option>--query-writable</option> option of the <command>info</command> command to list
writable file attributes.</para>
<para>If the <replaceable>TYPE</replaceable> is unset,
<replaceable>VALUE</replaceable> does not have to be specified.
If the <replaceable>TYPE</replaceable> is <literal>stringv</literal>, multiple values can be given.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-t</option>, <option>--type=<replaceable>TYPE</replaceable></option></term>
<listitem><para>Specifies the type of the attribute. Supported
types are <literal>string</literal>, <literal>stringv</literal>,
<literal>bytestring</literal>, <literal>boolean</literal>,
<literal>uint32</literal>, <literal>int32</literal>,
<literal>uint64</literal>, <literal>int64</literal> and <literal>unset</literal>.</para>
<para>If the type is not specified, <literal>string</literal> is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d</option>, <option>--delete</option></term>
<listitem><para>Unsets an attribute (same as setting it's type to <literal>unset</literal>).</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option>, <option>--nofollow-symlinks</option></term>
<listitem><para>Don’t follow symbolic links.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>trash</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Sends files or directories to the ‘Trashcan’ or restore them from
‘Trashcan’. This can be a different folder depending on where the file
is located, and not all file systems support this concept. In the common
case that the file lives inside a user’s home directory, the trash folder is
<filename><envar>$XDG_DATA_HOME</envar>/Trash</filename>.</para>
<para>Note that moving files to the trash does not free up space on
the file system until the ‘Trashcan’ is emptied. If you are interested
in deleting a file irreversibly, see the <command>remove</command> command.</para>
<para>Inspecting and emptying the ‘Trashcan’ is normally supported by
graphical file managers such as Nautilus, but you can also see the
trash with the command: <command>gio trash --list</command> or
<command>gio list trash://</command>.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>Ignore non-existent and non-deletable files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--empty</option></term>
<listitem><para>Empty the trash.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--list</option></term>
<listitem><para>List files in the trash with their original locations</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--restore</option></term>
<listitem><para>Restore a file from trash to its original location. A URI beginning
with <literal>trash://</literal> is expected here. If the original
directory doesn't exist, it will be recreated.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>tree</command>
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>LOCATION</replaceable></arg>
</term>
<listitem>
<para>Lists the contents of the given locations recursively, in a
tree-like format. If no location is given, it defaults to the current
directory.</para>
<para>The <command>tree</command> command is similar to the traditional <command>tree</command> utility.</para>
<refsect3>
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--hidden</option></term>
<listitem><para>Show hidden files.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option>, <option>--follow-symlinks</option></term>
<listitem><para>Follow symbolic links.</para></listitem>
</varlistentry>
</variablelist>
</refsect3>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Exit status</title>
<para>On success 0 is returned, a non-zero failure code otherwise.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry>
<refentrytitle>cat</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>cp</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>ls</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>mkdir</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>mv</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>rm</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>tree</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>

181
docs/reference/gio/glib-compile-resources.rst Normal file
View File

@ -0,0 +1,181 @@
.. _glib-compile-resources(1):
.. meta::
:copyright: Copyright 2012, 2016 Red Hat, Inc.
:copyright: Copyright 2012 Christian Persch
:copyright: Copyright 2016 Sam Thursfield
:copyright: Copyright 2016 Patrick Griffis
:copyright: Copyright 2018 Ninja-Koala
:copyright: Copyright 2018, 2021 Emmanuele Bassi
:copyright: Copyright 2020 Endless OS Foundation, LLC
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2012, 2016 Red Hat, Inc.
SPDX-FileCopyrightText: 2012 Christian Persch
SPDX-FileCopyrightText: 2016 Sam Thursfield
SPDX-FileCopyrightText: 2016 Patrick Griffis
SPDX-FileCopyrightText: 2018 Ninja-Koala
SPDX-FileCopyrightText: 2018, 2021 Emmanuele Bassi
SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC
SPDX-License-Identifier: LGPL-2.1-or-later
======================
glib-compile-resources
======================
----------------------
GLib resource compiler
----------------------
SYNOPSIS
--------
| **glib-compile-resources** [*OPTION*…] *FILE*
DESCRIPTION
-----------
``glib-compile-resources`` reads the resource description from ``FILE`` and the
files that it references and creates a binary resource bundle that is suitable
for use with the ``GResource`` API. The resulting bundle is then written out
as-is, or as C source for linking into an application.
The XML resource files normally have the filename extension ``.gresource.xml``.
For a detailed description of the XML file format, see the
``GResource`` `documentation <https://docs.gtk.org/gio/struct.Resource.html>`_.
OPTIONS
-------
``-h``, ``--help``
Print help and exit.
``--version``
Print program version and exit.
``--target <TARGET>``
Store the compiled resources in the file ``TARGET``. If not specified a
filename based on the ``FILE`` basename is used.
``--sourcedir <DIRECTORY>``
The files referenced in ``FILE`` are loaded from this directory. If not
specified, the current directory is used.
``--generate``
Write the output file in the format selected for by its filename extension:
``.c``
C source
``.h``
C header
``.gresource``
resource bundle
``--generate-source``
Instead of a writing the resource bundle in binary form, create a C source
file that contains the resource bundle. This can then be compiled into an
application for easy access.
``--generate-header``
Generate a header file for use with C code generated by ``--generate-source``.
``--generate-dependencies``
Prints the list of files that the resource bundle references to standard
output. This can be used to track dependencies in the build system. For
example, the following make rule would mark ``test.gresource`` as depending on
all the files that ``test.gresource.xml`` includes, so that it is
automatically rebuilt if any of them change::
test.gresource: test.gresource.xml $(shell $(GLIB_COMPILE_RESOURCES) --generate-dependencies test.gresource.xml)
Note that this may or may not be portable to non-GNU ``make``.
Also see ``--dependency-file``.
``--c-name``
Specify the prefix used for the C identifiers in the code generated by
``--generate-source`` and ``--generate-header``.
``--manual-register``
By default, code generated by ``--generate-source`` uses automatic
initialization of the resource. This works on most systems by using the
compiler support for constructors. However, some (uncommon) compilers may not
support this, you can then specify ``--manual-register``,
which will generate custom register and unregister functions that your code
can manually call at initialization and uninitialization time.
``--internal``
By default, code generated by ``--generate-source`` declares all
initialization functions as ``extern``. So they are exported unless this is
prevented by a link script or other means. Since libraries usually want to
use the functions only internally it can be more useful to declare them as
``G_GNUC_INTERNAL`` which is what ``--internal`` does.
``--external-data``
By default, code generated by ``--generate-source`` embeds the resource data
as a string literal. When ``--external-data`` is given, the data is only
declared in the generated C file, and the data has to be linked externally.
``--dependency-file <FILE>``
Write dependencies in the same style as ``gcc -M -MF`` to the given file. If
``FILE`` is ``-``, the dependencies are written to the standard output. Unlike
``--generate-dependencies``, this option can be combined with other
``--generate`` options to generate dependencies as a side-effect of generating
sources.
``--generate-phony-targets``
When creating a dependency file with ``--dependency-file`` include phony
targets in the same style as ``gcc -MP``. This would typically be used with
``make``.
``--compiler <NAME>``
Generate code that is going to target the given compiler ``NAME``. The current
two compiler modes are ``gcc``, for all GCC-compatible toolchains; and
``msvc``, for the Microsoft Visual C Compiler. If this option isn’t set, then
the default will be taken from the ``CC`` environment variable.
ENVIRONMENT
-----------
``XMLLINT``
The full path to the ``xmllint`` executable. This is used to preprocess
resources with the ``xml-stripblanks`` preprocessing option. If this
environment variable is not set, ``xmllint`` is searched for in the ``PATH``.
``GDK_PIXBUF_PIXDATA``
Deprecated since gdk-pixbuf 2.32, as ``GResource`` supports embedding
modern image formats without conversion.
The full path to the ``gdk-pixbuf-pixdata`` executable. This is used to
preprocess resources with the ``to-pixdata`` preprocessing option. If this
environment variable is not set, ``gdk-pixbuf-pixdata`` is searched for in the
``PATH``.
``JSON_GLIB_FORMAT``
The full path to the ``json-glib-format`` executable. This is used to
preprocess resources with the ``json-stripblanks`` preprocessing option. If
this environment variable is not set, ``json-glib-format`` is searched for in
the ``PATH``.

254
docs/reference/gio/glib-compile-resources.xml
View File

@ -1,254 +0,0 @@
<refentry id="glib-compile-resources" lang="en">
<refentryinfo>
<title>glib-compile-schemas</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Alexander</firstname>
<surname>Larsson</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-compile-resources</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-compile-resources</refname>
<refpurpose>GLib resource compiler</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-compile-resources</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="req">FILE</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-compile-resources</command> reads the resource description from
<replaceable>FILE</replaceable> and the files that it references
and creates a binary resource bundle that is suitable for use with the
<link linkend="GResource"><type>GResource</type></link> API.
The resulting bundle is then written out as-is, or as C source for linking into
an application.
</para>
<para>
The XML resource files normally have the filename extension <filename>.gresource.xml</filename>.
For a detailed description of the XML file format, see the
<link linkend="GResource"><type>GResource</type></link> documentation.
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
Print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
Print program version and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--target=<replaceable>TARGET</replaceable></option></term>
<listitem><para>
Store the compiled resources in the file <replaceable>TARGET</replaceable>.
If not specified a filename based on the <replaceable>FILE</replaceable>
basename is used.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--sourcedir=<replaceable>DIRECTORY</replaceable></option></term>
<listitem><para>
The files referenced in <replaceable>FILE</replaceable> are loaded from
this directory. If not specified, the current directory is used.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate</option></term>
<listitem><para>
Write the output file in the format selected for by its filename extension:
<variablelist>
<varlistentry>
<term><literal>.c</literal></term>
<listitem><para>C source</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>.h</literal></term>
<listitem><para>C header</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>.gresource</literal></term>
<listitem><para>resource bundle</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-source</option></term>
<listitem><para>
Instead of a writing the resource bundle in binary form create a C source file
that contains the resource bundle. This can then be compiled into an
application for easy access.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-header</option></term>
<listitem><para>
Generate a header file for use with C code generated by
<option>--generate-source</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-dependencies</option></term>
<listitem><para>
Prints the list of files that the resource bundle references to standard output.
This can be used to track dependencies in the build system. For example, the
following make rule would mark <replaceable>test.gresource</replaceable> as
depending on all the files that <replaceable>test.gresource.xml</replaceable>
includes, so that is is automatically rebuilt if any of them change:
<programlisting>
test.gresource: test.gresource.xml $(shell $(GLIB_COMPILE_RESOURCES) --generate-dependencies test.gresource.xml)
</programlisting>
Note that this may or may not be portable to non-GNU <command>make</command>.
</para>
<para>
Also see <option>--dependency-file</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--c-name</option></term>
<listitem><para>
Specify the prefix used for the C identifiers in the code generated by
<option>--generate-source</option> and <option>--generate-header</option>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--manual-register</option></term>
<listitem><para>
By default code generated by <option>--generate-source</option> uses automatic
initialization of the resource. This works on most systems by using the
compiler support for constructors. However, some (uncommon) compilers may not
support this, you can then specify <option>--manual-register</option>,
which will generate custom register and unregister functions that your code
can manually call at initialization and uninitialization time.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--internal</option></term>
<listitem><para>
By default code generated by <option>--generate-source</option> declares all
initialization functions as <type>extern</type>. So they are exported
unless this is prevented by a link script or other means. Since libraries
usually want to use the functions only internally it can be more useful to
declare them as
<link linkend="G-GNUC-INTERNAL:CAPS"><literal>G_GNUC_INTERNAL</literal></link>
which is what <option>--internal</option> does.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--external-data</option></term>
<listitem><para>
By default code generated by <option>--generate-source</option> embeds the
resource data as a string literal. When <option>--external-data</option>
is given, the data is only declared in the generated C file, and the data
has to be linked externally.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--dependency-file=<replaceable>FILE</replaceable></option></term>
<listitem><para>
Write dependencies in the same style as gcc -M -MF to the given file.
If <option>FILE</option> is -, the dependencies are written to the standard
output. Unlike <option>--generate-dependencies</option>, this option can be
combined with other <option>--generate</option> options to generate dependencies
as a side-effect of generating sources.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--generate-phony-targets</option></term>
<listitem><para>
When creating a dependency file with <option>--dependency-file</option>
include phony targets in the same style as gcc -MP. This would typically
be used with <literal>make</literal>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--compiler=<replaceable>NAME</replaceable></option></term>
<listitem><para>
Generate code that is going to target the given compiler <replaceable>NAME</replaceable>.
The current two compiler modes are "gcc", for all GCC-compatible toolchains; and "msvc",
for the Microsoft Visual C Compiler. If this option isn't set, then the default will be
taken from the <envar>CC</envar> environment variable.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Environment</title>
<variablelist>
<varlistentry>
<term><envar>XMLLINT</envar></term>
<listitem><para>
The full path to the <command>xmllint</command> executable. This is used to
preprocess resources with the <literal>xml-stripblanks</literal> preprocessing
option. If this environment variable is not set, <command>xmllint</command> is
searched for in the <envar>PATH</envar>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><envar>GDK_PIXBUF_PIXDATA</envar></term>
<listitem><para>
Deprecated since gdk-pixbuf 2.32, as <type>GResource</type> supports embedding
modern image formats without conversion.
</para><para>
The full path to the <command>gdk-pixbuf-pixdata</command> executable. This is
used to preprocess resources with the <literal>to-pixdata</literal> preprocessing
option. If this environment variable is not set, <command>gdk-pixbuf-pixdata</command>
is searched for in the <envar>PATH</envar>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><envar>JSON_GLIB_FORMAT</envar></term>
<listitem><para>
The full path to the <command>json-glib-format</command> executable. This is used
to preprocess resources with the <literal>json-stripblanks</literal> preprocessing
option. If this environment variable is not set, <command>json-glib-format</command>
is searched for in the <envar>PATH</envar>.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

83
docs/reference/gio/glib-compile-schemas.rst Normal file
View File

@ -0,0 +1,83 @@
.. _glib-compile-schemas(1):
.. meta::
:copyright: Copyright 2010, 2011, 2012, 2015 Red Hat, Inc.
:copyright: Copyright 2012 Allison Karlitskaya
:copyright: Copyright 2016 Sam Thursfield
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2010, 2011, 2012, 2015 Red Hat, Inc.
SPDX-FileCopyrightText: 2012 Allison Karlitskaya
SPDX-FileCopyrightText: 2016 Sam Thursfield
SPDX-License-Identifier: LGPL-2.1-or-later
====================
glib-compile-schemas
====================
-------------------------
GSettings schema compiler
-------------------------
SYNOPSIS
--------
| **glib-compile-schemas** [*OPTION*…] *DIRECTORY*
DESCRIPTION
-----------
``glib-compile-schemas`` compiles all the GSettings XML schema files in
``DIRECTORY`` into a binary file with the name ``gschemas.compiled`` that can be
used by ``GSettings``. The XML schema files must have the filename extension
``.gschema.xml``. For a detailed description of the XML file format, see the
``GSettings`` documentation.
At runtime, GSettings looks for schemas in the ``glib-2.0/schemas``
subdirectories of all directories specified in the ``XDG_DATA_DIRS`` environment
variable. The usual location to install schema files is
``/usr/share/glib-2.0/schemas``.
In addition to schema files, ``glib-compile-schemas`` reads ‘vendor override’
files, which are key files that can override default values for keys in
the schemas. The group names in the key files are the schema ID, and the
values are written in serialized GVariant form.
Vendor override files must have the filename extension
``.gschema.override``.
By convention, vendor override files begin with ``nn_`` where ``nn`` is a number
from 00 to 99. Higher numbered files have higher priority (e.g. if the same
override is made in a file numbered 10 and then again in a file numbered 20, the
override from 20 will take precedence).
OPTIONS
-------
``-h``, ``--help``
Print help and exit.
``--version``
Print program version and exit.
``--targetdir <TARGET>``
Store ``gschemas.compiled`` in the ``TARGET`` directory instead of
``DIRECTORY``.
``--strict``
Abort on any errors in schemas. Without this option, faulty schema files are
simply omitted from the resulting compiled schema.
``--dry-run``
Don’t write ``gschemas.compiled``. This option can be used to check
``.gschema.xml`` sources for errors.
``--allow-any-name``
Do not enforce restrictions on key names. Note that this option is purely
to facility the transition from GConf, and will be removed at some time
in the future.

118
docs/reference/gio/glib-compile-schemas.xml
View File

@ -1,118 +0,0 @@
<refentry id="glib-compile-schemas" lang="en">
<refentryinfo>
<title>glib-compile-schemas</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Ryan</firstname>
<surname>Lortie</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-compile-schemas</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-compile-schemas</refname>
<refpurpose>GSettings schema compiler</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-compile-schemas</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="req">DIRECTORY</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-compile-schemas</command> compiles all the GSettings XML
schema files in <replaceable>DIRECTORY</replaceable> into a binary file
with the name <filename>gschemas.compiled</filename> that can be used
by <link linkend="GSettings"><type>GSettings</type></link>. The XML schema
files must have the filename extension <filename>.gschema.xml</filename>.
For a detailed description of the XML file format, see the
<link linkend="GSettings"><type>GSettings</type></link> documentation.
</para>
<para>
At runtime, GSettings looks for schemas in the
<filename>glib-2.0/schemas</filename> subdirectories of all directories
specified in the <envar>XDG_DATA_DIRS</envar> environment variable. The
usual location to install schema files is
<filename>/usr/share/glib-2.0/schemas</filename>.
</para>
<para>
In addition to schema files, glib-compile-schemas reads 'vendor override'
files, which are key files that can override default values for keys in
the schemas. The group names in the key files are the schema id, and the
values are written in serialized GVariant form.
Vendor override files must have the filename extension
<filename>.gschema.override</filename>.
</para>
<para>
By convention, vendor override files begin with <filename>nn_</filename>
where <filename>nn</filename> is a number from 00 to 99. Higher
numbered files have higher priority (eg: if the same override is made in
a file numbered 10 and then again in a file numbered 20, the override
from 20 will take precedence).
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
Print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
Print program version and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--targetdir=<replaceable>TARGET</replaceable></option></term>
<listitem><para>
Store <filename>gschemas.compiled</filename> in the <replaceable>TARGET</replaceable> directory instead of <replaceable>DIRECTORY</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--strict</option></term>
<listitem><para>
Abort on any errors in schemas. Without this option, faulty schema files are
simply omitted from the resulting compiled schema.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--dry-run</option></term>
<listitem><para>
Don't write <filename>gschemas.compiled</filename>. This option can be used
to check <filename>.gschema.xml</filename> sources for errors.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--allow-any-name</option></term>
<listitem><para>
Do not enforce restrictions on key names. Note that this option is purely
to facility the transition from GConf, and will be removed at some time
in the future.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

66
docs/reference/gio/gresource.rst Normal file
View File

@ -0,0 +1,66 @@
.. _gresource(1):
.. meta::
:copyright: Copyright 2012 Red Hat, Inc.
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2012 Red Hat, Inc.
SPDX-License-Identifier: LGPL-2.1-or-later
=========
gresource
=========
--------------
GResource tool
--------------
SYNOPSIS
--------
| **gresource** [--section *SECTION*] list *FILE* [*PATH*]
| **gresource** [--section *SECTION*] details *FILE* [*PATH*]
| **gresource** [--section *SECTION*] extract *FILE* *PATH*
| **gresource** sections *FILE*
| **gresource** help [*COMMAND*]
DESCRIPTION
-----------
``gresource`` offers a simple commandline interface to ``GResource``. It lets
you list and extract resources that have been compiled into a resource file or
included in an ELF file (a binary or a shared library).
The file to operate on is specified by the ``FILE`` argument.
If an ELF file includes multiple sections with resources, it is possible to
select which one to operate on with the ``--section`` option. Use the
``sections`` command to find available sections.
COMMANDS
--------
``list``
Lists resources. If ``SECTION`` is given, only list resources in this section.
If ``PATH`` is given, only list matching resources.
``details``
Lists resources with details. If ``SECTION`` is given, only list resources in
this section. If ``PATH`` is given, only list matching resources. Details
include the section, size and compression of each resource.
``extract``
Extracts the resource named by ``PATH`` to stdout. Note that resources may
contain binary data.
``sections``
Lists sections containing resources. This is only interesting if ``FILE`` is
an ELF file.
``help``
Prints help and exits.

127
docs/reference/gio/gresource.xml
View File

@ -1,127 +0,0 @@
<refentry id="gresource-tool" lang="en">
<refentryinfo>
<title>gresource</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Matthias</firstname>
<surname>Clasen</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gresource</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gresource</refname>
<refpurpose>GResource tool</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gresource</command>
<arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
<arg choice="plain">list</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
<arg choice="opt"><replaceable>PATH</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
<arg choice="plain">details</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
<arg choice="opt"><replaceable>PATH</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="opt">--section <replaceable>SECTION</replaceable></arg>
<arg choice="plain">extract</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
<arg choice="plain"><replaceable>PATH</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="plain">sections</arg>
<arg choice="plain"><replaceable>FILE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gresource</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gresource</command> offers a simple commandline
interface to <link linkend="GResource"><type>GResource</type></link>.
It lets you list and extract resources that have been compiled
into a resource file or included in an elf file (a binary or a
shared library).
</para>
<para>
The file to operate on is specified by the <replaceable>FILE</replaceable>
argument.
</para>
<para>
If an elf file includes multiple sections with resources, it is
possible to select which one to operate on with the
<arg choice="plain">--section</arg> option. Use the
<arg choice="plain">sections</arg> command to find available sections.
</para>
</refsect1>
<refsect1><title>Commands</title>
<variablelist>
<varlistentry>
<term><option>list</option></term>
<listitem><para>
Lists resources. If <replaceable>SECTION</replaceable> is given, only
list resources in this section. If <replaceable>PATH</replaceable> is
given, only list matching resources.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>details</option></term>
<listitem><para>
Lists resources with details. If <replaceable>SECTION</replaceable>
is given, only list resources in this section. If
<replaceable>PATH</replaceable> is given, only list matching resources.
Details include the section, size and compression of each resource.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>extract</option></term>
<listitem><para>
Extracts the resource named by <replaceable>PATH</replaceable> to stdout.
Note that resources may contain binary data.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>sections</option></term>
<listitem><para>
Lists sections containing resources. This is only interesting if
<replaceable>FILE</replaceable> is an elf file.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exits.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

125
docs/reference/gio/gsettings.rst Normal file
View File

@ -0,0 +1,125 @@
.. _gsettings(1):
.. meta::
:copyright: Copyright 2010, 2011, 2013 Red Hat, Inc.
:copyright: Copyright 2011 Colin Walters
:copyright: Copyright 2016 Jeremy Whiting
:copyright: Copyright 2018 Arnaud Bonatti
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2010, 2011, 2013 Red Hat, Inc.
SPDX-FileCopyrightText: 2011 Colin Walters
SPDX-FileCopyrightText: 2016 Jeremy Whiting
SPDX-FileCopyrightText: 2018 Arnaud Bonatti
SPDX-License-Identifier: LGPL-2.1-or-later
=========
gsettings
=========
----------------------------
GSettings configuration tool
----------------------------
SYNOPSIS
--------
| **gsettings** get *SCHEMA*[:*PATH*] *KEY*
| **gsettings** monitor *SCHEMA*[:*PATH*] *KEY*
| **gsettings** writable *SCHEMA*[:*PATH*] *KEY*
| **gsettings** range *SCHEMA*[:*PATH*] *KEY*
| **gsettings** describe *SCHEMA*[:*PATH*] *KEY*
| **gsettings** set *SCHEMA*[:*PATH*] *KEY* *VALUE*
| **gsettings** reset *SCHEMA*[:*PATH*] *KEY*
| **gsettings** reset-recursively *SCHEMA*[:*PATH*]
| **gsettings** list-schemas [--print-paths]
| **gsettings** list-relocatable-schemas
| **gsettings** list-keys *SCHEMA*[:*PATH*]
| **gsettings** list-children *SCHEMA*[:*PATH*]
| **gsettings** list-recursively [*SCHEMA*[:*PATH*]]
| **gsettings** help [*COMMAND*]
DESCRIPTION
-----------
``gsettings`` offers a simple commandline interface to ``GSettings``. It lets
you get, set or monitor an individual key for changes.
The ``SCHEMA`` and ``KEY`` arguments are required for most commands to specify
the schema ID and the name of the key to operate on. The schema ID may
optionally have a ``:PATH`` suffix. Specifying the path is only needed if the
schema does not have a fixed path.
When setting a key, you also need specify a ``VALUE``. The format for the value
is that of a serialized ``GVariant``, so e.g. a string must include explicit
quotes: ``'foo'``. This format is also used when printing out values.
Note that ``gsettings`` needs a D-Bus session bus connection to write changes to
the dconf database.
COMMANDS
--------
``get``
Gets the value of ``KEY``. The value is printed out as a serialized
``GVariant``.
``monitor``
Monitors ``KEY`` for changes and prints the changed values. If no ``KEY`` is
specified, all keys in the schema are monitored. Monitoring will continue
until the process is terminated.
``writable``
Finds out whether ``KEY`` is writable.
``range``
Queries the range of valid values for ``KEY``.
``describe``
Queries the description of valid values for ``KEY``.
``set``
Sets the value of ``KEY`` to ``VALUE``. The value is specified as a serialized
``GVariant``.
``reset``
Resets ``KEY`` to its default value.
``reset-recursively``
Reset all keys under the given ``SCHEMA``.
``list-schemas``
Lists the installed, non-relocatable schemas. See ``list-relocatable-schemas``
if you are interested in relocatable schemas. If ``--print-paths`` is given,
the path where each schema is mapped is also printed.
``list-relocatable-schemas``
Lists the installed, relocatable schemas. See ``list-schemas`` if you are
interested in non-relocatable schemas.
``list-keys``
Lists the keys in ``SCHEMA``.
``list-children``
Lists the children of ``SCHEMA``.
``list-recursively``
Lists keys and values, recursively. If no ``SCHEMA`` is given, list keys in
all schemas.
``help``
Prints help and exits.

248
docs/reference/gio/gsettings.xml
View File

@ -1,248 +0,0 @@
<refentry id="gsettings-tool" lang="en">
<refentryinfo>
<title>gsettings</title>
<productname>GIO</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Ryan</firstname>
<surname>Lortie</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gsettings</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gsettings</refname>
<refpurpose>GSettings configuration tool</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">get</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">monitor</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="opt"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">writable</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">range</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">describe</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">set</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
<arg choice="plain"><replaceable>VALUE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">reset</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
<arg choice="plain"><replaceable>KEY</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">reset-recursively</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-schemas</arg>
<arg choice="opt">--print-paths</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-relocatable-schemas</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-keys</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-children</arg>
<arg choice="plain"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">list-recursively</arg>
<arg choice="opt"><replaceable>SCHEMA</replaceable><arg choice="opt">:<replaceable>PATH</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>gsettings</command>
<arg choice="plain">help</arg>
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gsettings</command> offers a simple commandline
interface to <link linkend="GSettings"><type>GSettings</type></link>.
It lets you get, set or monitor an individual key for changes.
</para>
<para>
The <replaceable>SCHEMA</replaceable> and <replaceable>KEY</replaceable>
arguments are required for most commands to specify the schema id and the
name of the key to operate on. The schema id may optionally have a
:<replaceable>PATH</replaceable> suffix. Specifying the path is only needed
if the schema does not have a fixed path.
</para>
<para>
When setting a key, you also need specify a <replaceable>VALUE</replaceable>
The format for the value is that of a serialized
<link linkend="GVariant"><type>GVariant</type></link>,
so e.g. a string
must include explicit quotes: "'foo'". This format is also used when printing
out values.
</para>
<para>
Note that gsettings needs a D-Bus session bus connection to write changes to
the dconf database.
</para>
</refsect1>
<refsect1><title>Commands</title>
<variablelist>
<varlistentry>
<term><option>get</option></term>
<listitem><para>
Gets the value of <replaceable>KEY</replaceable>.
The value is printed out as a serialized
<link linkend="GVariant"><type>GVariant</type></link>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>monitor</option></term>
<listitem><para>
Monitors <replaceable>KEY</replaceable> for changes and prints the changed
values. If no <replaceable>KEY</replaceable> is specified, all keys in the
schema are monitored. Monitoring will continue until the process is terminated.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>writable</option></term>
<listitem><para>
Finds out whether <replaceable>KEY</replaceable> is writable.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>range</option></term>
<listitem><para>
Queries the range of valid values for <replaceable>KEY</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>describe</option></term>
<listitem><para>
Queries the description of valid values for <replaceable>KEY</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>set</option></term>
<listitem><para>
Sets the value of <replaceable>KEY</replaceable> to
<replaceable>VALUE</replaceable>. The value is specified as a serialized
<link linkend="GVariant"><type>GVariant</type></link>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>reset</option></term>
<listitem><para>
Resets <replaceable>KEY</replaceable> to its default value.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>reset-recursively</option></term>
<listitem><para>
Reset all keys under the given <replaceable>SCHEMA</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-schemas</option></term>
<listitem><para>
Lists the installed, non-relocatable schemas.
See <option>list-relocatable-schemas</option> if you are interested in
relocatable schemas. If <optional><option>--print-paths</option></optional>
is given, the path where each schema is mapped is also printed.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-relocatable-schemas</option></term>
<listitem><para>
Lists the installed, relocatable schemas.
See <option>list-schemas</option> if you are interested in
non-relocatable schemas.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-keys</option></term>
<listitem><para>
Lists the keys in <replaceable>SCHEMA</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-children</option></term>
<listitem><para>
Lists the children of <replaceable>SCHEMA</replaceable>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>list-recursively</option></term>
<listitem><para>
Lists keys and values, recursively. If no <replaceable>SCHEMA</replaceable>
is given, list keys in all schemas.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>help</option></term>
<listitem><para>
Prints help and exits.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>

20
docs/reference/gio/io-scheduler.md Normal file
View File

@ -0,0 +1,20 @@
Title: GIOScheduler
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007 Andrew Walton
# GIOScheduler
Schedules asynchronous I/O operations. `GIOScheduler` integrates
into the main event loop ([struct@GLib.MainLoop]) and uses threads.
Deprecated: 2.36: As of GLib 2.36, `GIOScheduler` is deprecated in favor of
[struct@GLib.ThreadPool] and [class@Gio.Task].
The `GIOScheduler` API is:
* [type@Gio.IOSchedulerJobFunc]
* [func@Gio.io_scheduler_push_job]
* [func@Gio.io_scheduler_cancel_all_jobs]
* [type@Gio.IOSchedulerJob]
* [method@Gio.IOSchedulerJob.send_to_mainloop]
* [method@Gio.IOSchedulerJob.send_to_mainloop_async]

15
docs/reference/gio/menu-exporter.md Normal file
View File

@ -0,0 +1,15 @@
Title: GMenuModel Exporter
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2011 Matthias Clasen
# GMenuModel Exporter
These functions support exporting a [class@Gio.MenuModel] on D-Bus. The D-Bus
interface that is used is a private implementation detail.
* [method@Gio.DBusConnection.export_menu_model]
* [method@Gio.DBusConnection.unexport_menu_model]
To access an exported [class@Gio.MenuModel] remotely, use
[func@Gio.DBusMenuModel.get] to obtain a [class@Gio.DBusMenuModel].

329
docs/reference/gio/meson.build
View File

@ -1,236 +1,111 @@
if get_option('gtk_doc')
subdir('gdbus-object-manager-example')
subdir('xml')
ignore_headers = [
'gdbus-2.0',
'inotify',
'kqueue',
'libasyncns',
'tests',
'win32',
'xdgmime',
'gappinfoprivate.h',
'gapplicationimpl.h',
'gasynchelper.h',
'gcontenttypeprivate.h',
'gcontextspecificgroup.h',
'gcredentialsprivate.h',
'gdbus-daemon-generated.h',
'gdbusactiongroup-private.h',
'gdbusauth.h',
'gdbusauthmechanismanon.h',
'gdbusauthmechanismexternal.h',
'gdbusauthmechanism.h',
'gdbusauthmechanismsha1.h',
'gdbusdaemon.h',
'gdbusprivate.h',
'gdelayedsettingsbackend.h',
'gdocumentportal.h',
'gdummyfile.h',
'gdummyproxyresolver.h',
'gdummytlsbackend.h',
'gfileattribute-priv.h',
'gfileinfo-priv.h',
'ghttpproxy.h',
'giomodule-priv.h',
'gioprivate.h',
'giowin32-afunix.h',
'giowin32-priv.h',
'gio_probes.h',
'gio_trace.h',
'gio-tool.h',
'glocaldirectorymonitor.h',
'glocalfileenumerator.h',
'glocalfile.h',
'glocalfileinfo.h',
'glocalfileinputstream.h',
'glocalfileiostream.h',
'glocalfilemonitor.h',
'glocalfileoutputstream.h',
'glocalvfs.h',
'gmemorymonitordbus.h',
'gmemorymonitorportal.h',
'gmountprivate.h',
'gnativevolumemonitor.h',
'gnetworkingprivate.h',
'gnetworkmonitorbase.h',
'gnetworkmonitornetlink.h',
'gnetworkmonitornm.h',
'gnetworkmonitorportal.h',
'gnotificationbackend.h',
'gnotification-private.h',
'gopenuriportal.h',
'gpollfilemonitor.h',
'gportalsupport.h',
'gpowerprofilemonitordbus.h',
'gpowerprofilemonitorportal.h',
'gproxyresolverportal.h',
'gregistrysettingsbackend.h',
'gresourcefile.h',
'gsandbox.h',
'gsettingsbackendinternal.h',
'gsettings-mapping.h',
'gsettingsschema-internal.h',
'gsocketinputstream.h',
'gsocketoutputstream.h',
'gsocks4aproxy.h',
'gsocks4proxy.h',
'gsocks5proxy.h',
'gsubprocesslauncher-private.h',
'gthreadedresolver.h',
'gtrashportal.h',
'gunionvolumemonitor.h',
'gunixmount.h',
'gunixresolver.h',
'gunixvolume.h',
'gunixvolumemonitor.h',
'gwin32networkmonitor.h',
'gwin32api-application-activation-manager.h',
'gwin32api-iterator.h',
'gwin32api-misc.h',
'gwin32api-package.h',
'gwin32api-storage.h',
'gwin32appinfo.h',
'gwin32file-sync-stream.h',
'gwin32mount.h',
'gwin32packageparser.h',
'gwin32resolver.h',
'gwin32volumemonitor.h',
'thumbnail-verify.h',
'xdp-dbus.h',
'gio-visibility.h',
]
sections_files = files('gio-sections-common.txt')
if host_system == 'windows'
ignore_headers += [
'gfiledescriptorbased.h',
'gunixmounts.h',
'gunixfdmessage.h',
'gunixinputstream.h',
'gunixoutputstream.h',
'gdesktopappinfo.h',
'gosxappinfo.h',
]
sections_files += files('gio-sections-win32.txt')
platform_file = files('gio-docs-win32.xml')
else
if glib_have_cocoa
ignore_headers += ['gdesktopappinfo.h']
else
ignore_headers += ['gosxappinfo.h']
endif
ignore_headers += [
'gwin32inputstream.h',
'gwin32outputstream.h',
'gwin32registrykey.h',
]
platform_file = files('gio-docs-unix.xml')
endif
ignore_sources = [
'kqueue',
'tests',
'gdbus-daemon-generated.c',
'xdp-dbus.c',
]
docpath = join_paths(glib_datadir, 'gtk-doc', 'html')
version_conf = configuration_data()
version_conf.set('VERSION', meson.project_version())
configure_file(
input: 'version.xml.in',
output: 'version.xml',
configuration: version_conf
)
concat_files_helper = find_program('concat-files-helper.py')
configure_file(
output : 'gio-sections.txt',
input : sections_files,
command : [concat_files_helper, '@OUTPUT@', '@INPUT@'],
)
configure_file(
output : 'gio-docs-platform.xml',
input : platform_file,
copy : true,
)
content_files = [
'overview.xml',
'migrating-posix.xml',
'migrating-gnome-vfs.xml',
'migrating-gconf.xml',
'migrating-gdbus.xml',
'gio-querymodules.xml',
'glib-compile-schemas.xml',
'glib-compile-resources.xml',
'gapplication.xml',
'gsettings.xml',
'gresource.xml',
'gdbus.xml',
'gdbus-codegen.xml',
]
content_files += [
gdbus_example_objectmanager_xml,
gdbus_example_objectmanager_sources,
gdbus_object_manager_example_doc
]
gnome.gtkdoc('gio',
main_xml : 'gio-docs.xml',
namespace : 'g',
mode : 'none',
dependencies : [libgio_dep, libgobject_dep, libglib_dep],
src_dir : 'gio',
scan_args : [
'--ignore-decorators=' + ignore_decorators.replace('GLIB', 'GIO'),
'--rebuild-types',
'--ignore-headers=' + ' '.join(ignore_headers),
],
mkdb_args : [
'--ignore-files=' + ' '.join(ignore_sources),
],
content_files : content_files,
expand_content_files : [
'overview.xml',
'migrating-posix.xml',
'migrating-gnome-vfs.xml',
'migrating-gconf.xml',
'migrating-gdbus.xml',
'gdbus-codegen.xml',
],
html_assets : [
'gvfs-overview.png',
'menu-example.png',
'menu-model.png',
],
fixxref_args: [
'--html-dir=' + docpath,
'--extra-dir=' + join_paths('gio', '..', 'glib', 'html'),
'--extra-dir=' + join_paths('gio', '..', 'gobject', 'html'),
],
install: true,
check: true,
)
endif
if get_option('man')
if get_option('man-pages').enabled()
manpages = ['gapplication', 'gio-querymodules', 'glib-compile-schemas',
'glib-compile-resources', 'gsettings', 'gresource', 'gdbus',
'gio', 'gdbus-codegen']
foreach page : manpages
custom_target(page + '-man',
input: page + '.xml',
input: page + '.rst',
output: page + '.1',
command: xsltproc_command,
command: [
rst2man,
rst2man_flags,
'@INPUT@',
],
capture: true,
install: true,
install_dir: man1_dir)
install_dir: man1_dir,
install_tag: 'doc',
)
endforeach
endif
if get_option('documentation') and enable_gir
expand_content_files = [
'dbus-error.md',
'dbus-introspection.md',
'dbus-name-owning.md',
'dbus-name-watching.md',
'dbus-utils.md',
'error.md',
'file-attributes.md',
'io-scheduler.md',
'menu-exporter.md',
'migrating-gconf.md',
'migrating-gdbus.md',
'migrating-gnome-vfs.md',
'migrating-posix.md',
'networking.md',
'overview.md',
'pollable-utils.md',
'tls-overview.md',
]
expand_content_unix_files = [
'unix-mounts.md',
]
expand_content_win32_files = []
gio_toml = configure_file(input: 'gio.toml.in', output: 'gio.toml', configuration: toml_conf)
custom_target('gio-docs',
input: [ gio_toml, gio_gir[0] ],
output: 'gio',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
build_by_default: true,
depend_files: expand_content_files,
install: true,
install_dir: docs_dir,
install_tag: 'doc',
)
if host_system == 'windows'
gio_win32_toml = configure_file(input: 'gio-win32.toml.in', output: 'gio-win32.toml', configuration: toml_conf)
custom_target('gio-win32-docs',
input: [ gio_win32_toml, gio_win32_gir[0] ],
output: 'gio-win32',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
build_by_default: true,
depend_files: expand_content_win32_files,
install: true,
install_dir: docs_dir,
install_tag: 'doc',
)
else
gio_unix_toml = configure_file(input: 'gio-unix.toml.in', output: 'gio-unix.toml', configuration: toml_conf)
custom_target('gio-unix-docs',
input: [ gio_unix_toml, gio_unix_gir[0] ],
output: 'gio-unix',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
build_by_default: true,
depend_files: expand_content_unix_files,
install: true,
install_dir: docs_dir,
install_tag: 'doc',
)
endif
endif

466
docs/reference/gio/migrating-gconf.md Normal file
View File

@ -0,0 +1,466 @@
Title: Migrating from GConf to GSettings
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010, 2012 Matthias Clasen
SPDX-FileCopyrightText: 2010 Allison Lortie
SPDX-FileCopyrightText: 2011 Ray Strode
# Migrating from GConf to GSettings
## Before you start
Converting individual applications and their settings from GConf to
GSettings can be done at will. But desktop-wide settings like font or theme
settings often have consumers in multiple modules. Therefore, some
consideration has to go into making sure that all users of a setting are
converted to GSettings at the same time or that the program responsible for
configuring that setting continues to update the value in both places.
It is always a good idea to have a look at how others have handled similar
problems before.
## Conceptual differences
Conceptually, GConf and GSettings are fairly similar. Both have a concept of
pluggable backends. Both keep information about keys and their types in
schemas. Both have a concept of mandatory values, which lets you implement
lock-down.
There are some differences in the approach to schemas. GConf installs the
schemas into the database and has API to handle schema information
(`gconf_client_get_default_from_schema()`, `gconf_value_get_schema()`, etc).
GSettings on the other hand assumes that an application knows its own
schemas, and does not provide API to handle schema information at runtime.
GSettings is also more strict about requiring a schema whenever you want to
read or write a key. To deal with more free-form information that would
appear in schema-less entries in GConf, GSettings allows for schemas to be
'relocatable'.
One difference in the way applications interact with their settings is that
with GConf you interact with a tree of settings (ie the keys you pass to
functions when reading or writing values are actually paths with the actual
name of the key as the last element. With GSettings, you create a GSettings
object which has an implicit prefix that determines where the settings get
stored in the global tree of settings, but the keys you pass when reading or
writing values are just the key names, not the full path.
## GConfClient (and GConfBridge) API conversion
Most people use GConf via the high-level `GConfClient` API. The
corresponding API is the [class@Gio.Settings] object. While not every
`GConfClient` function has a direct GSettings equivalent, many do:
| GConfClient | GSettings |
|-------------|-----------|
| `gconf_client_get_default()` | no direct equivalent, instead you call [`ctor@Gio.Settings.new`] for the schemas you use |
| `gconf_client_set()` | [`method@Gio.Settings.set`] |
| `gconf_client_get()` | `g_settings_get()` |
| `gconf_client_get_bool()` | `g_settings_get_boolean()` |
| `gconf_client_set_bool()` | `g_settings_set_boolean()` |
| `gconf_client_get_int()` | `g_settings_get_int()` |
| `gconf_client_set_int()` | `g_settings_set_int()` |
| `gconf_client_get_float()` | `g_settings_get_double()` |
| `gconf_client_set_float()` | `g_settings_set_double()` |
| `gconf_client_get_string()` | `g_settings_get_string()` |
| `gconf_client_set_string()` | `g_settings_set_string()` |
| `gconf_client_get_list()` | for string lists, see `g_settings_get_strv()`, else see `g_settings_get_value()` and GVariant API |
| `gconf_client_set_list()` | for string lists, see `g_settings_set_strv()`, else see `g_settings_set_value()` and GVariant API |
| `gconf_entry_get_is_writable()` | `g_settings_is_writable()` |
| `gconf_client_notify_add()` | not required, the “changed” signal is emitted automatically |
| `gconf_client_add_dir()` | not required, each GSettings instance automatically watches all keys in its path |
| `GConfChangeSet` | `g_settings_delay()`, `g_settings_apply()` |
| `gconf_client_get_default_from_schema()` | no equivalent, applications are expected to know their schema |
| `gconf_client_all_entries()` | no equivalent, applications are expected to know their schema, and GSettings does not allow schema-less entries |
| `gconf_client_get_without_default()` | no equivalent |
| `gconf_bridge_bind_property()` | `g_settings_bind()` |
| `gconf_bridge_bind_property_full()` | `g_settings_bind_with_mapping()` |
GConfBridge was a third-party library that used GConf to bind an object
property to a particular configuration key. GSettings offers this service
itself.
There is a pattern that is sometimes used for GConf, where a setting can
have explicit 'value A', explicit 'value B' or 'use the system default'.
With GConf, 'use the system default' is sometimes implemented by unsetting
the user value. This is not possible in GSettings, since it does not have
API to determine if a value is the default and does not let you unset
values. The recommended way (and much clearer) way in which this can be
implemented in GSettings is to have a separate 'use-system-default' boolean
setting.
## Change notification
GConf requires you to call `gconf_client_add_dir()` and
`gconf_client_notify_add()` to get change notification. With GSettings, this
is not necessary; signals get emitted automatically for every change.
The [signal@Gio.Settings::changed] signal is emitted for each changed key.
There is also a [`signal@Gio.Settings::change-event`] signal that you can
handle if you need to see groups of keys that get changed at the same time.
GSettings also notifies you about changes in writability of keys, with the
[signal@Gio.Settings::writable-changed] signal (and the
[signal@Gio.Settings::writable-change-event] signal).
## Change sets
GConf has a concept of a set of changes which can be applied or reverted at
once: `GConfChangeSet` (GConf doesn't actually apply changes atomically,
which is one of its shortcomings).
Instead of a separate object to represent a change set, GSettings has a
'delayed-apply' mode, which can be turned on for a [class@Gio.Settings]
object by calling [method@Gio.Settings.delay]. In this mode, changes done to
the GSettings object are not applied - they are still visible when calling
[method@Gio.Settings.get] on the same object, but not to other GSettings
instances or even other processes.
To apply the pending changes all at once (GSettings does atomicity here),
call [method@Gio.Settings.apply]. To revert the pending changes, call
[method@Gio.Settings.revert] or just drop the reference to the GSettings
object.
## Schema conversion
If you are porting your application from GConf, most likely you already have
a GConf schema. GConf comes with a commandline tool
`gsettings-schema-convert` that can help with the task of converting a GConf
schema into an equivalent GSettings schema. The tool is not perfect and may
need assistance in some cases.
### An example for using gsettings-schema-convert
Running `gsettings-schema-convert --gconf --xml --schema-id
"org.gnome.font-rendering" --output org.gnome.font-rendering.gschema.xml
destop_gnome_font_rendering.schemas` on the following
`desktop_gnome_font_rendering.schemas` file:
```xml
<?xml version="1.0"?>
<gconfschemafile>
<schemalist>
<schema>
<key>/schemas/desktop/gnome/font_rendering/dpi</key>
<applyto>/desktop/gnome/font_rendering/dpi</applyto>
<owner>gnome</owner>
<type>int</type>
<default>96</default>
<locale name="C">
<short>DPI</short>
<long>The resolution used for converting font sizes to pixel sizes, in dots per inch.</long>
</locale>
</schema>
</schemalist>
</gconfschemafile>
```
produces an `org.gnome.font-rendering.gschema.xml` file with the following content:
```xml
<schemalist>
<schema id="org.gnome.font-rendering" path="/desktop/gnome/font_rendering/">
<key name="dpi" type="i">
<default>96</default>
<summary>DPI</summary>
<description>The resolution used for converting font sizes to pixel sizes, in dots per inch.</description>
</key>
</schema>
</schemalist>
```
GSettings schemas are identified at runtime by their id (as specified in the
XML source file). It is recommended to use a dotted name as schema id,
similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In
cases where the settings are general and not specific to one application,
the id should not use StudlyCaps, e.g. "org.gnome.font-rendering". The
filename used for the XML schema source is immaterial, but schema compiler
expects the files to have the extension `.gschema.xml`. It is recommended to
simply use the schema id as the filename, followed by this extension, e.g.
`org.gnome.SessionManager.gschema.xml`.
The XML source file for your GSettings schema needs to get installed into
`$datadir/glib-2.0/schemas`, and needs to be compiled into a binary form. At
runtime, GSettings looks for compiled schemas in the `glib-2.0/schemas`
subdirectories of all `XDG_DATA_DIRS` directories, so if you install your
schema in a different location, you need to set the `XDG_DATA_DIRS`
environment variable appropriately.
Schemas are compiled into binary form by the `glib-compile-schemas` utility.
GIO provides a `glib_compile_schemas` variable in its pkg-config file
pointing to the schema compiler binary.
### Using schemas with Meson
You should use `install_data()` to install the `.gschema.xml` file in the
correct directory, e.g.
```
install_data('my.app.gschema.xml', install_dir: get_option('datadir') / 'glib-2.0/schemas')
```
Schema compilation is done at installation time; if you are using Meson 0.57 or newer, you can use the `gnome.post_install()` function from the GNOME module:
```
gnome.post_install(glib_compile_schemas: true)
```
Alternatively, you can use `meson.add_install_script()` and the following
Python script:
```py
#!/usr/bin/env python3
# build-aux/compile-schemas.py
import os
import subprocess
install_prefix = os.environ['MESON_INSTALL_PREFIX']
schemadir = os.path.join(install_prefix, 'share', 'glib-2.0', 'schemas')
if not os.environ.get('DESTDIR'):
print('Compiling gsettings schemas...')
subprocess.call(['glib-compile-schemas', schemadir])
```
```
meson.add_install_script('build-aux/compile-schemas.py')
```
### Using schemas with Autotools
GLib provides m4 macros for hiding the various complexities and reduce the
chances of getting things wrong.
To handle schemas in your Autotools build, start by adding this to your
`configure.ac`:
```
GLIB_GSETTINGS
```
Then add this fragment to your `Makefile.am`:
```
# gsettings_SCHEMAS is a list of all the schemas you want to install
gsettings_SCHEMAS = my.app.gschema.xml
# include the appropriate makefile rules for schema handling
@GSETTINGS_RULES@
```
This is not sufficient on its own. You need to mention what the source of
the `my.app.gschema.xml` file is. If the schema file is distributed directly
with your project's tarball then a mention in `EXTRA_DIST` is appropriate. If
the schema file is generated from another source then you will need the
appropriate rule for that, plus probably an item in `EXTRA_DIST` for the
source files used by that rule.
One possible pitfall in doing schema conversion is that the default values
in GSettings schemas are parsed by the GVariant parser. This means that
strings need to include quotes in the XML. Also note that the types are now
specified as GVariant type strings.
```xml
<type>string</type>
<default>rgb</default>
```
becomes
```xml
<key name="rgba-order" type="s">
<default>'rgb'</default> <!-- note quotes -->
</key>
```
Another possible complication is that GConf specifies full paths for each
key, while a GSettings schema has a 'path' attribute that contains the
prefix for all the keys in the schema, and individual keys just have a
simple name. So
```xml
<key>/schemas/desktop/gnome/font_rendering/antialiasing</key>
```
becomes
```xml
<schema id="org.gnome.font" path="/desktop/gnome/font_rendering/">
<key name="antialiasing" type="s">
```
Default values can be localized in both GConf and GSettings schemas, but
GSettings uses gettext for the localization. You can specify the gettext
domain to use in the gettext-domain attribute. Therefore, when converting
localized defaults in GConf,
```xml
<key>/schemas/apps/my_app/font_size</key>
<locale name="C">
<default>18</default>
</locale>
<locale name="be">
<default>24</default>
</locale>
</key>
```
becomes
```xml
<schema id="..." gettext-domain="your-domain">
...
<key name="font-size" type="i">
<default l10n="messages" context="font_size">18</default>
</key>
```
GSettings uses gettext for translation of default values. The string that is
translated is exactly the string that appears inside of the `<default>`
element. This includes the quotation marks that appear around strings.
Default values must be marked with the l10n attribute in the `<default>` tag,
which should be set as equal to 'messages' or 'time' depending on the
desired category. An optional translation context can also be specified with
the context attribute, as in the example. This is usually recommended, since
the string "18" is not particularly easy to translate without context. The
translated version of the default value should be stored in the specified
gettext-domain. Care must be taken during translation to ensure that all
translated values remain syntactically valid; mistakes here will cause
runtime errors.
GSettings schemas have optional `<summary>` and `<description>` elements for
each key which correspond to the `<short>` and `<long>` elements in the
GConf schema and can be used in the same way by a GUI editor, so you should
use the same conventions for them: The summary is just a short label with no
punctuation, the description can be one or more complete sentences. If
multiple paragraphs are desired for the description, the paragraphs should
be separated by a completely empty line.
Translations for these strings will also be handled via gettext, so you
should arrange for these strings to be extracted into your gettext catalog.
Gettext supports GSettings schemas natively since version 0.19, so all you
have to do is add the XML schema file to the list of translatable files
inside your `POTFILES.in`.
GSettings is a bit more restrictive about key names than GConf. Key names in
GSettings can be at most 32 characters long, and must only consist of
lowercase characters, numbers and dashes, with no consecutive dashes. The
first character must not be a number or dash, and the last character cannot
be '-'.
If you are using the GConf backend for GSettings during the transition, you
may want to keep your key names the same they were in GConf, so that
existing settings in the users GConf database are preserved. You can achieve
this by using the `--allow-any-name` with the `glib-compile-schemas` schema
compiler. Note that this option is only meant to ease the process of porting
your application, allowing parts of your application to continue to access
GConf and parts to use GSettings. By the time you have finished porting your
application you must ensure that all key names are valid.
## Data conversion
GConf comes with a GSettings backend that can be used to facility the
transition to the GSettings API until you are ready to make the jump to a
different backend (most likely dconf). To use it, you need to set the
`GSETTINGS_BACKEND` to 'gconf', e.g. by using
```c
g_setenv ("GSETTINGS_BACKEND", "gconf", TRUE);
```
early on in your program. Note that this backend is meant purely as a
transition tool, and should not be used in production.
GConf also comes with a utility called `gsettings-data-convert`, which is
designed to help with the task of migrating user settings from GConf into
another GSettings backend. It can be run manually, but it is designed to be
executed automatically, every time a user logs in. It keeps track of the
data migrations that it has already done, and it is harmless to run it more
than once.
To make use of this utility, you must install a keyfile in the directory
`/usr/share/GConf/gsettings` which lists the GSettings keys and GConf paths
to map to each other, for each schema that you want to migrate user data
for.
Here is an example:
```
[org.gnome.fonts]
antialiasing = /desktop/gnome/font_rendering/antialiasing
dpi = /desktop/gnome/font_rendering/dpi
hinting = /desktop/gnome/font_rendering/hinting
rgba-order = /desktop/gnome/font_rendering/rgba_order
[apps.myapp:/path/to/myapps/]
some-odd-key1 = /apps/myapp/some_ODD-key1
```
The last key demonstrates that it may be necessary to modify the key name to
comply with stricter GSettings key name rules. Of course, that means your
application must use the new key names when looking up settings in
GSettings.
The last group in the example also shows how to handle the case of
'relocatable' schemas, which don't have a fixed path. You can specify the
path to use in the group name, separated by a colon.
There are some limitations: `gsettings-data-convert` does not do any
transformation of the values. And it does not handle complex GConf types
other than lists of strings or integers.
**Don't forget to require GConf 2.31.1 or newer in your configure script if
you are making use of the GConf backend or the conversion utility.**
If, as an application developer, you are interested in manually ensuring
that `gsettings-data-convert` has been invoked (for example, to deal with the
case where the user is logged in during a distribution upgrade or for
non-XDG desktop environments which do not run the command as an autostart)
you may invoke it manually during your program initialisation. This is not
recommended for all application authors -- it is your choice if this use
case concerns you enough.
Internally, `gsettings-data-convert` uses a keyfile to track which settings
have been migrated. The following code fragment will check that keyfile to
see if your data conversion script has been run yet and, if not, will
attempt to invoke the tool to run it. You should adapt it to your
application as you see fit.
```c
static void
ensure_migrated (const gchar *name)
{
gboolean needed = TRUE;
GKeyFile *kf;
gchar **list;
gsize i, n;
kf = g_key_file_new ();
g_key_file_load_from_data_dirs (kf, "gsettings-data-convert",
NULL, G_KEY_FILE_NONE, NULL);
list = g_key_file_get_string_list (kf, "State", "converted", &n, NULL);
if (list)
{
for (i = 0; i < n; i++)
if (strcmp (list[i], name) == 0)
{
needed = FALSE;
break;
}
g_strfreev (list);
}
g_key_file_free (kf);
if (needed)
g_spawn_command_line_sync ("gsettings-data-convert",
NULL, NULL, NULL, NULL);
}
```
Although there is the possibility that the `gsettings-data-convert` script
will end up running multiple times concurrently with this approach, it is
believed that this is safe.

515
docs/reference/gio/migrating-gconf.xml
View File

@ -1,515 +0,0 @@
<chapter>
<title>Migrating from GConf to GSettings</title>
<section>
<title>Before you start</title>
<para>
Converting individual applications and their settings from GConf to
GSettings can be done at will. But desktop-wide settings like font or
theme settings often have consumers in multiple modules. Therefore,
some consideration has to go into making sure that all users of a setting
are converted to GSettings at the same time or that the program
responsible for configuring that setting continues to update the value in
both places.
</para>
<para>
It is always a good idea to have a look at how others have handled
similar problems before.
</para>
</section>
<section>
<title>Conceptual differences</title>
<para>
Conceptually, GConf and GSettings are fairly similar. Both
have a concept of pluggable backends. Both keep information
about keys and their types in schemas. Both have a concept of
mandatory values, which lets you implement lock-down.
</para>
<para>
There are some differences in the approach to schemas. GConf
installs the schemas into the database and has API to handle
schema information (gconf_client_get_default_from_schema(),
gconf_value_get_schema(), etc). GSettings on the other hand
assumes that an application knows its own schemas, and does
not provide API to handle schema information at runtime.
GSettings is also more strict about requiring a schema whenever
you want to read or write a key. To deal with more free-form
information that would appear in schema-less entries in GConf,
GSettings allows for schemas to be 'relocatable'.
</para>
<para>
One difference in the way applications interact with their
settings is that with GConf you interact with a tree of
settings (ie the keys you pass to functions when reading
or writing values are actually paths with the actual name
of the key as the last element. With GSettings, you create
a GSettings object which has an implicit prefix that determines
where the settings get stored in the global tree of settings,
but the keys you pass when reading or writing values are just
the key names, not the full path.
</para>
</section>
<section>
<title>GConfClient (and GConfBridge) API conversion</title>
<para>
Most people use GConf via the high-level #GConfClient API.
The corresponding API is the #GSettings object. While not
every GConfClient function has a direct GSettings equivalent,
many do:
<table id="gconf-client-vs-gsettings">
<tgroup cols="2">
<thead>
<row><entry>GConfClient</entry><entry>GSettings</entry></row>
</thead>
<tbody>
<row><entry>gconf_client_get_default()</entry><entry>no direct equivalent,
instead you call g_settings_new() for the schemas you use</entry></row>
<row><entry>gconf_client_set()</entry><entry>g_settings_set()</entry></row>
<row><entry>gconf_client_get()</entry><entry>g_settings_get()</entry></row>
<row><entry>gconf_client_get_bool()</entry><entry>g_settings_get_boolean()</entry></row>
<row><entry>gconf_client_set_bool()</entry><entry>g_settings_set_boolean()</entry></row>
<row><entry>gconf_client_get_int()</entry><entry>g_settings_get_int()</entry></row>
<row><entry>gconf_client_set_int()</entry><entry>g_settings_set_int()</entry></row>
<row><entry>gconf_client_get_float()</entry><entry>g_settings_get_double()</entry></row>
<row><entry>gconf_client_set_float()</entry><entry>g_settings_set_double()</entry></row>
<row><entry>gconf_client_get_string()</entry><entry>g_settings_get_string()</entry></row>
<row><entry>gconf_client_set_string()</entry><entry>g_settings_set_string()</entry></row>
<row><entry>gconf_client_get_list()</entry><entry>for string lists, see g_settings_get_strv(), else see g_settings_get_value() and #GVariant API</entry></row>
<row><entry>gconf_client_set_list()</entry><entry>for string lists, see g_settings_set_strv(), else see g_settings_set_value() and #GVariant API</entry></row>
<row><entry>gconf_entry_get_is_writable()</entry><entry>g_settings_is_writable()</entry></row>
<row><entry>gconf_client_notify_add()</entry><entry>not required, the #GSettings::changed signal is emitted automatically</entry></row>
<row><entry>gconf_client_add_dir()</entry><entry>not required, each GSettings instance automatically watches all keys in its path</entry></row>
<row><entry>#GConfChangeSet</entry><entry>g_settings_delay(), g_settings_apply()</entry></row>
<row><entry>gconf_client_get_default_from_schema()</entry><entry>no equivalent, applications are expected to know their schema</entry></row>
<row><entry>gconf_client_all_entries()</entry><entry>no equivalent, applications are expected to know their schema, and GSettings does not allow schema-less entries</entry></row>
<row><entry>gconf_client_get_without_default()</entry><entry>no equivalent</entry></row>
<row><entry>gconf_bridge_bind_property()</entry><entry>g_settings_bind()</entry></row>
<row><entry>gconf_bridge_bind_property_full()</entry><entry>g_settings_bind_with_mapping()</entry></row>
</tbody>
</tgroup>
</table>
</para>
<para>
GConfBridge was a third-party library that used GConf to bind an object property
to a particular configuration key. GSettings offers this service itself.
</para>
<para>
There is a pattern that is sometimes used for GConf, where a setting can have
explicit 'value A', explicit 'value B' or 'use the system default'. With GConf,
'use the system default' is sometimes implemented by unsetting the user value.
</para>
<para>
This is not possible in GSettings, since it does not have API to determine if a value
is the default and does not let you unset values. The recommended way (and much
clearer) way in which this can be implemented in GSettings is to have a separate
'use-system-default' boolean setting.
</para>
</section>
<section>
<title>Change notification</title>
<para>
GConf requires you to call gconf_client_add_dir() and
gconf_client_notify_add() to get change notification. With
GSettings, this is not necessary; signals get emitted automatically
for every change.
</para>
<para>
The #GSettings::changed signal is emitted for each changed key.
There is also a #GSettings::change-event signal that you can handle
if you need to see groups of keys that get changed at the same time.
</para>
<para>
GSettings also notifies you about changes in writability of keys,
with the #GSettings::writable-changed signal (and the
#GSettings::writable-change-event signal).
</para>
</section>
<section><title>Change sets</title>
<para>
GConf has a concept of a set of changes which can be applied or reverted
at once: #GConfChangeSet (GConf doesn't actually apply changes atomically,
which is one of its shortcomings).
</para>
<para>
Instead of a separate object to represent a change set, GSettings has a
'delayed-apply' mode, which can be turned on for a GSettings object by
calling g_settings_delay(). In this mode, changes done to the GSettings
object are not applied - they are still visible when calling g_settings_get()
<emphasis>on the same object</emphasis>, but not to other GSettings instances
or even other processes.
</para>
<para>
To apply the pending changes all at once (GSettings <emphasis>does</emphasis>
atomicity here), call g_settings_apply(). To revert the pending changes,
call g_settings_revert() or just drop the reference to the #GSettings object.
</para>
</section>
<section>
<title>Schema conversion</title>
<para>
If you are porting your application from GConf, most likely you already
have a GConf schema. GConf comes with a commandline tool
gsettings-schema-convert that can help with the task of converting
a GConf schema into an equivalent GSettings schema. The tool is not
perfect and may need assistance in some cases.
</para>
<example><title>An example for using gsettings-schema-convert</title>
<para>Running <userinput>gsettings-schema-convert --gconf --xml --schema-id "org.gnome.font-rendering" --output org.gnome.font-rendering.gschema.xml destop_gnome_font_rendering.schemas</userinput> on the following <filename>desktop_gnome_font_rendering.schemas</filename> file:
<programlisting>
<![CDATA[
<?xml version="1.0"?>
<gconfschemafile>
<schemalist>
<schema>
<key>/schemas/desktop/gnome/font_rendering/dpi</key>
<applyto>/desktop/gnome/font_rendering/dpi</applyto>
<owner>gnome</owner>
<type>int</type>
<default>96</default>
<locale name="C">
<short>DPI</short>
<long>The resolution used for converting font sizes to pixel sizes, in dots per inch.</long>
</locale>
</schema>
</schemalist>
</gconfschemafile>
]]>
</programlisting>
produces a <filename>org.gnome.font-rendering.gschema.xml</filename> file with the following content:
<programlisting>
<![CDATA[
<schemalist>
<schema id="org.gnome.font-rendering" path="/desktop/gnome/font_rendering/">
<key name="dpi" type="i">
<default>96</default>
<summary>DPI</summary>
<description>The resolution used for converting font sizes to pixel sizes, in dots per inch.</description>
</key>
</schema>
</schemalist>
]]>
</programlisting>
</para>
</example>
<para>
GSettings schemas are identified at runtime by their id (as specified
in the XML source file). It is recommended to use a dotted name as schema
id, similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager".
In cases where the settings are general and not specific to one application,
the id should not use StudlyCaps, e.g. "org.gnome.font-rendering".
The filename used for the XML schema source is immaterial, but
schema compiler expects the files to have the extension
<filename>.gschema.xml</filename>. It is recommended to simply
use the schema id as the filename, followed by this extension,
e.g. <filename>org.gnome.SessionManager.gschema.xml</filename>.
</para>
<para>
The XML source file for your GSettings schema needs to get installed
into <filename>$datadir/glib-2.0/schemas</filename>, and needs to be
compiled into a binary form. At runtime, GSettings looks for compiled
schemas in the <filename>glib-2.0/schemas</filename> subdirectories
of all <envar>XDG_DATA_DIRS</envar> directories, so if you install
your schema in a different location, you need to set the
<envar>XDG_DATA_DIRS</envar> environment variable appropriately.
</para>
<para>
Schemas are compiled into binary form by the
<link linkend="glib-compile-schemas">glib-compile-schemas</link> utility.
GIO provides a <literal>glib_compile_schemas</literal>
variable for the schema compiler.
</para>
<para>
You can ignore all of this by using the provided m4 macros. To
do this, add to your <filename>configure.ac</filename>:
<programlisting>
GLIB_GSETTINGS
</programlisting>
The corresponding <filename>Makefile.am</filename> fragment looks like
this:
<programlisting>
# gsettings_SCHEMAS is a list of all the schemas you want to install
gsettings_SCHEMAS = my.app.gschema.xml
# include the appropriate makefile rules for schema handling
@GSETTINGS_RULES@
</programlisting>
</para>
<para>
This is not sufficient on its own. You need to mention what the source
of the <filename>my.app.gschema.xml</filename> file is. If the schema
file is distributed directly with your project's tarball then a mention
in <varname>EXTRA_DIST</varname> is appropriate. If the schema file is
generated from another source then you will need the appropriate rule
for that, plus probably an item in <varname>EXTRA_DIST</varname> for the
source files used by that rule.
</para>
<para>
One possible pitfall in doing schema conversion is that the default
values in GSettings schemas are parsed by the #GVariant parser.
This means that strings need to include quotes in the XML. Also note
that the types are now specified as #GVariant type strings.
<programlisting>
<![CDATA[
<type>string</type>
<default>rgb</default>
]]>
</programlisting>
becomes
<programlisting>
<![CDATA[
<key name="rgba-order" type="s">
<default>'rgb'</default> <!-- note quotes -->
</key>
]]>
</programlisting>
</para>
<para>
Another possible complication is that GConf specifies full paths
for each key, while a GSettings schema has a 'path' attribute that
contains the prefix for all the keys in the schema, and individual
keys just have a simple name. So
<programlisting>
<![CDATA[
<key>/schemas/desktop/gnome/font_rendering/antialiasing</key>
]]>
</programlisting>
becomes
<programlisting>
<![CDATA[
<schema id="org.gnome.font" path="/desktop/gnome/font_rendering/">
<key name="antialiasing" type="s">
]]>
</programlisting>
</para>
<para>
Default values can be localized in both GConf and GSettings schemas,
but GSettings uses gettext for the localization. You can specify
the gettext domain to use in the <tag class="attribute">gettext-domain</tag>
attribute. Therefore, when converting localized defaults in GConf,
<programlisting>
<![CDATA[
<key>/schemas/apps/my_app/font_size</key>
<locale name="C">
<default>18</default>
</locale>
<locale name="be">
<default>24</default>
</locale>
</key>
]]>
</programlisting>
becomes
<programlisting>
<![CDATA[
<schema id="..." gettext-domain="your-domain">
...
<key name="font-size" type="i">
<default l10n="messages" context="font_size">18</default>
</key>
]]>
</programlisting>
</para>
<para>
GSettings uses gettext for translation of default values.
The string that is translated is exactly the string that appears
inside of the <tag class='starttag'>default</tag> element. This
includes the quotation marks that appear around strings.
Default values must be marked with the <varname>l10n</varname>
attribute in the <tag class='starttag'>default</tag> tag, which
should be set as equal to <literal>'messages'</literal> or
<literal>'time'</literal> depending on the desired category. An
optional translation context can also be specified with the
<varname>context</varname> attribute, as in the example. This
is usually recommended, since the string "<literal>18</literal>"
is not particularly easy to translate without context. The
translated version of the default value should be stored in the
specified <varname>gettext-domain</varname>. Care must be taken
during translation to ensure that all translated values remain
syntactically valid; mistakes here will cause runtime errors.
</para>
<para>
GSettings schemas have optional <tag class="starttag">summary</tag> and
<tag class="starttag">description</tag> elements for each key which
correspond to the <tag class="starttag">short</tag> and
<tag class="starttag">long</tag> elements in the GConf schema and
will be used in similar ways by a future gsettings-editor, so you
should use the same conventions for them: The summary is just a short
label with no punctuation, the description can be one or more complete
sentences. If multiple paragraphs are desired for the description, the
paragraphs should be separated by a completely empty line.
</para>
<para>
Translations for these strings will also be handled
via gettext, so you should arrange for these strings to be
extracted into your gettext catalog. One way to do that is to use
intltool. Since intltool 0.50.1, schema files are
supported, so all you have to do is to add your .gschema.xml
files to <filename>POTFILES.in</filename> with a line like
<programlisting>
[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
</programlisting>
</para>
<para>
GSettings is a bit more restrictive about key names than GConf. Key
names in GSettings can be at most 32 characters long, and must only
consist of lowercase characters, numbers and dashes, with no
consecutive dashes. The first character must not be a number or dash,
and the last character cannot be '-'.
</para>
<para>
If you are using the GConf backend for GSettings during the
transition, you may want to keep your key names the same they
were in GConf, so that existing settings in the users GConf
database are preserved. You can achieve this by using the
<option>--allow-any-name</option> with the
<link linkend="glib-compile-schemas">glib-compile-schemas</link> schema
compiler. Note that this option is only meant
to ease the process of porting your application, allowing parts
of your application to continue to access GConf and parts to use
GSettings. By the time you have finished porting your application
you must ensure that all key names are valid.
</para>
</section>
<section><title>Data conversion</title>
<para>
GConf comes with a GSettings backend that can be used to
facility the transition to the GSettings API until you are
ready to make the jump to a different backend (most likely
dconf). To use it, you need to set the <envar>GSETTINGS_BACKEND</envar>
to 'gconf', e.g. by using
<programlisting>
g_setenv ("GSETTINGS_BACKEND", "gconf", TRUE);
</programlisting>
early on in your program. Note that this backend is meant purely
as a transition tool, and should not be used in production.
</para>
<para>
GConf also comes with a utility called
<command>gsettings-data-convert</command>, which is designed to help
with the task of migrating user settings from GConf into another
GSettings backend. It can be run manually, but it is designed to be
executed automatically, every time a user logs in. It keeps track of
the data migrations that it has already done, and it is harmless to
run it more than once.
</para>
<para>
To make use of this utility, you must install a keyfile in the
directory <filename>/usr/share/GConf/gsettings</filename> which
lists the GSettings keys and GConf paths to map to each other, for
each schema that you want to migrate user data for.
</para>
<para>
Here is an example:
<programlisting>
<![CDATA[
[org.gnome.fonts]
antialiasing = /desktop/gnome/font_rendering/antialiasing
dpi = /desktop/gnome/font_rendering/dpi
hinting = /desktop/gnome/font_rendering/hinting
rgba-order = /desktop/gnome/font_rendering/rgba_order
[apps.myapp:/path/to/myapps/]
some-odd-key1 = /apps/myapp/some_ODD-key1
]]>
</programlisting>
The last key demonstrates that it may be necessary to modify the key
name to comply with stricter GSettings key name rules. Of course,
that means your application must use the new key names when looking
up settings in GSettings.
</para>
<para>
The last group in the example also shows how to handle the case
of 'relocatable' schemas, which don't have a fixed path. You can
specify the path to use in the group name, separated by a colon.
</para>
<para>
There are some limitations: <command>gsettings-data-convert</command>
does not do any transformation of the values. And it does not handle
complex GConf types other than lists of strings or integers.
</para>
<para>
Don't forget to require GConf 2.31.1 or newer in your configure
script if you are making use of the GConf backend or the conversion
utility.
</para>
<para>
If, as an application developer, you are interested in manually
ensuring that <command>gsettings-data-convert</command> has been
invoked (for example, to deal with the case where the user is
logged in during a distribution upgrade or for non-XDG desktop
environments which do not run the command as an autostart) you
may invoke it manually during your program initialisation. This
is not recommended for all application authors -- it is your
choice if this use case concerns you enough.
</para>
<para>
Internally, <command>gsettings-data-convert</command> uses a
keyfile to track which settings have been migrated. The
following code fragment will check that keyfile to see if your
data conversion script has been run yet and, if not, will
attempt to invoke the tool to run it. You should adapt it to
your application as you see fit.
</para>
<para>
<programlisting>
<![CDATA[
static void
ensure_migrated (const gchar *name)
{
gboolean needed = TRUE;
GKeyFile *kf;
gchar **list;
gsize i, n;
kf = g_key_file_new ();
g_key_file_load_from_data_dirs (kf, "gsettings-data-convert",
NULL, G_KEY_FILE_NONE, NULL);
list = g_key_file_get_string_list (kf, "State", "converted", &n, NULL);
if (list)
{
for (i = 0; i < n; i++)
if (strcmp (list[i], name) == 0)
{
needed = FALSE;
break;
}
g_strfreev (list);
}
g_key_file_free (kf);
if (needed)
g_spawn_command_line_sync ("gsettings-data-convert",
NULL, NULL, NULL, NULL);
}
]]>
</programlisting>
</para>
<para>
Although there is the possibility that the
<command>gsettings-data-convert</command> script will end up
running multiple times concurrently with this approach, it is
believed that this is safe.
</para>
</section>
</chapter>

633
docs/reference/gio/migrating-gdbus.md Normal file
View File

@ -0,0 +1,633 @@
Title: Migrating to GDBus
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 Matthias Clasen
SPDX-FileCopyrightText: 2010, 2011 David Zeuthen
# Migrating to GDBus
## Conceptual differences
The central concepts of D-Bus are modelled in a very similar way in
dbus-glib and GDBus. Both have objects representing connections, proxies and
method invocations. But there are some important differences:
- dbus-glib uses the libdbus reference implementation, GDBus doesn't.
Instead, it relies on GIO streams as transport layer, and has its own
implementation for the D-Bus connection setup and authentication. Apart
from using streams as transport, avoiding libdbus also lets GDBus avoid
some thorny multithreading issues.
- dbus-glib uses the GObject type system for method arguments and return
values, including a homegrown container specialization mechanism. GDBus
relies on the GVariant type system which is explicitly designed to match
D-Bus types.
- dbus-glib models only D-Bus interfaces and does not provide any types for
objects. GDBus models both D-Bus interfaces (via the GDBusInterface,
GDBusProxy and GDBusInterfaceSkeleton types) and objects (via the
GDBusObject, GDBusObjectSkeleton and GDBusObjectProxy types).
- GDBus includes native support for the org.freedesktop.DBus.Properties (via
the GDBusProxy type) and org.freedesktop.DBus.ObjectManager D-Bus
interfaces, dbus-glib doesn't.
- The typical way to export an object in dbus-glib involves generating glue
code from XML introspection data using dbus-binding-tool. GDBus provides a
similar tool called gdbus-codegen that can also generate Docbook D-Bus
interface documentation.
- dbus-glib doesn't provide any convenience API for owning and watching bus
names, GDBus provides the `g_bus_own_name()` and `g_bus_watch_name()`
family of convenience functions.
- GDBus provides API to parse, generate and work with Introspection XML,
dbus-glib doesn't.
- GTestDBus provides API to create isolated unit tests
## API comparison
| dbus-glib | GDBus |
|-----------|-------|
| `DBusGConnection` | `GDBusConnection` |
| `DBusGProxy` | `GDBusProxy`, `GDBusInterface` - also see `GDBusObjectProxy` |
| `DBusGObject` | `GDBusInterfaceSkeleton`, `GDBusInterface` - also see `GDBusObjectSkeleton` |
| `DBusGMethodInvocation` | `GDBusMethodInvocation` |
| `dbus_g_bus_get()` | `g_bus_get_sync()`, also see `g_bus_get()` |
| `dbus_g_proxy_new_for_name()` | `g_dbus_proxy_new_sync()` and `g_dbus_proxy_new_for_bus_sync()`, also see `g_dbus_proxy_new()` |
| `dbus_g_proxy_add_signal()` | not needed, use the generic “g-signal” |
| `dbus_g_proxy_connect_signal()` | use `g_signal_connect()` with “g-signal” |
| `dbus_g_connection_register_g_object()` | `g_dbus_connection_register_object()` - also see `g_dbus_object_manager_server_export()` |
| `dbus_g_connection_unregister_g_object()` | `g_dbus_connection_unregister_object()` - also see `g_dbus_object_manager_server_unexport()` |
| `dbus_g_object_type_install_info()` | introspection data is installed while registering an object, see `g_dbus_connection_register_object()` |
| `dbus_g_proxy_begin_call()` | `g_dbus_proxy_call()` |
| `dbus_g_proxy_end_call()` | `g_dbus_proxy_call_finish()` |
| `dbus_g_proxy_call()` | `g_dbus_proxy_call_sync()` |
| `dbus_g_error_domain_register()` | `g_dbus_error_register_error_domain()` |
| `dbus_g_error_has_name()` | no direct equivalent, see `g_dbus_error_get_remote_error()` |
| `dbus_g_method_return()` | `g_dbus_method_invocation_return_value()` |
| `dbus_g_method_return_error()` | `g_dbus_method_invocation_return_error()` and variants |
| `dbus_g_method_get_sender()` | `g_dbus_method_invocation_get_sender()` |
## Owning bus names
Using dbus-glib, you typically call RequestName manually to own a name, like in the following excerpt:
```c
error = NULL;
res = dbus_g_proxy_call (system_bus_proxy,
"RequestName",
&error,
G_TYPE_STRING, NAME_TO_CLAIM,
G_TYPE_UINT, DBUS_NAME_FLAG_ALLOW_REPLACEMENT,
G_TYPE_INVALID,
G_TYPE_UINT, &result,
G_TYPE_INVALID);
if (!res)
{
if (error != NULL)
{
g_warning ("Failed to acquire %s: %s",
NAME_TO_CLAIM, error->message);
g_error_free (error);
}
else
{
g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
}
goto out;
}
if (result != DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER)
{
if (error != NULL)
{
g_warning ("Failed to acquire %s: %s",
NAME_TO_CLAIM, error->message);
g_error_free (error);
}
else
{
g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
}
exit (1);
}
dbus_g_proxy_add_signal (system_bus_proxy, "NameLost",
G_TYPE_STRING, G_TYPE_INVALID);
dbus_g_proxy_connect_signal (system_bus_proxy, "NameLost",
G_CALLBACK (on_name_lost), NULL, NULL);
/* further setup ... */
```
While you can do things this way with GDBus too, using
`g_dbus_proxy_call_sync()`, it is much nicer to use the high-level API for
this:
```c
static void
on_name_acquired (GDBusConnection *connection,
const gchar *name,
gpointer user_data)
{
/* further setup ... */
}
/* ... */
owner_id = g_bus_own_name (G_BUS_TYPE_SYSTEM,
NAME_TO_CLAIM,
G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT,
on_bus_acquired,
on_name_acquired,
on_name_lost,
NULL,
NULL);
g_main_loop_run (loop);
g_bus_unown_name (owner_id);
```
Note that `g_bus_own_name()` works asynchronously and requires you to enter
your mainloop to await the `on_name_aquired()` callback. Also note that in
order to avoid race conditions (e.g. when your service is activated by a
method call), you have to export your manager object before acquiring the
name. The `on_bus_acquired()` callback is the right place to do such
preparations.
## Creating proxies for well-known names
dbus-glib lets you create proxy objects for well-known names, like the following example:
```c
proxy = dbus_g_proxy_new_for_name (system_bus_connection,
"org.freedesktop.Accounts",
"/org/freedesktop/Accounts",
"org.freedesktop.Accounts");
```
For a DBusGProxy constructed like this, method calls will be sent to the current owner of the name, and that owner can change over time.
The same can be achieved with GDBusProxy:
```c
error = NULL;
proxy = g_dbus_proxy_new_for_bus_sync (G_BUS_TYPE_SYSTEM,
G_DBUS_PROXY_FLAGS_NONE,
NULL, /* GDBusInterfaceInfo */
"org.freedesktop.Accounts",
"/org/freedesktop/Accounts",
"org.freedesktop.Accounts",
NULL, /* GCancellable */
&error);
```
For an added layer of safety, you can specify what D-Bus interface the proxy
is expected to conform to by using the GDBusInterfaceInfo type.
Additionally, GDBusProxy loads, caches and tracks changes to the D-Bus
properties on the remote object. It also sets up match rules so D-Bus
signals from the remote object are delivered locally.
The GDBusProxy type normally isn't used directly - instead proxies
subclassing GDBusProxy generated by `gdbus-codegen` is used, see the section
called “Using gdbus-codegen”.
## Generating code and docs
### Using gdbus-codegen
dbus-glib comes with dbus-binding-tool, which can produce somewhat nice
client- and server-side wrappers for a D-Bus interface. With GDBus,
gdbus-codegen is used and like its counterpart, it also takes D-Bus
Introspection XML as input:
#### Example D-Bus Introspection XML
```xml
<node>
<!-- org.gtk.GDBus.Example.ObjectManager.Animal:
@short_description: Example docs generated by gdbus-codegen
@since: 2.30
This D-Bus interface is used to describe a simple animal.
-->
<interface name="org.gtk.GDBus.Example.ObjectManager.Animal">
<!-- Mood: The mood of the animal.
@since: 2.30
Known values for this property include
<literal>Happy</literal> and <literal>Sad</literal>. Use the
org.gtk.GDBus.Example.ObjectManager.Animal.Poke() method to
change this property.
This property influences how often the animal jumps up and
down, see the
#org.gtk.GDBus.Example.ObjectManager.Animal::Jumped signal
for more details.
-->
<property name="Mood" type="s" access="read"/>
<!--
Poke:
@make_sad: Whether to make the animal sad.
@make_happy: Whether to make the animal happy.
@since: 2.30
Method used to changing the mood of the animal. See also the
#org.gtk.GDBus.Example.ObjectManager.Animal:Mood property.
-->
<method name="Poke">
<arg direction="in" type="b" name="make_sad"/>
<arg direction="in" type="b" name="make_happy"/>
</method>
<!--
Jumped:
@height: Height, in meters, that the animal jumped.
@since: 2.30
Emitted when the animal decides to jump.
-->
<signal name="Jumped">
<arg type="d" name="height"/>
</signal>
<!--
Foo:
Property with no <quote>since</quote> annotation (should inherit the 2.30 from its containing interface).
-->
<property name="Foo" type="s" access="read"/>
<!--
Bar:
@since: 2.36
Property with a later <quote>since</quote> annotation.
-->
<property name="Bar" type="s" access="read"/>
</interface>
<!-- org.gtk.GDBus.Example.ObjectManager.Cat:
@short_description: More example docs generated by gdbus-codegen
This D-Bus interface is used to describe a cat. Right now there
are no properties, methods or signals associated with this
interface so it is essentially a <ulink
url="http://en.wikipedia.org/wiki/Marker_interface_pattern">Marker
Interface</ulink>.
Note that D-Bus objects implementing this interface also
implement the #org.gtk.GDBus.Example.ObjectManager.Animal
interface.
-->
<interface name="org.gtk.GDBus.Example.ObjectManager.Cat">
</interface>
</node>
```
If this XML is processed like this
```
gdbus-codegen --interface-prefix org.gtk.GDBus.Example.ObjectManager. \
--generate-c-code generated-code \
--c-namespace Example \
--c-generate-object-manager \
--generate-docbook generated-docs \
gdbus-example-objectmanager.xml
```
then two files generated-code.h and generated-code.c are generated.
Additionally, two XML files
generated-docs-org.gtk.GDBus.Example.ObjectManager.Animal and
generated-docs-org.gtk.GDBus.Example.ObjectManager.Cat with Docbook XML are
generated.
While the contents of `generated-code.h` and `generated-code.c` are best described by the `gdbus-codegen` manual page, here's a brief example of how this generated code can be used:
```c
#include "gdbus-object-manager-example/objectmanager-gen.h"
/* ---------------------------------------------------------------------------------------------------- */
static GDBusObjectManagerServer *manager = NULL;
static gboolean
on_animal_poke (ExampleAnimal *animal,
GDBusMethodInvocation *invocation,
gboolean make_sad,
gboolean make_happy,
gpointer user_data)
{
if ((make_sad && make_happy) || (!make_sad && !make_happy))
{
g_dbus_method_invocation_return_dbus_error (invocation,
"org.gtk.GDBus.Examples.ObjectManager.Error.Failed",
"Exactly one of make_sad or make_happy must be TRUE");
goto out;
}
if (make_sad)
{
if (g_strcmp0 (example_animal_get_mood (animal), "Sad") == 0)
{
g_dbus_method_invocation_return_dbus_error (invocation,
"org.gtk.GDBus.Examples.ObjectManager.Error.SadAnimalIsSad",
"Sad animal is already sad");
goto out;
}
example_animal_set_mood (animal, "Sad");
example_animal_complete_poke (animal, invocation);
goto out;
}
if (make_happy)
{
if (g_strcmp0 (example_animal_get_mood (animal), "Happy") == 0)
{
g_dbus_method_invocation_return_dbus_error (invocation,
"org.gtk.GDBus.Examples.ObjectManager.Error.HappyAnimalIsHappy",
"Happy animal is already happy");
goto out;
}
example_animal_set_mood (animal, "Happy");
example_animal_complete_poke (animal, invocation);
goto out;
}
g_assert_not_reached ();
out:
return G_DBUS_METHOD_INVOCATION_HANDLED;
}
static void
on_bus_acquired (GDBusConnection *connection,
const gchar *name,
gpointer user_data)
{
ExampleObjectSkeleton *object;
guint n;
g_print ("Acquired a message bus connection\n");
/* Create a new org.freedesktop.DBus.ObjectManager rooted at /example/Animals */
manager = g_dbus_object_manager_server_new ("/example/Animals");
for (n = 0; n < 10; n++)
{
gchar *s;
ExampleAnimal *animal;
/* Create a new D-Bus object at the path /example/Animals/N where N is 000..009 */
s = g_strdup_printf ("/example/Animals/%03d", n);
object = example_object_skeleton_new (s);
g_free (s);
/* Make the newly created object export the interface
* org.gtk.GDBus.Example.ObjectManager.Animal (note
* that @object takes its own reference to @animal).
*/
animal = example_animal_skeleton_new ();
example_animal_set_mood (animal, "Happy");
example_object_skeleton_set_animal (object, animal);
g_object_unref (animal);
/* Cats are odd animals - so some of our objects implement the
* org.gtk.GDBus.Example.ObjectManager.Cat interface in addition
* to the .Animal interface
*/
if (n % 2 == 1)
{
ExampleCat *cat;
cat = example_cat_skeleton_new ();
example_object_skeleton_set_cat (object, cat);
g_object_unref (cat);
}
/* Handle Poke() D-Bus method invocations on the .Animal interface */
g_signal_connect (animal,
"handle-poke",
G_CALLBACK (on_animal_poke),
NULL); /* user_data */
/* Export the object (@manager takes its own reference to @object) */
g_dbus_object_manager_server_export (manager, G_DBUS_OBJECT_SKELETON (object));
g_object_unref (object);
}
/* Export all objects */
g_dbus_object_manager_server_set_connection (manager, connection);
}
static void
on_name_acquired (GDBusConnection *connection,
const gchar *name,
gpointer user_data)
{
g_print ("Acquired the name %s\n", name);
}
static void
on_name_lost (GDBusConnection *connection,
const gchar *name,
gpointer user_data)
{
g_print ("Lost the name %s\n", name);
}
gint
main (gint argc, gchar *argv[])
{
GMainLoop *loop;
guint id;
loop = g_main_loop_new (NULL, FALSE);
id = g_bus_own_name (G_BUS_TYPE_SESSION,
"org.gtk.GDBus.Examples.ObjectManager",
G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT |
G_BUS_NAME_OWNER_FLAGS_REPLACE,
on_bus_acquired,
on_name_acquired,
on_name_lost,
loop,
NULL);
g_main_loop_run (loop);
g_bus_unown_name (id);
g_main_loop_unref (loop);
return 0;
}
```
This, on the other hand, is a client-side application using generated code:
```c
#include "gdbus-object-manager-example/objectmanager-gen.h"
/* ---------------------------------------------------------------------------------------------------- */
static void
print_objects (GDBusObjectManager *manager)
{
GList *objects;
GList *l;
g_print ("Object manager at %s\n", g_dbus_object_manager_get_object_path (manager));
objects = g_dbus_object_manager_get_objects (manager);
for (l = objects; l != NULL; l = l->next)
{
ExampleObject *object = EXAMPLE_OBJECT (l->data);
GList *interfaces;
GList *ll;
g_print (" - Object at %s\n", g_dbus_object_get_object_path (G_DBUS_OBJECT (object)));
interfaces = g_dbus_object_get_interfaces (G_DBUS_OBJECT (object));
for (ll = interfaces; ll != NULL; ll = ll->next)
{
GDBusInterface *interface = G_DBUS_INTERFACE (ll->data);
g_print (" - Interface %s\n", g_dbus_interface_get_info (interface)->name);
/* Note that @interface is really a GDBusProxy instance - and additionally also
* an ExampleAnimal or ExampleCat instance - either of these can be used to
* invoke methods on the remote object. For example, the generated function
*
* void example_animal_call_poke_sync (ExampleAnimal *proxy,
* gboolean make_sad,
* gboolean make_happy,
* GCancellable *cancellable,
* GError **error);
*
* can be used to call the Poke() D-Bus method on the .Animal interface.
* Additionally, the generated function
*
* const gchar *example_animal_get_mood (ExampleAnimal *object);
*
* can be used to get the value of the :Mood property.
*/
}
g_list_free_full (interfaces, g_object_unref);
}
g_list_free_full (objects, g_object_unref);
}
static void
on_object_added (GDBusObjectManager *manager,
GDBusObject *object,
gpointer user_data)
{
gchar *owner;
owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
g_print ("Added object at %s (owner %s)\n", g_dbus_object_get_object_path (object), owner);
g_free (owner);
}
static void
on_object_removed (GDBusObjectManager *manager,
GDBusObject *object,
gpointer user_data)
{
gchar *owner;
owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
g_print ("Removed object at %s (owner %s)\n", g_dbus_object_get_object_path (object), owner);
g_free (owner);
}
static void
on_notify_name_owner (GObject *object,
GParamSpec *pspec,
gpointer user_data)
{
GDBusObjectManagerClient *manager = G_DBUS_OBJECT_MANAGER_CLIENT (object);
gchar *name_owner;
name_owner = g_dbus_object_manager_client_get_name_owner (manager);
g_print ("name-owner: %s\n", name_owner);
g_free (name_owner);
}
static void
on_interface_proxy_properties_changed (GDBusObjectManagerClient *manager,
GDBusObjectProxy *object_proxy,
GDBusProxy *interface_proxy,
GVariant *changed_properties,
const gchar *const *invalidated_properties,
gpointer user_data)
{
GVariantIter iter;
const gchar *key;
GVariant *value;
gchar *s;
g_print ("Properties Changed on %s:\n", g_dbus_object_get_object_path (G_DBUS_OBJECT (object_proxy)));
g_variant_iter_init (&iter, changed_properties);
while (g_variant_iter_next (&iter, "{&sv}", &key, &value))
{
s = g_variant_print (value, TRUE);
g_print (" %s -> %s\n", key, s);
g_variant_unref (value);
g_free (s);
}
}
gint
main (gint argc, gchar *argv[])
{
GDBusObjectManager *manager;
GMainLoop *loop;
GError *error;
gchar *name_owner;
manager = NULL;
loop = NULL;
loop = g_main_loop_new (NULL, FALSE);
error = NULL;
manager = example_object_manager_client_new_for_bus_sync (G_BUS_TYPE_SESSION,
G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_NONE,
"org.gtk.GDBus.Examples.ObjectManager",
"/example/Animals",
NULL, /* GCancellable */
&error);
if (manager == NULL)
{
g_printerr ("Error getting object manager client: %s", error->message);
g_error_free (error);
goto out;
}
name_owner = g_dbus_object_manager_client_get_name_owner (G_DBUS_OBJECT_MANAGER_CLIENT (manager));
g_print ("name-owner: %s\n", name_owner);
g_free (name_owner);
print_objects (manager);
g_signal_connect (manager,
"notify::name-owner",
G_CALLBACK (on_notify_name_owner),
NULL);
g_signal_connect (manager,
"object-added",
G_CALLBACK (on_object_added),
NULL);
g_signal_connect (manager,
"object-removed",
G_CALLBACK (on_object_removed),
NULL);
g_signal_connect (manager,
"interface-proxy-properties-changed",
G_CALLBACK (on_interface_proxy_properties_changed),
NULL);
g_main_loop_run (loop);
out:
if (manager != NULL)
g_object_unref (manager);
if (loop != NULL)
g_main_loop_unref (loop);
return 0;
}
```

310
docs/reference/gio/migrating-gdbus.xml
View File

@ -1,310 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<chapter>
<title>Migrating to GDBus</title>
<section>
<title>Conceptual differences</title>
<para>
The central concepts of D-Bus are modelled in a very similar way
in dbus-glib and GDBus. Both have objects representing connections,
proxies and method invocations. But there are some important
differences:
<itemizedlist>
<listitem><para>
dbus-glib uses the <ulink
url="http://www.freedesktop.org/wiki/Software/dbus#ReferenceImplementation.28dbus-daemonandlibdbus.29">libdbus
reference implementation</ulink>, GDBus doesn't. Instead, it
relies on GIO streams as transport layer, and has its own
implementation for the D-Bus connection setup and
authentication. Apart from using streams as transport,
avoiding libdbus also lets GDBus avoid some thorny
multithreading issues.
</para></listitem>
<listitem><para>
dbus-glib uses the GObject type system for method arguments and
return values, including a homegrown container specialization
mechanism. GDBus relies on the #GVariant type system which is
explicitly designed to match D-Bus types.
</para></listitem>
<listitem><para>
dbus-glib models only D-Bus interfaces and does not provide
any types for objects. GDBus models both D-Bus interfaces
(via the #GDBusInterface, #GDBusProxy and
#GDBusInterfaceSkeleton types) and objects (via the
#GDBusObject, #GDBusObjectSkeleton and #GDBusObjectProxy types).
</para></listitem>
<listitem><para>
GDBus includes native support for the <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> (via the #GDBusProxy type) and <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> D-Bus interfaces, dbus-glib doesn't.
</para></listitem>
<listitem><para>
The typical way to export an object in dbus-glib involves
generating glue code from XML introspection data using
<command>dbus-binding-tool</command>. GDBus provides a
similar tool called <command><link
linkend="gdbus-codegen">gdbus-codegen</link></command> that
can also generate Docbook D-Bus interface documentation.
</para></listitem>
<listitem><para>
dbus-glib doesn't provide any convenience API for owning and
watching bus names, GDBus provides the g_bus_own_name() and
g_bus_watch_name() family of convenience functions.
</para></listitem>
<listitem><para>
GDBus provides API to parse, generate and work with <link
linkend="gio-D-Bus-Introspection-Data">Introspection
XML</link>, dbus-glib doesn't.
</para></listitem>
<listitem><para>
GTestDBus provides API to create isolated unit tests <link
linkend="gio-D-Bus-Test-Scaffolding">GDBus Test Scaffolding</link>.
</para></listitem>
</itemizedlist>
</para>
</section>
<section>
<title>API comparison</title>
<table id="dbus-glib-vs-gdbus">
<title>dbus-glib APIs and their GDBus counterparts</title>
<tgroup cols="2">
<thead>
<row><entry>dbus-glib</entry><entry>GDBus</entry></row>
</thead>
<tbody>
<row><entry>#DBusGConnection</entry><entry>#GDBusConnection</entry></row>
<row><entry>#DBusGProxy</entry><entry>#GDBusProxy, #GDBusInterface - also see #GDBusObjectProxy</entry></row>
<row><entry>#DBusGObject</entry><entry>#GDBusInterfaceSkeleton, #GDBusInterface - also see #GDBusObjectSkeleton</entry></row>
<row><entry>#DBusGMethodInvocation</entry><entry>#GDBusMethodInvocation</entry></row>
<row><entry>dbus_g_bus_get()</entry><entry>g_bus_get_sync(), also see
g_bus_get()</entry></row>
<row><entry>dbus_g_proxy_new_for_name()</entry><entry>g_dbus_proxy_new_sync() and
g_dbus_proxy_new_for_bus_sync(), also see g_dbus_proxy_new()</entry></row>
<row><entry>dbus_g_proxy_add_signal()</entry><entry>not needed, use the generic #GDBusProxy::g-signal</entry></row>
<row><entry>dbus_g_proxy_connect_signal()</entry><entry>use g_signal_connect() with #GDBusProxy::g-signal</entry></row>
<row><entry>dbus_g_connection_register_g_object()</entry><entry>g_dbus_connection_register_object() - also see g_dbus_object_manager_server_export()</entry></row>
<row><entry>dbus_g_connection_unregister_g_object()</entry><entry>g_dbus_connection_unregister_object() - also see g_dbus_object_manager_server_unexport()</entry></row>
<row><entry>dbus_g_object_type_install_info()</entry><entry>introspection data is installed while registering
an object, see g_dbus_connection_register_object()</entry></row>
<row><entry>dbus_g_proxy_begin_call()</entry><entry>g_dbus_proxy_call()</entry></row>
<row><entry>dbus_g_proxy_end_call()</entry><entry>g_dbus_proxy_call_finish()</entry></row>
<row><entry>dbus_g_proxy_call()</entry><entry>g_dbus_proxy_call_sync()</entry></row>
<row><entry>dbus_g_error_domain_register()</entry><entry>g_dbus_error_register_error_domain()</entry></row>
<row><entry>dbus_g_error_has_name()</entry><entry>no direct equivalent, see g_dbus_error_get_remote_error()</entry></row>
<row><entry>dbus_g_method_return()</entry><entry>g_dbus_method_invocation_return_value()</entry></row>
<row><entry>dbus_g_method_return_error()</entry><entry>g_dbus_method_invocation_return_error() and variants</entry></row>
<row><entry>dbus_g_method_get_sender()</entry><entry>g_dbus_method_invocation_get_sender()</entry></row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Owning bus names</title>
<para>
Using dbus-glib, you typically call RequestName manually
to own a name, like in the following excerpt:
<informalexample><programlisting><![CDATA[
error = NULL;
res = dbus_g_proxy_call (system_bus_proxy,
"RequestName",
&error,
G_TYPE_STRING, NAME_TO_CLAIM,
G_TYPE_UINT, DBUS_NAME_FLAG_ALLOW_REPLACEMENT,
G_TYPE_INVALID,
G_TYPE_UINT, &result,
G_TYPE_INVALID);
if (!res)
{
if (error != NULL)
{
g_warning ("Failed to acquire %s: %s",
NAME_TO_CLAIM, error->message);
g_error_free (error);
}
else
{
g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
}
goto out;
}
if (result != DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER)
{
if (error != NULL)
{
g_warning ("Failed to acquire %s: %s",
NAME_TO_CLAIM, error->message);
g_error_free (error);
}
else
{
g_warning ("Failed to acquire %s", NAME_TO_CLAIM);
}
exit (1);
}
dbus_g_proxy_add_signal (system_bus_proxy, "NameLost",
G_TYPE_STRING, G_TYPE_INVALID);
dbus_g_proxy_connect_signal (system_bus_proxy, "NameLost",
G_CALLBACK (on_name_lost), NULL, NULL);
/* further setup ... */
]]>
</programlisting></informalexample>
</para>
<para>
While you can do things this way with GDBus too, using
g_dbus_proxy_call_sync(), it is much nicer to use the high-level API
for this:
<informalexample><programlisting><![CDATA[
static void
on_name_acquired (GDBusConnection *connection,
const gchar *name,
gpointer user_data)
{
/* further setup ... */
}
/* ... */
owner_id = g_bus_own_name (G_BUS_TYPE_SYSTEM,
NAME_TO_CLAIM,
G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT,
on_bus_acquired,
on_name_acquired,
on_name_lost,
NULL,
NULL);
g_main_loop_run (loop);
g_bus_unown_name (owner_id);
]]>
</programlisting></informalexample>
Note that g_bus_own_name() works asynchronously and requires
you to enter your mainloop to await the on_name_aquired()
callback. Also note that in order to avoid race conditions (e.g.
when your service is activated by a method call), you have to export
your manager object <emphasis>before</emphasis> acquiring the
name. The on_bus_acquired() callback is the right place to do
such preparations.
</para>
</section>
<section>
<title>Creating proxies for well-known names</title>
<para>
dbus-glib lets you create proxy objects for well-known names, like the
following example:
<informalexample><programlisting><![CDATA[
proxy = dbus_g_proxy_new_for_name (system_bus_connection,
"org.freedesktop.Accounts",
"/org/freedesktop/Accounts",
"org.freedesktop.Accounts");
]]>
</programlisting></informalexample>
For a #DBusGProxy constructed like this, method calls will be sent to
the current owner of the name, and that owner can change over time.
</para>
<para>
The same can be achieved with #GDBusProxy:
<informalexample><programlisting><![CDATA[
error = NULL;
proxy = g_dbus_proxy_new_for_bus_sync (G_BUS_TYPE_SYSTEM,
G_DBUS_PROXY_FLAGS_NONE,
NULL, /* GDBusInterfaceInfo */
"org.freedesktop.Accounts",
"/org/freedesktop/Accounts",
"org.freedesktop.Accounts",
NULL, /* GCancellable */
&error);
]]>
</programlisting></informalexample>
For an added layer of safety, you can specify what D-Bus
interface the proxy is expected to conform to by using the
#GDBusInterfaceInfo type. Additionally, #GDBusProxy loads,
caches and tracks changes to the D-Bus properties on the remote
object. It also sets up match rules so D-Bus signals from the
remote object are delivered locally.
</para>
<para>
The #GDBusProxy type normally isn't used directly - instead
proxies subclassing #GDBusProxy generated by <command><link
linkend="gdbus-codegen">gdbus-codegen</link></command> is used, see <xref linkend="gdbus-example-gdbus-codegen"/>
</para>
</section>
<section>
<title>Generating code and docs</title>
<section id="gdbus-example-gdbus-codegen">
<title>Using gdbus-codegen</title>
<para>
dbus-glib comes with <command>dbus-binding-tool</command>, which
can produce somewhat nice client- and server-side wrappers for a D-Bus interface.
With GDBus, <command><link
linkend="gdbus-codegen">gdbus-codegen</link></command> is used and like
its counterpart, it also takes D-Bus Introspection XML as input:
</para>
<example id="gdbus-example-codegen-input"><title>Example D-Bus Introspection XML</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-object-manager-example/gdbus-example-objectmanager.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: gdbus-example-objectmanager.xml</xi:fallback></xi:include></programlisting></example>
<para>
If this XML is processed like this
<informalexample><programlisting><![CDATA[
gdbus-codegen --interface-prefix org.gtk.GDBus.Example.ObjectManager. \
--generate-c-code generated-code \
--c-namespace Example \
--c-generate-object-manager \
--generate-docbook generated-docs \
gdbus-example-objectmanager.xml
]]></programlisting></informalexample>
then two files <filename>generated-code.h</filename> and
<filename>generated-code.c</filename> are
generated. Additionally, two XML files
<filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Animal</filename> and
<filename>generated-docs-org.gtk.GDBus.Example.ObjectManager.Cat</filename>
with Docbook XML are generated. For an example of what the docs look
like see <link
linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Animal">the Animal D-Bus interface documentation</link>.
and
<link
linkend="gdbus-interface-org-gtk-GDBus-Example-ObjectManager-Cat">the Cat D-Bus interface documentation</link>.
</para>
<para>
While the contents of <filename>generated-code.h</filename> and
<filename>generated-code.c</filename> are best described by the
<command><link
linkend="gdbus-codegen">gdbus-codegen</link></command> manual
page, brief examples of how this generated code can be used can be found in
<xref linkend="gdbus-example-codegen-server"/>
and <xref
linkend="gdbus-example-codegen-client"/>. Additionally, since
the generated code has 100% gtk-doc coverage, see
#ExampleAnimal, #ExampleCat, #ExampleObject and
#ExampleObjectManagerClient pages for documentation.
</para>
<example id="gdbus-example-codegen-server"><title>Server-side application using generated code</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-objectmanager-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: gdbus-example-objectmanager-server.c</xi:fallback></xi:include></programlisting></example>
<example id="gdbus-example-codegen-client"><title>Client-side application using generated code</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-objectmanager-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: gdbus-example-objectmanager-client.c</xi:fallback></xi:include></programlisting></example>
</section>
<!-- All XInclude paths are relative to the html/ directory under the build root directory -->
<xi:include href="../../../../gio/tests/gdbus-object-manager-example/objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Animal.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Animal.xml</xi:fallback></xi:include>
<xi:include href="../../../../gio/tests/gdbus-object-manager-example/objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Cat.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: objectmanager-gen-org.gtk.GDBus.Example.ObjectManager.Cat.xml</xi:fallback></xi:include>
<xi:include href="../gdbus-object-manager-example/xml/ExampleAnimal.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleAnimal.xml</xi:fallback></xi:include>
<xi:include href="../gdbus-object-manager-example/xml/ExampleCat.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleCat.xml</xi:fallback></xi:include>
<xi:include href="../gdbus-object-manager-example/xml/ExampleObject.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleObject.xml</xi:fallback></xi:include>
<xi:include href="../gdbus-object-manager-example/xml/ExampleObjectManagerClient.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT: ExampleObjectManagerClient.xml</xi:fallback></xi:include>
</section>
</chapter>

109
docs/reference/gio/migrating-gnome-vfs.md Normal file
View File

@ -0,0 +1,109 @@
Title: Migrating from GnomeVFS to GIO
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 Matthias Clasen
# Migrating from GnomeVFS to GIO
## Comparison of GnomeVFS and GIO concepts
| GnomeVFS | GIO |
|----------|-----|
| `GnomeVFSURI` | [iface@Gio.File] |
| `GnomeVFSFileInfo` | [class@Gio.FileInfo] |
| `GnomeVFSResult` | [struct@GLib.Error], with `G_IO_ERROR` values |
| `GnomeVFSHandle` & `GnomeVFSAsyncHandle` | [class@Gio.InputStream] or [class@Gio.OutputStream] |
| `GnomeVFSDirectoryHandle` | [class@Gio.FileEnumerator] |
| MIME type | content type |
| `GnomeVFSMonitor` | [class@Gio.FileMonitor] |
| `GnomeVFSVolumeMonitor` | [class@Gio.VolumeMonitor] |
| `GnomeVFSVolume` | [iface@Gio.Mount] |
| `GnomeVFSDrive` | [iface@Gio.Volume] |
| - | [iface@Gio.Drive] |
| `GnomeVFSContext` | [class@Gio.Cancellable] |
| `gnome_vfs_async_cancel()` | [method@Gio.Cancellable.cancel] |
## Trash handling
The handling of trashed files has been changed in GIO, compared to
gnome-vfs. gnome-vfs has a home-grown trash implementation that predates the
freedesktop.org [Desktop Trash
Can](http://www.freedesktop.org/wiki/Specifications/trash-spec)
specification that is implemented in GIO. The location for storing trashed
files has changed from `$HOME/.Trash` to `$HOME/.local/share/Trash` (or more
correctly `$XDG_DATA_HOME/Trash`), which means that there is a need for
migrating files that have been trashed by gnome-vfs to the new location.
In gnome-vfs, the `trash://` scheme offering a merged view of all trash
directories was implemented in Nautilus, and trash-handling applications had
to find and monitor all trash directories themselves. With GIO, the
`trash://` implementation has been moved to gvfs and applications can simply
monitor that location:
```c
static void
file_changed (GFileMonitor *file_monitor,
GFile *child,
GFile *other_file,
GFileMonitorEvent event_type,
gpointer user_data)
{
switch (event_type)
{
case G_FILE_MONITOR_EVENT_DELETED:
g_print ("'%s' removed from trash\n", g_file_get_basename (child));
break;
case G_FILE_MONITOR_EVENT_CREATED:
g_print ("'%s' added to trash\n", g_file_get_basename (child));
break;
default: ;
}
}
static void
start_monitoring_trash (void)
{
GFile *file;
GFileMonitor *monitor;
file = g_file_new_for_uri ("trash://");
monitor = g_file_monitor_directory (file, 0, NULL, NULL);
g_object_unref (file);
g_signal_connect (monitor, "changed", G_CALLBACK (file_changed), NULL);
/* ... */
}
```
GIO exposes some useful metadata about trashed files. There are
`trash::orig-path` and `trash::deletion-date` attributes. The
`standard::icon` attribute of the `trash://` itself provides a suitable icon
for displaying the trash can on the desktop. If you are using this icon,
make sure to monitor this attribute for changes, since the icon may be
updated to reflect that state of the trash can.
Moving a file to the trash is much simpler with GIO. Instead of using
`gnome_vfs_find_directory()` with `GNOME_VFS_DIRECTORY_KIND_TRASH` to find
out where to move the trashed file, just use the [`method@Gio.File.trash`]
method.
## Operations on multiple files
gnome-vfs has the dreaded `gnome_vfs_xfer_uri_list()` function which has
tons of options and offers the equivalent of `cp`, `mv`, `ln`, `mkdir` and
`rm` at the same time.
GIO offers a much simpler asynchronous task functionality instead, that lets
you schedule a function to be called in a separate thread, making sure that
updates are scheduled within the main context that created the task, so you
can update your user interface. See: [`class@Gio.Task`].
## Mime monitoring
gnome-vfs offered a way to monitor the association between mime types and
default handlers for changes, with the `GnomeVFSMIMEMonitor` object. GIO
does not offer a replacement for this functionality at this time, since we
have not found a compelling use case where `GnomeVFSMIMEMonitor` was used.
If you think you have such a use case, please [open an issue on the GLib
issue tracker](https://gitlab.gnome.org/GNOME/glib/issues/new).

133
docs/reference/gio/migrating-gnome-vfs.xml
View File

@ -1,133 +0,0 @@
<chapter>
<title>Migrating from GnomeVFS to GIO</title>
<table id="gnome-vfs-vs-gio">
<title>Comparison of GnomeVFS and GIO concepts</title>
<tgroup cols="2">
<thead>
<row><entry>GnomeVFS</entry><entry>GIO</entry></row>
</thead>
<tbody>
<row><entry>GnomeVFSURI</entry><entry>GFile</entry></row>
<row><entry>GnomeVFSFileInfo</entry><entry>GFileInfo</entry></row>
<row><entry>GnomeVFSResult</entry><entry>GError, with G_IO_ERROR values</entry></row>
<row><entry>GnomeVFSHandle &amp; GnomeVFSAsyncHandle</entry><entry>GInputStream or GOutputStream</entry></row>
<row><entry>GnomeVFSDirectoryHandle</entry><entry>GFileEnumerator</entry></row>
<row><entry>mime type</entry><entry>content type</entry></row>
<row><entry>GnomeVFSMonitor</entry><entry>GFileMonitor</entry></row>
<row><entry>GnomeVFSVolumeMonitor</entry><entry>GVolumeMonitor</entry></row>
<row><entry>GnomeVFSVolume</entry><entry>GMount</entry></row>
<row><entry>GnomeVFSDrive</entry><entry>GVolume</entry></row>
<row><entry>-</entry><entry>GDrive</entry></row>
<row><entry>GnomeVFSContext</entry><entry>GCancellable</entry></row>
<row><entry>gnome_vfs_async_cancel</entry><entry>g_cancellable_cancel</entry></row>
</tbody>
</tgroup>
</table>
<section>
<title>Trash handling</title>
<para>
The handling of trashed files has been changed in GIO, compared
to gnome-vfs. gnome-vfs has a home-grown trash implementation that
predates the freedesktop.org <ulink url="http://www.freedesktop.org/wiki/Specifications/trash-spec">Desktop Trash Can</ulink> specification
that is implemented in GIO. The location for storing trashed files
has changed from <filename>$HOME/.Trash</filename> to
<filename>$HOME/.local/share/Trash</filename> (or more correctly
<filename>$XDG_DATA_HOME/Trash</filename>), which means that
there is a need for migrating files that have been trashed by
gnome-vfs to the new location.
</para>
<para>
In gnome-vfs, the <filename>trash://</filename> scheme offering a
merged view of all trash directories was implemented in nautilus,
and trash-handling applications had to find and monitor all trash
directories themselves. With GIO, the <filename>trash://</filename>
implementation has been moved to gvfs and applications can simply
monitor that location:
</para>
<informalexample><programlisting>
static void
file_changed (GFileMonitor *file_monitor,
GFile *child,
GFile *other_file,
GFileMonitorEvent event_type,
gpointer user_data)
{
switch (event_type)
{
case G_FILE_MONITOR_EVENT_DELETED:
g_print ("'%s' removed from trash\n", g_file_get_basename (child));
break;
case G_FILE_MONITOR_EVENT_CREATED:
g_print ("'%s' added to trash\n", g_file_get_basename (child));
break;
default: ;
}
}
static void
start_monitoring_trash (void)
{
GFile *file;
GFileMonitor *monitor;
file = g_file_new_for_uri ("trash://");
monitor = g_file_monitor_directory (file, 0, NULL, NULL);
g_object_unref (file);
g_signal_connect (monitor, "changed", G_CALLBACK (file_changed), NULL);
/* ... */
}
</programlisting></informalexample>
<para>
GIO exposes some useful metadata about trashed files. There are
trash::orig-path and trash::deletion-date attributes. The
standard::icon attribute of the <filename>trash://</filename>
itself provides a suitable icon for displaying the trash can on
the desktop. If you are using this icon, make sure to monitor
this attribute for changes, since the icon may be updated to
reflect that state of the trash can.
</para>
<para>
Moving a file to the trash is much simpler with GIO. Instead of
using gnome_vfs_find_directory() with %GNOME_VFS_DIRECTORY_KIND_TRASH
to find out where to move the trashed file, just use the g_file_trash()
function.
</para>
</section>
<section>
<title>Operations on multiple files</title>
<para>
gnome-vfs has the dreaded gnome_vfs_xfer_uri_list() function which
has tons of options and offers the equivalent of cp, mv, ln, mkdir
and rm at the same time.
</para>
<para>
GIO offers a much simpler I/O scheduler functionality instead, that
lets you schedule a function to be called in a separate thread, or
if threads are not available, as an idle in the mainloop.
See g_io_scheduler_push_job().
</para>
</section>
<section>
<title>Mime monitoring</title>
<para>
gnome-vfs offered a way to monitor the association between mime types
and default handlers for changes, with the #GnomeVFSMIMEMonitor object.
GIO does not offer a replacement for this functionality at this time,
since we have not found a compelling use case where
#GnomeVFSMIMEMonitor was used. If you think you have such a use
case, please report it at
<ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>.
</para>
</section>
</chapter>

21
docs/reference/gio/migrating-posix.md Normal file
View File

@ -0,0 +1,21 @@
Title: Migrating from POSIX to GIO
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007 Matthias Clasen
# Migrating from POSIX to GIO
## Comparison of POSIX and GIO concepts
The final two entries in this table require including `gio-unix-2.0.pc` as well
as `gio-2.0.pc` in your build (or, in GIR namespace terms, `GioUnix-2.0` as well
as `Gio-2.0`).
| POSIX | GIO |
|-----------------------|-------------------------------------------------------------|
| `char *path` | [iface@Gio.File] |
| `struct stat *buf` | [class@Gio.FileInfo] |
| `struct statvfs *buf` | [class@Gio.FileInfo] |
| `int fd` | [class@Gio.InputStream] or [class@Gio.OutputStream] |
| `DIR *` | [class@Gio.FileEnumerator] |
| `fstab entry` | [`GUnixMountPoint`](../gio-unix/struct.UnixMountPoint.html) |
| `mtab entry` | [`GUnixMountEntry`](../gio-unix/struct.UnixMountEntry.html) |

27
docs/reference/gio/migrating-posix.xml
View File

@ -1,27 +0,0 @@
<part id="migrating">
<title>Migrating to GIO</title>
<chapter>
<title>Migrating from POSIX to GIO</title>
<table id="posix-vs-gio">
<title>Comparison of POSIX and GIO concepts</title>
<tgroup cols="2">
<thead>
<row><entry>POSIX</entry><entry>GIO</entry></row>
</thead>
<tbody>
<row><entry>char *path</entry><entry>GFile *file</entry></row>
<row><entry>struct stat *buf</entry><entry>GFileInfo *info</entry></row>
<row><entry>struct statvfs *buf</entry><entry>GFileInfo *info</entry></row>
<row><entry morerows="1">int fd</entry><entry>GInputStream *in</entry></row>
<row><entry>GOutputStream *out</entry></row>
<row><entry>DIR *</entry><entry>GFileEnumerator *enum</entry></row>
<row><entry>fstab entry</entry><entry>GUnixMountPoint *mount_point</entry></row>
<row><entry>mtab entry</entry><entry>GUnixMountEntry *mount_entry</entry></row>
</tbody>
</tgroup>
</table>
</chapter>
</part>

29
docs/reference/gio/networking.md Normal file
View File

@ -0,0 +1,29 @@
Title: gnetworking.h
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 Dan Winship
# gnetworking.h
The `<gio/gnetworking.h>` header can be included to get
various low-level networking-related system headers, automatically
taking care of certain portability issues for you.
This can be used, for example, if you want to call
[`setsockopt()`](man:setsockopt(2)) on a [class@Gio.Socket].
Note that while WinSock has many of the same APIs as the
traditional UNIX socket API, most of them behave at least slightly
differently (particularly with respect to error handling). If you
want your code to work under both UNIX and Windows, you will need
to take these differences into account.
Also, under GNU libc, certain non-portable functions are only visible
in the headers if you define `_GNU_SOURCE` before including them. Note
that this symbol must be defined before including any headers, or it
may not take effect.
There is one function provided specifically for initialising the networking
APIs, which needs to be called only if they are being used before GLib
initialises itself:
* [func@Gio.networking_init]

406
docs/reference/gio/overview.md Normal file
View File

@ -0,0 +1,406 @@
Title: Overview
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007, 2008, 2010, 2011, 2012, 2013 Matthias Clasen
SPDX-FileCopyrightText: 2007, 2009 Alexander Larsson
SPDX-FileCopyrightText: 2008 A. Walton
SPDX-FileCopyrightText: 2010 David Zeuthen
SPDX-FileCopyrightText: 2013 Stef Walter
SPDX-FileCopyrightText: 2015 Collabora, Ltd.
SPDX-FileCopyrightText: 2016 Colin Walters
SPDX-FileCopyrightText: 2020 Wouter Bolsterlee
SPDX-FileCopyrightText: 2022 Endless OS Foundation, LLC
# Overview
GIO is striving to provide a modern, easy-to-use VFS API that sits at the
right level in the library stack, as well as other generally useful APIs
for desktop applications (such as networking and D-Bus support). The goal
is to overcome the shortcomings of GnomeVFS and provide an API that is so
good that developers prefer it over raw POSIX calls. Among other things
that means using GObject. It also means not cloning the POSIX API, but
providing higher-level, document-centric interfaces.
The abstract file system model of GIO consists of a number of interfaces and
base classes for I/O and files:
[iface@Gio.File]
: reference to a file
[class@Gio.FileInfo]
: information about a file or filesystem
[class@Gio.FileEnumerator]
: list files in directories
[iface@Gio.Drive]
: represents a drive
[iface@Gio.Volume]
: represents a file system in an abstract way
[iface@Gio.Mount]
: represents a mounted file system
Then there is a number of stream classes, similar to the input and output
stream hierarchies that can be found in frameworks like Java:
[class@Gio.InputStream]
: read data
[class@Gio.OutputStream]
: write data
[class@Gio.IOStream]
: read and write data
[iface@Gio.Seekable]
: interface optionally implemented by streams to support seeking
There are interfaces related to applications and the types of files they
handle:
[iface@Gio.AppInfo]
: information about an installed application
[iface@Gio.Icon]
: abstract type for file and application icons
There is a framework for storing and retrieving application settings:
[class@Gio.Settings]
: stores and retrieves application settings
There is support for network programming, including connectivity monitoring,
name resolution, lowlevel socket APIs and highlevel client and server helper
classes:
[class@Gio.Socket]
: lowlevel platform independent socket object
[class@Gio.Resolver]
: asynchronous and cancellable DNS resolver
[class@Gio.SocketClient]
: high-level network client helper
[class@Gio.SocketService]
: high-level network server helper
[class@Gio.SocketConnection]
: network connection stream
[iface@Gio.NetworkMonitor]
: network connectivity monitoring
There is support for connecting to
[D-Bus](https://www.freedesktop.org/wiki/Software/dbus/), sending and receiving
messages, owning and watching bus names, and making objects available on the bus:
[class@Gio.DBusConnection]
: a D-Bus connection
[class@Gio.DBusMethodInvocation]
: for handling remote calls
[class@Gio.DBusServer]
: helper for accepting connections
[class@Gio.DBusProxy]
: proxy to access D-Bus interfaces on a remote object
Beyond these, GIO provides facilities for file monitoring, asynchronous I/O
and filename completion. In addition to the interfaces, GIO provides
implementations for the local case. Implementations for various network file
systems are provided by the GVFS package as loadable modules.
Other design choices which consciously break with the GnomeVFS design are to
move backends out-of-process, which minimizes the dependency bloat and makes
the whole system more robust. The backends are not included in GIO, but in
the separate GVFS package. The GVFS package also contains the GVFS daemon,
which spawn further mount daemons for each individual connection.
![GIO in the GTK library stack](./gvfs-overview.png)
The GIO model of I/O is stateful: if an application establishes e.g. a SFTP
connection to a server, it becomes available to all applications in the
session; the user does not have to enter his password over and over again.
One of the big advantages of putting the VFS in the GLib layer is that GTK
can directly use it, e.g. in the filechooser.
## Writing GIO applications
The information in the GLib documentation about writing GLib applications is
generally applicable when writing GIO applications.
### Threads
GDBus has its own private worker thread, so applications using GDBus have at
least 3 threads. GIO makes heavy use of the concept of a thread-default main
context to execute callbacks of asynchronous methods in the same context in
which the operation was started.
### Asynchronous Programming
Many GIO functions come in two versions: synchronous and asynchronous,
denoted by an `_async` suffix. It is important to use these appropriately:
synchronous calls should not be used from within a main loop which is shared
with other code, such as one in the application’s main thread. Synchronous
calls block until they complete, and I/O operations can take noticeable
amounts of time (even on ‘fast’ SSDs). Blocking a main loop iteration while
waiting for I/O means that other sources in the main loop will not be
dispatched, such as input and redraw handlers for the application’s UI. This
can cause the application to ‘freeze’ until I/O completes.
A few self-contained groups of functions, such as code generated by
gdbus-codegen, use a different convention: functions are asynchronous
default, and it is the synchronous version which has a `_sync` suffix. Aside
from naming differences, they should be treated the same way as functions
following the normal convention above.
The asynchronous (`_async`) versions of functions return control to the
caller immediately, after scheduling the I/O in the kernel and adding a
callback for it to the main loop. This callback will be invoked when the
operation has completed. From the callback, the paired `_finish` function
should be called to retrieve the return value of the I/O operation, and any
errors which occurred. For more information on using and implementing
asynchronous functions, see [iface@Gio.AsyncResult] and [class@Gio.Task].
By starting multiple asynchronous operations in succession, they will be
executed in parallel (up to an arbitrary limit imposed by GIO’s internal
worker thread pool).
The synchronous versions of functions can be used early in application
startup when there is no main loop to block, for example to load initial
configuration files. They can also be used for I/O on files which are
guaranteed to be small and on the local disk. Note that the user’s home
directory is not guaranteed to be on the local disk. Security
When your program needs to carry out some privileged operation (say, create
a new user account), there are various ways in which you can go about this:
- Implement a daemon that offers the privileged operation. A convenient way
to do this is as a D-Bus system-bus service. The daemon will probably need
ways to check the identity and authorization of the caller before
executing the operation.
[polkit](https://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html)
is a framework that allows this.
- Use a small helper that is executed with elevated privileges via pkexec.
[`pkexec`](https://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html)
is a small program launcher that is part of polkit.
- Use a small helper that is executed with elevated privileges by being suid
root.
None of these approaches is the clear winner, they all have their advantages
and disadvantages.
When writing code that runs with elevated privileges, it is important to
follow some basic rules of secure programming. David Wheeler has an
excellent book on this topic,
[Secure Programming for Linux and Unix HOWTO](https://dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html).
When using GIO in code that runs with elevated privileges, you have to be
careful. GIO has extension points whose implementations get loaded from
modules (executable code in shared objects), which could allow an attacker
to sneak his own code into your application by tricking it into loading the
code as a module. However, GIO will never load modules from your home
directory except when explicitly asked to do so via an environment variable.
In most cases, your helper program should be so small that you don't need
GIO, whose APIs are largely designed to support full-blown desktop
applications. If you can't resist the convenience of these APIs, here are
some steps you should take:
- Clear the environment, e.g. using the `clearenv()` function. David Wheeler
has a good
[explanation](https://dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html)
for why it is important to sanitize the environment. See the section on
running GIO applications for a list of all environment variables affecting
GIO. In particular, `PATH` (used to locate binaries), `GIO_EXTRA_MODULES`
(used to locate loadable modules) and `DBUS_{SYSTEM,SESSION}_BUS_ADDRESS`
(used to locate the D-Bus system and session bus) are important.
- Don't use GVfs, by setting `GIO_USE_VFS=local` in the environment. The
reason to avoid GVfs in security-sensitive programs is that it uses many
libraries which have not necessarily been audited for security problems.
Gvfs is also heavily distributed and relies on a session bus to be
present.
## Compiling GIO applications
GIO comes with a `gio-2.0.pc` file that you should use together with
pkg-config to obtain the necessary information about header files and
libraries. See the pkg-config man page or the GLib documentation for more
information on how to use pkg-config to compile your application.
If you are using GIO on UNIX-like systems, you may want to use UNIX-specific
GIO interfaces such as `GUnixInputStream`, `GUnixOutputStream`, `GUnixMount`
or `GDesktopAppInfo`. To do so, use the `gio-unix-2.0.pc` file as well as
`gio-2.0.pc` (or, in GIR namespace terms, `GioUnix-2.0` as well as `Gio-2.0`).
## Running GIO applications
GIO inspects a few environment variables in addition to the ones used by GLib.
- `XDG_DATA_HOME`, `XDG_DATA_DIRS`. GIO uses these environment variables to
locate MIME information. For more information, see the
[Shared MIME-info Database](https://specifications.freedesktop.org/shared-mime-info-spec/latest/)
and the [Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/).
- `GVFS_DISABLE_FUSE`. This variable can be set to keep Gvfs from starting
the fuse backend, which may be unwanted or unnecessary in certain
situations.
- `GIO_USE_VFS`. This environment variable can be set to the name of a GVfs
implementation to override the default for debugging purposes. The GVfs
implementation for local files that is included in GIO has the name
"local", the implementation in the gvfs module has the name "gvfs". Most
commonly, system software will set this to "local" to avoid having `GFile`
APIs perform unnecessary D-Bus calls. The special value help can be used
to print a list of available implementations to standard output.
The following environment variables are only useful for debugging GIO itself
or modules that it loads. They should not be set in a production
environment.
- `GIO_USE_FILE_MONITOR`. This variable can be set to the name of a
GFileMonitor implementation to override the default for debugging
purposes. The GFileMonitor implementation for local files that is included
in GIO on Linux has the name "inotify", others that are built are built as
modules (depending on the platform) are called "fam" and "fen". The
special value help can be used to print a list of available
implementations to standard output.
- `GIO_USE_VOLUME_MONITOR`. This variable can be set to the name of a
GVolumeMonitor implementation to override the default for debugging
purposes. The GVolumeMonitor implementation for local files that is
included in GIO has the name "unix", the udisks2-based implementation in
the gvfs module has the name "udisks2". The special value help can be used
to print a list of available implementations to standard output.
- `GIO_USE_TLS`. This variable can be set to the name of a GTlsBackend
implementation to override the default for debugging purposes. GIO does
not include a GTlsBackend implementation, the gnutls-based implementation
in the glib-networking module has the name "gnutls". The special value
help can be used to print a list of available implementations to standard
output.
- `GIO_USE_PORTALS`. This variable can be set to override detection of portals
and force them to be used to provide various bits of GIO functionality, for
testing and debugging. This variable is not intended to be used in production.
- `GIO_MODULE_DIR`. When this environment variable is set to a path, GIO
will load modules from this alternate directory instead of the directory
built into GIO. This is useful when running tests, for example. This
environment variable is ignored when running in a setuid program.
- `GIO_EXTRA_MODULES`. When this environment variable is set to a path, or
a set of paths separated by a colon, GIO will attempt to load additional
modules from within the path. This environment variable is ignored when
running in a setuid program.
- `GSETTINGS_BACKEND`. This variable can be set to the name of a
GSettingsBackend implementation to override the default for debugging
purposes. The memory-based implementation that is included in GIO has the
name "memory", the one in dconf has the name "dconf". The special value
help can be used to print a list of available implementations to standard
output.
- `GSETTINGS_SCHEMA_DIR`. This variable can be set to the names of
directories to consider when looking for compiled schemas for GSettings,
in addition to the `glib-2.0/schemas` subdirectories of the XDG system
data dirs. To specify multiple directories, use `G_SEARCHPATH_SEPARATOR_S`
as a separator.
- `DBUS_SYSTEM_BUS_ADDRESS`. This variable is consulted to find the address
of the D-Bus system bus. For the format of D-Bus addresses, see the
[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
Setting this variable overrides platform-specific ways of determining the
system bus address.
- `DBUS_SESSION_BUS_ADDRESS`. This variable is consulted to find the
address of the D-Bus session bus. Setting this variable overrides
platform-specific ways of determining the session bus address.
- `DBUS_STARTER_BUS_TYPE`. This variable is consulted to find out the
'starter' bus for an application that has been started via D-Bus
activation. The possible values are 'system' or 'session'.
- `G_DBUS_DEBUG`. This variable can be set to a list of debug options,
which cause GLib to print out different types of debugging information
when using the D-Bus routines.
- `transport`: Show IO activity (e.g. reads and writes)
- `message`: Show all sent and received D-Bus messages
- `payload`: Show payload for all sent and received D-Bus messages (implies
message)
- `call`: Trace `g_dbus_connection_call()` and
`g_dbus_connection_call_sync()` API usage
- `signal`: Show when a D-Bus signal is received
- `incoming`: Show when an incoming D-Bus method call is received
- `return`: Show when a reply is returned via the GDBusMethodInvocation API
- `emission`: Trace `g_dbus_connection_emit_signal()` API usage
- `authentication`: Show information about connection authentication
- `address`: Show information about D-Bus address lookups and autolaunching
- `all`: Turn on all debug options
- `help`: Print a list of supported options to the standard output
- `G_DBUS_COOKIE_SHA1_KEYRING_DIR`. Can be used to override the directory
used to store the keyring used in the `DBUS_COOKIE_SHA1` authentication
mechanism. Normally the directory used is `.dbus-keyrings` in the user's
home directory.
- `G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION`. If set, the
permissions of the directory used to store the keyring used in the
`DBUS_COOKIE_SHA1` authentication mechanism won't be checked. Normally the
directory must be readable only by the user.
## Extending GIO
A lot of the functionality that is accessible through GIO is implemented in
loadable modules, and modules provide a convenient way to extend GIO. In
addition to the [`class@Gio.IOModule`] API which supports writing such modules, GIO has a
mechanism to define extension points, and register implementations thereof,
see [`struct@Gio.IOExtensionPoint`].
The following extension points are currently defined by GIO:
- `G_VFS_EXTENSION_POINT_NAME`. Allows to override the functionality of the
GVfs class. Implementations of this extension point must be derived from
GVfs. GIO uses the implementation with the highest priority that is
active, see `g_vfs_is_active()`. GIO implements this extension point for
local files, gvfs contains an implementation that supports all the
backends in gvfs.
- `G_VOLUME_MONITOR_EXTENSION_POINT_NAME`. Allows to add more volume
monitors. Implementations of this extension point must be derived from
GVolumeMonitor. GIO uses all registered extensions. gvfs contains an
implementation that works together with the GVfs implementation in gvfs.
- `G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME`. Allows to override the
'native' volume monitor. Implementations of this extension point must be
derived from GNativeVolumeMonitor. GIO uses the implementation with the
highest priority that is supported, as determined by the `is_supported()`
vfunc in GVolumeMonitorClass. GIO implements this extension point for
local mounts, gvfs contains a udisks2-based implementation.
- `G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME`. Allows to override the file
monitor implementation for local files. Implementations of this extension
point must be derived from GLocalFileMonitor. GIO uses the implementation
with the highest priority that is supported, as determined by the
`is_supported()` vfunc in GLocalFileMonitorClass. GIO uses this extension
point internally, to switch between its fam-based and inotify-based file
monitoring implementations.
- `G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME`. Allows to override the
directory monitor implementation for local files. Implementations of this
extension point must be derived from GLocalDirectoryMonitor. GIO uses the
implementation with the highest priority that is supported, as determined
by the `is_supported()` vfunc in GLocalDirectoryMonitorClass. GIO uses
this extension point internally, to switch between its fam-based and
inotify-based directory monitoring implementations.
- `G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME`. Unix-only. Allows to
provide a way to associate default handlers with URI schemes.
Implementations of this extension point must implement the
GDesktopAppInfoLookup interface. GIO uses the implementation with the
highest priority. This extension point has been discontinued in GLib 2.28.
It is still available to keep API and ABI stability, but GIO is no longer
using it for default handlers. Instead, the mime handler mechanism is
used, together with x-scheme-handler pseudo-mimetypes.
- `G_SETTINGS_BACKEND_EXTENSION_POINT_NAME`. Allows to provide an
alternative storage for GSettings. Implementations of this extension point
must derive from the GSettingsBackend type. GIO contains a keyfile-based
implementation of this extension point, another one is provided by dconf.
- `G_PROXY_EXTENSION_POINT_NAME`. Allows to provide implementations for
network proxying. Implementations of this extension point must provide the
GProxy interface, and must be named after the network protocol they are
proxying. glib-networking contains an implementation of this extension
point based on libproxy.
- `G_TLS_BACKEND_EXTENSION_POINT_NAME`. Allows to provide implementations
for TLS support. Implementations of this extension point must implement
the GTlsBackend interface. glib-networking contains an implementation of
this extension point.
- `G_NETWORK_MONITOR_EXTENSION_POINT_NAME`. Allows to provide
implementations for network connectivity monitoring. Implementations of
this extension point must implement the GNetworkMonitorInterface
interface. GIO contains an implementation of this extension point that is
using the netlink interface of the Linux kernel.

745
docs/reference/gio/overview.xml
View File

@ -1,745 +0,0 @@
<part>
<title>GIO Overview</title>
<chapter>
<title>Introduction</title>
<para>
GIO is striving to provide a modern, easy-to-use VFS API that sits
at the right level in the library stack, as well as other generally
useful APIs for desktop applications (such as networking and
D-Bus support). The goal is to overcome the shortcomings of GnomeVFS
and provide an API that is so good that developers prefer it over raw
POSIX calls. Among other things that means using GObject. It also means
not cloning the POSIX API, but providing higher-level, document-centric
interfaces.
</para>
<para>
The abstract file system model of GIO consists of a number of
interfaces and base classes for I/O and files:
<variablelist>
<varlistentry>
<term>GFile</term>
<listitem><para>reference to a file</para></listitem>
</varlistentry>
<varlistentry>
<term>GFileInfo</term>
<listitem><para>information about a file or filesystem</para></listitem>
</varlistentry>
<varlistentry>
<term>GFileEnumerator</term>
<listitem><para>list files in directories</para></listitem>
</varlistentry>
<varlistentry>
<term>GDrive</term>
<listitem><para>represents a drive</para></listitem>
</varlistentry>
<varlistentry>
<term>GVolume</term>
<listitem><para>represents a file system in an abstract way</para></listitem>
</varlistentry>
<varlistentry>
<term>GMount</term>
<listitem><para>represents a mounted file system</para></listitem>
</varlistentry>
</variablelist>
Then there is a number of stream classes, similar to the input and
output stream hierarchies that can be found in frameworks like Java:
<variablelist>
<varlistentry>
<term>GInputStream</term>
<listitem><para>read data</para></listitem>
</varlistentry>
<varlistentry>
<term>GOutputStream</term>
<listitem><para>write data</para></listitem>
</varlistentry>
<varlistentry>
<term>GIOStream</term>
<listitem><para>read and write data</para></listitem>
</varlistentry>
<varlistentry>
<term>GSeekable</term>
<listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
</varlistentry>
</variablelist>
There are interfaces related to applications and the types
of files they handle:
<variablelist>
<varlistentry>
<term>GAppInfo</term>
<listitem><para>information about an installed application</para></listitem>
</varlistentry>
<varlistentry>
<term>GIcon</term>
<listitem><para>abstract type for file and application icons</para></listitem>
</varlistentry>
</variablelist>
There is a framework for storing and retrieving application settings:
<variablelist>
<varlistentry>
<term>GSettings</term>
<listitem><para>stores and retrieves application settings</para></listitem>
</varlistentry>
</variablelist>
There is support for network programming, including connectivity monitoring,
name resolution, lowlevel socket APIs and highlevel client and server
helper classes:
<variablelist>
<varlistentry>
<term>GSocket</term>
<listitem><para>lowlevel platform independent socket object</para></listitem>
</varlistentry>
<varlistentry>
<term>GResolver</term>
<listitem><para>asynchronous and cancellable DNS resolver</para></listitem>
</varlistentry>
<varlistentry>
<term>GSocketClient</term>
<listitem><para>high-level network client helper</para></listitem>
</varlistentry>
<varlistentry>
<term>GSocketService</term>
<listitem><para>high-level network server helper</para></listitem>
</varlistentry>
<varlistentry>
<term>GSocketConnection</term>
<listitem><para>network connection stream</para></listitem>
</varlistentry>
<varlistentry>
<term>GNetworkMonitor</term>
<listitem><para>network connectivity monitoring</para></listitem>
</varlistentry>
</variablelist>
There is support for connecting to <ulink url="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
sending and receiving messages, owning and watching bus names,
and making objects available on the bus:
<variablelist>
<varlistentry>
<term>GDBusConnection</term>
<listitem><para>a D-Bus connection</para></listitem>
</varlistentry>
<varlistentry>
<term>GDBusMethodInvocation</term>
<listitem><para>for handling remote calls</para></listitem>
</varlistentry>
<varlistentry>
<term>GDBusServer</term>
<listitem><para>helper for accepting connections</para></listitem>
</varlistentry>
<varlistentry>
<term>GDBusProxy</term>
<listitem><para>proxy to access D-Bus interfaces on a remote object</para></listitem>
</varlistentry>
</variablelist>
Beyond these, GIO provides facilities for file monitoring,
asynchronous I/O and filename completion. In addition to the
interfaces, GIO provides implementations for the local case.
Implementations for various network file systems are provided
by the GVFS package as loadable modules.
</para>
<para>
Other design choices which consciously break with the GnomeVFS
design are to move backends out-of-process, which minimizes the
dependency bloat and makes the whole system more robust. The backends
are not included in GIO, but in the separate GVFS package. The GVFS
package also contains the GVFS daemon, which spawn further mount
daemons for each individual connection.
</para>
<figure id="gvfs-overview">
<title>GIO in the GTK library stack</title>
<graphic fileref="gvfs-overview.png" format="PNG"></graphic>
</figure>
<para>
The GIO model of I/O is stateful: if an application establishes e.g.
a SFTP connection to a server, it becomes available to all applications
in the session; the user does not have to enter their password over
and over again.
</para>
<para>
One of the big advantages of putting the VFS in the GLib layer
is that GTK can directly use it, e.g. in the filechooser.
</para>
</chapter>
<chapter>
<title>Writing GIO applications</title>
<para>
The information in the GLib <ulink url="http://developer.gnome.org/glib/stable/glib-programming.html">documentation</ulink> about writing GLib
applications is generally applicable when writing GIO applications.
</para>
<simplesect><title>Threads</title>
<para>
GDBus has its own private worker thread, so applications using
GDBus have at least 3 threads. GIO makes heavy use of the concept
of a <link linkend="g-main-context-push-thread-default">thread-default
main context</link> to execute callbacks of asynchronous
methods in the same context in which the operation was started.
</para>
</simplesect>
<simplesect id="async-programming"><title>Asynchronous Programming</title>
<para>
Many GIO functions come in two versions: synchronous and asynchronous,
denoted by an <code>_async</code> suffix. It is important to use these
appropriately: synchronous calls should not be used from
within a main loop which is shared with other code, such as one in the
application’s main thread. Synchronous calls block until they complete,
and I/O operations can take noticeable amounts of time (even on ‘fast’
SSDs). Blocking a main loop iteration while waiting for I/O means that
other sources in the main loop will not be dispatched, such as input and
redraw handlers for the application’s UI. This can cause the application
to ‘freeze’ until I/O completes.
</para>
<para>
A few self-contained groups of functions, such as code generated by
<link linkend="gdbus-codegen"><application>gdbus-codegen</application></link>,
use a different convention: functions are asynchronous default, and it is
the <emphasis>synchronous</emphasis> version which has a
<code>_sync</code>
suffix. Aside from naming differences, they should be treated the same
way as functions following the normal convention above.
</para>
<para>
The asynchronous (<code>_async</code>) versions of functions return
control to the caller immediately, after scheduling the I/O in the kernel
and adding a callback for it to the main loop. This callback will be
invoked when the operation has completed. From the callback, the paired
<code>_finish</code> function should be called to retrieve the return
value of the I/O operation, and any errors which occurred. For more
information on using and implementing asynchronous functions, see
<link linkend="GAsyncResult.description"><type>GAsyncResult</type></link>
and <link linkend="GTask.description"><type>GTask</type></link>.
</para>
<para>
By starting multiple asynchronous operations in succession, they will be
executed in parallel (up to an arbitrary limit imposed by GIO’s internal
worker thread pool).
</para>
<para>
The synchronous versions of functions can be used early in application
startup when there is no main loop to block, for example to load initial
configuration files. They can also be used for I/O on files which are
guaranteed to be small and on the local disk. Note that the user’s home
directory is not guaranteed to be on the local disk.
</para>
</simplesect>
<simplesect><title>Security</title>
<para>
When your program needs to carry out some privileged operation (say,
create a new user account), there are various ways in which you can go
about this:
<itemizedlist>
<listitem><para>
Implement a daemon that offers the privileged operation. A convenient
way to do this is as a D-Bus system-bus service. The daemon will probably
need ways to check the identity and authorization of the caller before
executing the operation. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">polkit</ulink> is a framework that allows this.
</para></listitem>
<listitem><para>
Use a small helper that is executed with elevated privileges via
pkexec. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html">pkexec</ulink> is a small program launcher that is part of polkit.
</para></listitem>
<listitem><para>
Use a small helper that is executed with elevated privileges by
being suid root.
</para></listitem>
</itemizedlist>
None of these approaches is the clear winner, they all have their
advantages and disadvantages.
</para>
<para>
When writing code that runs with elevated privileges, it is important
to follow some basic rules of secure programming. David Wheeler has an
excellent book on this topic,
<ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
</para>
<para>
When using GIO in code that runs with elevated privileges, you have to
be careful. GIO has extension points whose implementations get loaded
from modules (executable code in shared objects), which could allow
an attacker to sneak their own code into your application by tricking it
into loading the code as a module. However, GIO will never load modules
from your home directory except when explicitly asked to do so via an
environment variable.
</para>
<para>
In most cases, your helper program should be so small that you don't
need GIO, whose APIs are largely designed to support full-blown desktop
applications. If you can't resist the convenience of these APIs, here
are some steps you should take:
<itemizedlist>
<listitem><para>
Clear the environment, e.g. using the <function>clearenv()</function>
function.
David Wheeler has a good <ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html">explanation</ulink> for why it is
important to sanitize the environment.
See <xref linkend="running-gio-apps"/>
for a list of all environment variables affecting GIO. In particular,
<envar>PATH</envar> (used to locate binaries), <envar>GIO_EXTRA_MODULES</envar> (used to locate loadable modules) and <envar>DBUS_{SYSTEM,SESSION}_BUS_ADDRESS</envar> (used to locate the D-Bus system and session bus) are important.
</para></listitem>
<listitem><para>
Don't use GVfs, by setting <envar>GIO_USE_VFS=local</envar> in the environment.
The reason to avoid GVfs in security-sensitive programs is that it uses
many libraries which have not necessarily been audited for security problems.
Gvfs is also heavily distributed and relies on a session bus to be present.
</para></listitem>
</itemizedlist>
</para>
</simplesect>
</chapter>
<chapter>
<title>Compiling GIO applications</title>
<para>
GIO comes with a <filename>gio-2.0.pc</filename> file that you
should use together with <literal>pkg-config</literal> to obtain
the necessary information about header files and libraries. See
the <literal>pkg-config</literal> man page or the GLib documentation
for more information on how to use <literal>pkg-config</literal>
to compile your application.
</para>
<para>
If you are using GIO on UNIX-like systems, you may want to use
UNIX-specific GIO interfaces such as #GUnixInputStream,
#GUnixOutputStream, #GUnixMount or #GDesktopAppInfo.
To do so, use the <filename>gio-unix-2.0.pc</filename> file
instead of <filename>gio-2.0.pc</filename>
</para>
</chapter>
<chapter id="running-gio-apps">
<title>Running GIO applications</title>
<para>
GIO inspects a few environment variables in addition to the
ones used by GLib.
</para>
<formalpara>
<title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
<para>
GIO uses these environment variables to locate MIME information.
For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
</para>
</formalpara>
<formalpara>
<title><envar>GVFS_DISABLE_FUSE</envar></title>
<para>
This variable can be set to keep #Gvfs from starting the fuse backend,
which may be unwanted or unnecessary in certain situations.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_USE_VFS</envar></title>
<para>
This environment variable can be set to the name of a #GVfs
implementation to override the default for debugging purposes.
The #GVfs implementation for local files that is included in GIO
has the name "local", the implementation in the gvfs module has
the name "gvfs". Most commonly, system software will set this to "local"
to avoid having `GFile` APIs perform unnecessary D-Bus calls.
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<para>
The following environment variables are only useful for debugging
GIO itself or modules that it loads. They should not be set in a
production environment.
</para>
<formalpara>
<title><envar>GIO_USE_FILE_MONITOR</envar></title>
<para>
This variable can be set to the name of a #GFileMonitor
implementation to override the default for debugging purposes.
The #GFileMonitor implementation for local files that is included
in GIO on Linux has the name <literal>inotify</literal>, others that are built
are built as modules (depending on the platform) are called
<literal>kqueue</literal> and <literal>win32filemonitor</literal>.
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
<para>
This variable can be set to the name of a #GVolumeMonitor
implementation to override the default for debugging purposes.
The #GVolumeMonitor implementation for local files that is included
in GIO has the name "unix", the udisks2-based implementation in the
gvfs module has the name "udisks2".
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_USE_TLS</envar></title>
<para>
This variable can be set to the name of a #GTlsBackend
implementation to override the default for debugging purposes.
GIO does not include a #GTlsBackend implementation, the gnutls-based
implementation in the glib-networking module has the name "gnutls".
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_MODULE_DIR</envar></title>
<para>
When this environment variable is set to a path, GIO will load
modules from this alternate directory instead of the directory
built into GIO. This is useful when running tests, for example.
</para>
<para>
This environment variable is ignored when running in a setuid program.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_EXTRA_MODULES</envar></title>
<para>
When this environment variable is set to a path, or a set of
paths separated by a colon, GIO will attempt to load
additional modules from within the path.
</para>
<para>
This environment variable is ignored when running in a setuid program.
</para>
</formalpara>
<formalpara>
<title><envar>GSETTINGS_BACKEND</envar></title>
<para>
This variable can be set to the name of a #GSettingsBackend
implementation to override the default for debugging purposes.
The memory-based implementation that is included in GIO has
the name "memory", the one in dconf has the name "dconf".
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GSETTINGS_SCHEMA_DIR</envar></title>
<para>
This variable can be set to the names of directories to consider when looking for compiled schemas for #GSettings,
in addition to the <filename>glib-2.0/schemas</filename>
subdirectories of the XDG system data dirs. To specify multiple directories, use <constant>G_SEARCHPATH_SEPARATOR_S</constant> as a separator.
</para>
</formalpara>
<formalpara>
<title><envar>DBUS_SYSTEM_BUS_ADDRESS</envar></title>
<para>
This variable is consulted to find the address of the D-Bus system
bus. For the format of D-Bus addresses, see the D-Bus
<ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">specification</ulink>.
</para>
<para>
Setting this variable overrides platform-specific ways of determining
the system bus address.
</para>
</formalpara>
<formalpara>
<title><envar>DBUS_SESSION_BUS_ADDRESS</envar></title>
<para>
This variable is consulted to find the address of the D-Bus session bus.
</para>
<para>
Setting this variable overrides platform-specific ways of determining
the session bus address.
</para>
</formalpara>
<formalpara>
<title><envar>DBUS_STARTER_BUS_TYPE</envar></title>
<para>
This variable is consulted to find out the 'starter' bus for an
application that has been started via D-Bus activation. The possible
values are 'system' or 'session'.
</para>
</formalpara>
<formalpara>
<title><envar>G_DBUS_DEBUG</envar></title>
<para>
This variable can be set to a list of debug options, which
cause GLib to print out different types of debugging
information when using the D-Bus routines.
<variablelist>
<varlistentry>
<term>transport</term>
<listitem><para>Show IO activity (e.g. reads and writes)</para></listitem>
</varlistentry>
<varlistentry>
<term>message</term>
<listitem><para>Show all sent and received D-Bus messages</para></listitem>
</varlistentry>
<varlistentry>
<term>payload</term>
<listitem><para>Show payload for all sent and received D-Bus messages (implies message)</para></listitem>
</varlistentry>
<varlistentry>
<term>call</term>
<listitem><para>Trace g_dbus_connection_call() and g_dbus_connection_call_sync() API usage</para></listitem>
</varlistentry>
<varlistentry>
<term>signal</term>
<listitem><para>Show when a D-Bus signal is received</para></listitem>
</varlistentry>
<varlistentry>
<term>incoming</term>
<listitem><para>Show when an incoming D-Bus method call is received</para></listitem>
</varlistentry>
<varlistentry>
<term>return</term>
<listitem><para>Show when a reply is returned via the #GDBusMethodInvocation API</para></listitem>
</varlistentry>
<varlistentry>
<term>emission</term>
<listitem><para>Trace g_dbus_connection_emit_signal() API usage</para></listitem>
</varlistentry>
<varlistentry>
<term>authentication</term>
<listitem><para>Show information about connection authentication</para></listitem>
</varlistentry>
<varlistentry>
<term>address</term>
<listitem><para>Show information about D-Bus address lookups and autolaunching</para></listitem>
</varlistentry>
</variablelist>
The special value <literal>all</literal> can be used to turn
on all debug options. The special value
<literal>help</literal> can be used to print a list of
supported options to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
<para>
Can be used to override the directory used to store the
keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
authentication mechanism. Normally the directory used is
<filename>.dbus-keyrings</filename> in the user's home
directory.
</para>
</formalpara>
<formalpara>
<title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
<para>
If set, the permissions of the directory used to store the
keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
authentication mechanism won't be checked. Normally the
directory must be readable only by the user.
</para>
</formalpara>
</chapter>
<chapter id="extending-gio">
<title>Extending GIO</title>
<para>
A lot of the functionality that is accessible through GIO
is implemented in loadable modules, and modules provide a convenient
way to extend GIO. In addition to the #GIOModule API which supports
writing such modules, GIO has a mechanism to define extension points,
and register implementations thereof, see #GIOExtensionPoint.
</para>
<para>
The following extension points are currently defined by GIO:
</para>
<formalpara>
<title>G_VFS_EXTENSION_POINT_NAME</title>
<para>
Allows to override the functionality of the #GVfs class.
Implementations of this extension point must be derived from #GVfs.
GIO uses the implementation with the highest priority that is active,
see g_vfs_is_active().
</para>
<para>
GIO implements this extension point for local files, gvfs contains
an implementation that supports all the backends in gvfs.
</para>
</formalpara>
<formalpara>
<title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to add more volume monitors.
Implementations of this extension point must be derived from
#GVolumeMonitor. GIO uses all registered extensions.
</para>
<para>
gvfs contains an implementation that works together with the #GVfs
implementation in gvfs.
</para>
</formalpara>
<formalpara>
<title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to override the 'native' volume monitor.
Implementations of this extension point must be derived from
#GNativeVolumeMonitor. GIO uses the implementation with
the highest priority that is supported, as determined by the
is_supported() vfunc in #GVolumeMonitorClass.
</para>
<para>
GIO implements this extension point for local mounts,
gvfs contains a udisks2-based implementation.
</para>
</formalpara>
<formalpara>
<title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to override the file monitor implementation for
local files. Implementations of this extension point must
be derived from #GLocalFileMonitor. GIO uses the implementation
with the highest priority that is supported, as determined by the
is_supported() vfunc in #GLocalFileMonitorClass.
</para>
<para>
GIO uses this extension point internally, to switch between
its kqueue-based and inotify-based file monitoring implementations.
</para>
</formalpara>
<formalpara>
<title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
<para>
Unix-only. Allows to provide a way to associate default handlers
with URI schemes. Implementations of this extension point must
implement the #GDesktopAppInfoLookup interface. GIO uses the
implementation with the highest priority.
</para>
<para>
This extension point has been discontinued in GLib 2.28. It is
still available to keep API and ABI stability, but GIO is no
longer using it for default handlers. Instead, the mime handler
mechanism is used, together with x-scheme-handler pseudo-mimetypes.
</para>
</formalpara>
<formalpara>
<title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
<para>
Allows to provide an alternative storage for #GSettings.
Implementations of this extension point must derive from the
#GSettingsBackend type. GIO contains a keyfile-based
implementation of this extension point, another one is provided
by dconf.
</para>
</formalpara>
<formalpara>
<title>G_PROXY_EXTENSION_POINT_NAME</title>
<para>
Allows to provide implementations for network proxying.
Implementations of this extension point must provide the
#GProxy interface, and must be named after the network
protocol they are proxying.
</para>
<para>
glib-networking contains an implementation of this extension
point based on libproxy.
</para>
</formalpara>
<formalpara>
<title>G_TLS_BACKEND_EXTENSION_POINT_NAME</title>
<para>
Allows to provide implementations for TLS support.
Implementations of this extension point must implement
the #GTlsBackend interface.
</para>
<para>
glib-networking contains an implementation of this extension
point.
</para>
</formalpara>
<formalpara>
<title>G_NETWORK_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to provide implementations for network connectivity
monitoring.
Implementations of this extension point must implement
the #GNetworkMonitorInterface interface.
</para>
<para>
GIO contains an implementation of this extension point
that is using the netlink interface of the Linux kernel.
</para>
</formalpara>
</chapter>
</part>

15
docs/reference/gio/pollable-utils.md Normal file
View File

@ -0,0 +1,15 @@
Title: Pollable Utility Functions
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2012 Dan Winship
# Pollable Utility Functions
Utility functions for [iface@Gio.PollableInputStream] and
[iface@Gio.PollableOutputStream] implementations.
* [func@Gio.pollable_source_new]
* [func@Gio.pollable_source_new_full]
* [func@Gio.pollable_stream_read]
* [func@Gio.pollable_stream_write]
* [func@Gio.pollable_stream_write_all]

37
docs/reference/gio/tls-overview.md Normal file
View File

@ -0,0 +1,37 @@
Title: TLS Overview
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 Dan Winship
SPDX-FileCopyrightText: 2015 Collabora, Ltd.
# TLS Overview
[class@Gio.TlsConnection] and related classes provide TLS (Transport Layer
Security, previously known as SSL, Secure Sockets Layer) support for GIO-based
network streams.
[iface@Gio.DtlsConnection] and related classes provide DTLS (Datagram TLS)
support for GIO-based network sockets, using the [iface@Gio.DatagramBased]
interface. The TLS and DTLS APIs are almost identical, except TLS is
stream-based and DTLS is datagram-based. They share certificate and backend
infrastructure.
In the simplest case, for a client TLS connection, you can just set the
[property@Gio.SocketClient:tls] flag on a [class@Gio.SocketClient], and then any
connections created by that client will have TLS negotiated automatically, using
appropriate default settings, and rejecting any invalid or self-signed
certificates (unless you change that default by setting the
[property@Gio.SocketClient:tls-validation-flags] property). The returned object
will be a [class@Gio.TcpWrapperConnection], which wraps the underlying
[iface@Gio.TlsClientConnection].
For greater control, you can create your own [iface@Gio.TlsClientConnection],
wrapping a [class@Gio.SocketConnection] (or an arbitrary [class@Gio.IOStream]
with pollable input and output streams) and then connect to its signals,
such as [signal@Gio.TlsConnection::accept-certificate], before starting the
handshake.
Server-side TLS is similar, using [iface@Gio.TlsServerConnection]. At the
moment, there is no support for automatically wrapping server-side
connections in the way [class@Gio.SocketClient] does for client-side
connections.

35
docs/reference/gio/unix-mounts.md Normal file
View File

@ -0,0 +1,35 @@
Title: UNIX Mounts
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007 Andrew Walton
SPDX-FileCopyrightText: 2008 Matthias Clasen
# UNIX Mounts
Routines for managing mounted UNIX mount points and paths.
Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
file or the `GioUnix-2.0` GIR namespace when using it.
There are three main classes:
* [struct@GioUnix.MountEntry]
* [struct@GioUnix.MountPoint]
* [class@GioUnix.MountMonitor]
Various helper functions for querying mounts:
* [func@GioUnix.mount_points_get]
* [func@GioUnix.MountPoint.at]
* [func@GioUnix.mounts_get]
* [func@GioUnix.mount_at]
* [func@GioUnix.mount_for]
* [func@GioUnix.mounts_changed_since]
* [func@GioUnix.mount_points_changed_since]
And several helper functions for checking the type of a mount or path:
* [func@GioUnix.is_mount_path_system_internal]
* [func@GioUnix.is_system_fs_type]
* [func@GioUnix.is_system_device_path]

1
docs/reference/gio/version.xml.in
View File

@ -1 +0,0 @@
@VERSION@

8
docs/reference/gio/xml/gtkdocentities.ent.in
View File

@ -1,8 +0,0 @@
<!ENTITY package "@PACKAGE@">
<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
<!ENTITY package_name "@PACKAGE_NAME@">
<!ENTITY package_string "@PACKAGE_STRING@">
<!ENTITY package_tarname "@PACKAGE_TARNAME@">
<!ENTITY package_url "@PACKAGE_URL@">
<!ENTITY package_version "@PACKAGE_VERSION@">
<!ENTITY package_api_version "@PACKAGE_API_VERSION@">

14
docs/reference/gio/xml/meson.build
View File

@ -1,14 +0,0 @@
ent_conf = configuration_data()
ent_conf.set('PACKAGE', 'glib')
ent_conf.set('PACKAGE_BUGREPORT', 'https://gitlab.gnome.org/GNOME/glib/issues/new')
ent_conf.set('PACKAGE_NAME', 'glib')
ent_conf.set('PACKAGE_STRING', 'glib')
ent_conf.set('PACKAGE_TARNAME', 'glib')
ent_conf.set('PACKAGE_URL', 'FIXME')
ent_conf.set('PACKAGE_VERSION', glib_version)
ent_conf.set('PACKAGE_API_VERSION', glib_api_version)
configure_file(
input: 'gtkdocentities.ent.in',
output: 'gtkdocentities.ent',
configuration: ent_conf
)

103
docs/reference/girepository/gi-compile-repository.rst Normal file
View File

@ -0,0 +1,103 @@
.. _gi-compile-repository(1):
.. meta::
:copyright: Copyright 2010 Johan Dahlin
:copyright: Copyright 2015 Ben Boeckel
:copyright: Copyright 2013, 2015 Dieter Verfaillie
:copyright: Copyright 2018 Emmanuele Bassi
:copyright: Copyright 2018 Tomasz Miąsko
:copyright: Copyright 2018 Christoph Reiter
:copyright: Copyright 2020 Jan Tojnar
:copyright: Copyright 2024 Collabora Ltd.
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2010 Johan Dahlin
SPDX-FileCopyrightText: 2015 Ben Boeckel
SPDX-FileCopyrightText: 2013, 2015 Dieter Verfaillie
SPDX-FileCopyrightText: 2018 Emmanuele Bassi
SPDX-FileCopyrightText: 2018 Tomasz Miąsko
SPDX-FileCopyrightText: 2018 Christoph Reiter
SPDX-FileCopyrightText: 2020 Jan Tojnar
SPDX-FileCopyrightText: 2024 Collabora Ltd.
SPDX-License-Identifier: LGPL-2.1-or-later
=====================
gi-compile-repository
=====================
----------------
Typelib compiler
----------------
:Manual section: 1
SYNOPSIS
========
**gi-compile-repository** [*OPTION*…] *GIRFILE*
DESCRIPTION
===========
gi-compile-repository converts one or more GIR files into one or more typelibs.
The output will be written to standard output unless the ``--output`` is
specified.
OPTIONS
=======
``--help``
Show help options.
``--output`` *FILENAME*, ``-o`` *FILENAME*
Save the resulting output in *FILENAME*.
``--verbose``
Show verbose messages.
``--debug``
Show debug messages.
``--includedir`` *DIRECTORY*
Add *DIRECTORY* to the search path for GIR XML.
This option can be used more than once.
The first *DIRECTORY* on the command-line will be searched first
(highest precedence).
``--shared-library`` *FILENAME*, ``-l`` *FILENAME*
Specifies the shared library where the symbols in the typelib can be
found. The name of the library should not contain the ending shared
library suffix.
This option can be used more than once, for typelibs that describe
more than one shared library.
``--version``
Show program’s version number and exit.
EXAMPLE
=======
::
$ gi-compile-repository -o Gio-2.0.typelib /usr/share/gir-1.0/Gio-2.0.gir
BUGS
====
Report bugs at https://gitlab.gnome.org/GNOME/glib/-/issues
HOMEPAGE and CONTACT
====================
https://gi.readthedocs.io/
AUTHORS
=======
Matthias Clasen

107
docs/reference/girepository/gi-decompile-typelib.rst Normal file
View File

@ -0,0 +1,107 @@
.. _gi-decompile-typelib(1):
.. meta::
:copyright: Copyright 2008, 2010 Johan Dahlin
:copyright: Copyright 2014 Robert Roth
:copyright: Copyright 2015 Dieter Verfaillie
:copyright: Copyright 2018 Tomasz Miąsko
:copyright: Copyright 2018 Christoph Reiter
:copyright: Copyright 2020 Jan Tojnar
:copyright: Copyright 2024 Collabora Ltd.
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2008, 2010 Johan Dahlin
SPDX-FileCopyrightText: 2014 Robert Roth
SPDX-FileCopyrightText: 2015 Dieter Verfaillie
SPDX-FileCopyrightText: 2018 Tomasz Miąsko
SPDX-FileCopyrightText: 2018 Christoph Reiter
SPDX-FileCopyrightText: 2020 Jan Tojnar
SPDX-FileCopyrightText: 2024 Collabora Ltd.
SPDX-License-Identifier: LGPL-2.1-or-later
====================
gi-decompile-typelib
====================
------------------
Typelib decompiler
------------------
:Manual section: 1
SYNOPSIS
========
**gi-decompile-typelib** [*OPTION*…] *TYPELIB* [*TYPELIB*\ …]
DESCRIPTION
===========
gi-decompile-typelib is a GIR decompiler, using the repository API.
It generates GIR XML files from the compiled binary typelib format.
The output will be written to standard output unless the ``--output``
is specified.
The binary typelib format stores a subset of the information available
in GIR XML, so not all typelibs can be decompiled in this way, and the
resulting GIR XML might be incomplete.
Normally, GIR XML should be generated from source code, headers and
shared libraries using `g-ir-scanner(1) <man:g-ir-scanner(1)>`_
instead of using this tool.
OPTIONS
=======
``--help``
Show help options.
``--output`` *FILENAME*, ``-o`` *FILENAME*
Save the resulting output in *FILENAME*.
``--includedir`` *DIRECTORY*
Add *DIRECTORY* to the search path for typelibs.
This option can be used more than once.
The first *DIRECTORY* on the command-line will be searched first
(highest precedence).
``--all``
Show all available information.
``--version``
Show program’s version number and exit.
EXAMPLE
=======
::
$ libdir=/usr/lib/x86_64-linux-gnu # or /usr/lib64 or similar
$ gi-decompile-typelib -o Gio-2.0.gir \
$libdir/girepository-1.0/Gio-2.0.typelib
$ diff -u /usr/share/gir-1.0/Gio-2.0.gir Gio-2.0.gir
You will see that the original GIR XML contains much more information
than the decompiled typelib.
BUGS
====
Report bugs at https://gitlab.gnome.org/GNOME/glib/-/issues
HOMEPAGE and CONTACT
====================
https://gi.readthedocs.io/
AUTHORS
=======
Matthias Clasen

58
docs/reference/girepository/gi-inspect-typelib.rst Normal file
View File

@ -0,0 +1,58 @@
.. _gio(1):
.. meta::
:copyright: Copyright 2024 Collabora Ltd.
:license: LGPL-2.1-or-later
..
This has to be duplicated from above to make it machine-readable by `reuse`:
SPDX-FileCopyrightText: 2024 Collabora Ltd.
SPDX-License-Identifier: LGPL-2.1-or-later
==================
gi-inspect-typelib
==================
-----------------------
Typelib inspection tool
-----------------------
SYNOPSIS
--------
| **gi-inspect-typelib** [*OPTION*\ …] **--print-shlibs** *NAMESPACE*
| **gi-inspect-typelib** [*OPTION*\ …] **--print-typelibs** *NAMESPACE*
DESCRIPTION
-----------
**gi-inspect-typelib** displays information about GObject-Introspection
binary typelib files.
OPTIONS
-------
``--print-shlibs``
Show the shared libraries that implement the *NAMESPACE*.
``--print-typelibs``
Show the other typelibs that the *NAMESPACE* depends on.
``--typelib-version``
The version of each *NAMESPACE* to inspect.
For example, the version of ``Gio-2.0.typelib`` is ``2.0``.
If not specified, use the newest available version if there is more
than one installed.
EXAMPLE
-------
On Linux, the ``Gio-2.0`` typelib is implemented by ``libgio-2.0.so.0``::
$ gi-inspect-typelib --typelib-version 2.0 --print-shlibs Gio
shlib: libgio-2.0.so.0
and it depends on GObject-2.0, GLib-2.0 and GModule-2.0::
$ gi-inspect-typelib --typelib-version 2.0 --print-typelibs Gio
typelib: GObject-2.0
typelib: GLib-2.0
typelib: GModule-2.0

51
docs/reference/girepository/girepository.toml.in Normal file
View File

@ -0,0 +1,51 @@
# SPDX-License-Identifier: LGPL-2.1-or-later
# Copyright 2023 Matthias Clasen
# Copyright 2023 Philip Withnall
[library]
name = "Girepository"
version = "@VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/glib/"
repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
website_url = "https://www.gtk.org"
docs_urls = "https://docs.gtk.org/girepository/"
authors = "GLib Development Team"
license = "LGPL-2.1-or-later"
description = "GIRepository is a library providing access to typelibs and introspection data which describes C APIs"
dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
devhelp = true
search_index = true
[dependencies."GLib-2.0"]
name = "GLib"
description = "The base utility library"
docs_url = "https://docs.gtk.org/glib/"
[dependencies."GModule-2.0"]
name = "GModule"
description = "Portable API for dynamically loading modules"
docs_url = "https://docs.gtk.org/gmodule/"
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."Gio-2.0"]
name = "Gio"
description = "Useful classes for general purpose I/O, networking, IPC, settings, etc."
docs_url = "https://docs.gtk.org/gio/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[extra]
urlmap_file = "../urlmap.js"
# The same order will be used when generating the index
content_files = [
"migrating-gi.md",
]
content_images = [
]

56
docs/reference/girepository/meson.build Normal file
View File

@ -0,0 +1,56 @@
if get_option('man-pages').enabled()
manpages = [
'gi-compile-repository',
'gi-decompile-typelib',
'gi-inspect-typelib',
]
foreach page : manpages
custom_target(page + '-man',
input: page + '.rst',
output: page + '.1',
command: [
rst2man,
rst2man_flags,
'@INPUT@',
],
capture: true,
install: true,
install_dir: man1_dir,
install_tag: 'doc',
)
endforeach
endif
if get_option('documentation') and enable_gir
expand_content_files = [
'migrating-gi.md',
]
girepository_toml = configure_file(
input: 'girepository.toml.in',
output: 'girepository.toml',
configuration: toml_conf,
)
custom_target('girepository-docs',
input: [ girepository_toml, girepository_gir[0] ],
output: 'girepository',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gobject'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gmodule'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gio'),
'@INPUT1@',
],
build_by_default: true,
depend_files: expand_content_files,
install: true,
install_dir: docs_dir,
install_tag: 'doc',
)
endif

112
docs/reference/girepository/migrating-gi.md Normal file
View File

@ -0,0 +1,112 @@
Title: Migrating from girepository-1.0 to girepository-2.0
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2014 GNOME Foundation
# Migrating from girepository-1.0 to girepository-2.0
libgirepository was originally part of
[gobject-introspection](https://gitlab.gnome.org/GNOME/gobject-introspection/),
where it was prototyped for a number of years.
Now that it’s considered stable (for a long time), it’s been moved to
[glib](https://gitlab.gnome.org/GNOME/glib/) in order to simplify the build
process of the two modules.
As part of this move, the API version has been bumped from 1.0 to 2.0, and some
fairly straightforward API changes have been made. Note that the GIR version
was previously 2.0, and is now 3.0 — so the new version of libgirepository uses
`girepository-2.0.pc` and `GIRepository-3.0.typelib`.
The main change between the two versions of libgirepository is that it now uses
[type@GObject.TypeInstance] as the basis of its type system, rather than simple
C struct aliasing. This means that [type@GIRepository.BaseInfo] instances are
now reference counted using [method@GIRepository.BaseInfo.ref] and
[method@GIRepository.BaseInfo.unref].
It also means that runtime cast macros such as [func@GIRepository.CALLABLE_INFO]
are now available. Using these instead of simple C casts can improve the runtime
type safety of your code.
Stack allocation of some [type@GIRepository.BaseInfo] subtypes is still
possible, but they must now be cleared using
[method@GIRepository.BaseInfo.clear] once finished with. Previously this wasn’t
necessary.
As part of moving the code over, the symbol prefix has changed from `g_` to
`gi_` — this has affected every API in the library, but trivially.
The types of various function arguments have changed — for example from
`guint32` to `size_t` for most offsets. This will require minor adjustments in
your code if integer type warnings are enabled.
## API replacements from version 1.0 to 2.0
| girepository-1.0 | girepository-2.0 |
|------------------|------------------|
| `GI_CHECK_VERSION` | [func@GLib.CHECK_VERSION] |
| `g_arg_info_get_closure` | [method@GIRepository.ArgInfo.get_closure_index] |
| `g_arg_info_get_destroy` | [method@GIRepository.ArgInfo.get_destroy_index] |
| `g_arg_info_get_type` | [method@GIRepository.ArgInfo.get_type_info] |
| `g_arg_info_load_type` | [method@GIRepository.ArgInfo.load_type_info] |
| - | [method@GIRepository.BaseInfo.ref] and [method@GIRepository.BaseInfo.unref] |
| `g_base_info_get_type` | Use type checking macros like [func@GIRepository.IS_OBJECT_INFO], or raw [type@GObject.Type]s with [func@GObject.TYPE_FROM_INSTANCE] |
| `g_info_new` | Removed with no replacement, use [method@GIRepository.find_by_name] and related APIs |
| `g_callable_info_invoke` arguments | `is_method` and `throws` dropped in [method@GIRepository.CallableInfo.invoke] |
| `g_constant_info_get_type` | [method@GIRepository.ConstantInfo.get_type_info] |
| `g_field_info_get_type` | [method@GIRepository.FieldInfo.get_type_info] |
| `g_object_info_find_method_using_interfaces` and `g_object_info_find_vfunc_using_interfaces` | The `implementor` out argument has been renamed to `declarer` and is now of type [type@GIRepository.BaseInfo] |
| `g_object_info_get_type_init` | [method@GIRepository.ObjectInfo.get_type_init_function_name] |
| `g_object_info_get_ref_function` | [method@GIRepository.ObjectInfo.get_ref_function_name] |
| `g_object_info_get_unref_function` | [method@GIRepository.ObjectInfo.get_unref_function_name] |
| `g_object_info_get_set_value_function` | [method@GIRepository.ObjectInfo.get_set_value_function_name] |
| `g_object_info_get_get_value_function` | [method@GIRepository.ObjectInfo.get_get_value_function_name] |
| `g_property_info_get_type` | [method@GIRepository.PropertyInfo.get_type_info] |
| `g_registered_type_info_get_type_init` | [method@GIRepository.RegisteredTypeInfo.get_type_init_function_name] |
| `g_irepository_*` | `gi_repository_*` |
| `g_irepository_get_default` | Singleton object removed; create separate [class@GIRepository.Repository] instances instead |
| `g_irepository_get_search_path` and `g_irepository_get_library_path` | Now return arrays rather than linked lists |
| `g_irepository_enumerate_versions` | Now returns an array rather than a linked list |
| `g_irepository_get_immediate_dependencies`, `g_irepository_get_dependencies` and `g_irepository_get_loaded_namespaces` | Now additionally return a length argument |
| `g_irepository_get_shared_library` | [method@GIRepository.get_shared_libraries] |
| `g_irepository_dump` | Takes structured `input_filename` and `output_filename` arguments rather than a single formatted string |
| `g_function_invoker_destroy` | `gi_function_invoker_clear()` |
| `g_struct_info_get_copy_function` | [method@GIRepository.StructInfo.get_copy_function_name] |
| `g_struct_info_get_free_function` | [method@GIRepository.StructInfo.get_free_function_name] |
| `g_type_info_get_array_length` and `g_type_info_get_array_fixed_size` | Split success and failure return values out into a new out-argument and return value |
| `g_type_info_get_array_length` | [method@GIRepository.TypeInfo.get_array_length_index] |
| `g_typelib_new_from_*` | All replaced with `gi_typelib_new_from_bytes()` |
| `g_typelib_free` | [type@GIRepository.Typelib] is now a refcounted and boxed type, so use [method@GIRepository.Typelib.unref] |
| `GI_FUNCTION_THROWS` and `GI_VFUNC_THROWS` | [method@GIRepository.CallableInfo.can_throw_gerror] |
| `g_union_info_get_discriminator_offset` | Split success and failure return values out into a new out-argument and return value |
| `g_union_info_get_copy_function` | [method@GIRepository.UnionInfo.get_copy_function_name] |
| `g_union_info_get_free_function` | [method@GIRepository.UnionInfo.get_free_function_name] |
| `GIInfoType` | Use [type@GObject.Type] directly |
| `GI_INFO_TYPE_BOXED` | Dropped in favour of [method@GIRepository.RegisteredTypeInfo.is_boxed] |
## Utility program renames from version 1.0 to 2.0
| girepository-1.0 | girepository-2.0 |
|------------------|-------------------------|
| `g-ir-compiler` | `gi-compile-repository` |
| `g-ir-generate` | `gi-decompile-typelib` |
| `g-ir-inspect` | `gi-inspect-typelib` |
In addition, some command-line options have been changed.
The `--version` option for `g-ir-inspect` has been renamed to
`--typelib-version` in `gi-inspect-typelib`.
The `--includedir` option to `gi-decompile-typelib` treats the
given directories as most-important-first, consistent with
`gi-compile-repository --includedir` and `gcc -I`.
`g-ir-generate` treated `--includedir` options as least-important-first.
The unimplemented `g-ir-compiler --module` option has been removed in
`gi-compile-repository`.
The unimplemented `g-ir-generate --shlib` option has been removed in
`gi-decompile-typelib`.
`gi-inspect-typelib` only accepts one namespace parameter. `g-ir-inspect`
accepted multiple namespaces, but would only inspect the first one,
with the others being ignored.

75
docs/reference/glib/atomic.md Normal file
View File

@ -0,0 +1,75 @@
Title: Atomic Operations
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2012 Dan Winship
# Atomic Operations
The following is a collection of compiler macros to provide atomic
access to integer and pointer-sized values.
The macros that have ‘int’ in the name will operate on pointers to `gint` and
`guint`. The macros with ‘pointer’ in the name will operate on pointers to any
pointer-sized value, including `guintptr`.
There is no support for 64-bit operations on platforms with 32-bit pointers
because it is not generally possible to perform these operations atomically.
The get, set and exchange operations for integers and pointers
nominally operate on `gint` and `gpointer`, respectively. Of the
arithmetic operations, the ‘add’ operation operates on (and returns)
signed integer values (`gint` and `gssize`) and the ‘and’, ‘or’, and
‘xor’ operations operate on (and return) unsigned integer values
(`guint` and `gsize`).
All of the operations act as a full compiler and (where appropriate)
hardware memory barrier. Acquire and release or producer and
consumer barrier semantics are not available through this API.
It is very important that all accesses to a particular integer or
pointer be performed using only this API and that different sizes of
operation are not mixed or used on overlapping memory regions. Never
read or assign directly from or to a value — always use this API.
For simple reference counting purposes you should use `gatomicrefcount`
(see [func@GLib.atomic_ref_count_init]) rather than [func@GLib.atomic_int_inc]
and [func@GLib.atomic_int_dec_and_test].
Uses of [func@GLib.atomic_int_inc] and [func@GLib.atomic_int_dec_and_test]
that fall outside of simple counting patterns are prone to
subtle bugs and occasionally undefined behaviour. It is also worth
noting that since all of these operations require global
synchronisation of the entire machine, they can be quite slow. In
the case of performing multiple atomic operations it can often be
faster to simply acquire a mutex lock around the critical area,
perform the operations normally and then release the lock.
## Atomic Integer Operations
* [func@GLib.atomic_int_get]
* [func@GLib.atomic_int_set]
* [func@GLib.atomic_int_inc]
* [func@GLib.atomic_int_dec_and_test]
* [func@GLib.atomic_int_compare_and_exchange]
* [func@GLib.atomic_int_compare_and_exchange_full]
* [func@GLib.atomic_int_exchange]
* [func@GLib.atomic_int_add]
* [func@GLib.atomic_int_and]
* [func@GLib.atomic_int_or]
* [func@GLib.atomic_int_xor]
## Atomic Pointer Operations
* [func@GLib.atomic_pointer_get]
* [func@GLib.atomic_pointer_set]
* [func@GLib.atomic_pointer_compare_and_exchange]
* [func@GLib.atomic_pointer_compare_and_exchange_full]
* [func@GLib.atomic_pointer_exchange]
* [func@GLib.atomic_pointer_add]
* [func@GLib.atomic_pointer_and]
* [func@GLib.atomic_pointer_or]
* [func@GLib.atomic_pointer_xor]
## Deprecated API
* [func@GLib.atomic_int_exchange_and_add]

291
docs/reference/glib/auto-cleanup.md Normal file
View File

@ -0,0 +1,291 @@
Title: Automatic Cleanup
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2023 Matthias Clasen
# Automatic Cleanup
GLib provides a set of macros that wrap the GCC extension for automatic
cleanup of variables when they go out of scope.
These macros can only be used with GCC and GCC-compatible C compilers.
## Variable declaration
`g_auto(TypeName)`
: Helper to declare a variable with automatic cleanup.
The variable is cleaned up in a way appropriate to its type when the
variable goes out of scope. The `TypeName` of the variable must support
this.
The way to clean up the type must have been defined using one of the macros
`G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC()` or `G_DEFINE_AUTO_CLEANUP_FREE_FUNC()`.
This feature is only supported on GCC and clang. This macro is not
defined on other compilers and should not be used in programs that
are intended to be portable to those compilers.
This macro meant to be used with stack-allocated structures and
non-pointer types. For the (more commonly used) pointer version, see
`g_autoptr()`.
This macro can be used to avoid having to do explicit cleanups of
local variables when exiting functions. It often vastly simplifies
handling of error conditions, removing the need for various tricks
such as `goto out` or repeating of cleanup code. It is also helpful
for non-error cases.
Consider the following example:
GVariant *
my_func(void)
{
g_auto(GQueue) queue = G_QUEUE_INIT;
g_auto(GVariantBuilder) builder;
g_auto(GStrv) strv;
g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT);
strv = g_strsplit("a:b:c", ":", -1);
// ...
if (error_condition)
return NULL;
// ...
return g_variant_builder_end (&builder);
}
You must initialize the variable in some way — either by use of an
initialiser or by ensuring that an `_init` function will be called on
it unconditionally before it goes out of scope.
Since: 2.44
`g_autoptr(TypeName)`
: Helper to declare a pointer variable with automatic cleanup.
The variable is cleaned up in a way appropriate to its type when the
variable goes out of scope. The `TypeName` of the variable must support this.
The way to clean up the type must have been defined using the macro
`G_DEFINE_AUTOPTR_CLEANUP_FUNC()`.
This feature is only supported on GCC and clang. This macro is not
defined on other compilers and should not be used in programs that
are intended to be portable to those compilers.
This is meant to be used to declare pointers to types with cleanup
functions. The type of the variable is a pointer to `TypeName`. You
must not add your own `*`.
This macro can be used to avoid having to do explicit cleanups of
local variables when exiting functions. It often vastly simplifies
handling of error conditions, removing the need for various tricks
such as `goto out` or repeating of cleanup code. It is also helpful
for non-error cases.
Consider the following example:
gboolean
check_exists(GVariant *dict)
{
g_autoptr(GVariant) dirname, basename = NULL;
g_autofree gchar *path = NULL;
dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING);
if (dirname == NULL)
return FALSE;
basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING);
if (basename == NULL)
return FALSE;
path = g_build_filename (g_variant_get_string (dirname, NULL),
g_variant_get_string (basename, NULL),
NULL);
return g_access (path, R_OK) == 0;
}
You must initialise the variable in some way — either by use of an
initialiser or by ensuring that it is assigned to unconditionally
before it goes out of scope.
See also: `g_auto()`, `g_autofree()` and `g_steal_pointer()`.
Since: 2.44
`g_autofree`
: Macro to add an attribute to pointer variable to ensure automatic
cleanup using `g_free()`.
This macro differs from `g_autoptr()` in that it is an attribute supplied
before the type name, rather than wrapping the type definition. Instead
of using a type-specific lookup, this macro always calls `g_free()` directly.
This means it's useful for any type that is returned from `g_malloc()`.
Otherwise, this macro has similar constraints as `g_autoptr()`: only
supported on GCC and clang, the variable must be initialized, etc.
gboolean
operate_on_malloc_buf (void)
{
g_autofree guint8* membuf = NULL;
membuf = g_malloc (8192);
// Some computation on membuf
// membuf will be automatically freed here
return TRUE;
}
Since: 2.44
`g_autolist(TypeName)`
: Helper to declare a list variable with automatic deep cleanup.
The list is deeply freed, in a way appropriate to the specified type, when the
variable goes out of scope. The type must support this.
This feature is only supported on GCC and clang. This macro is not
defined on other compilers and should not be used in programs that
are intended to be portable to those compilers.
This is meant to be used to declare lists of a type with a cleanup
function. The type of the variable is a `GList *`. You
must not add your own `*`.
This macro can be used to avoid having to do explicit cleanups of
local variables when exiting functions. It often vastly simplifies
handling of error conditions, removing the need for various tricks
such as `goto out` or repeating of cleanup code. It is also helpful
for non-error cases.
See also: `g_autoslist()`, `g_autoptr()` and `g_steal_pointer()`.
Since: 2.56
`g_autoslist(TypeName)`
: Helper to declare a singly linked list variable with automatic deep cleanup.
The list is deeply freed, in a way appropriate to the specified type, when the
variable goes out of scope. The type must support this.
This feature is only supported on GCC and clang. This macro is not
defined on other compilers and should not be used in programs that
are intended to be portable to those compilers.
This is meant to be used to declare lists of a type with a cleanup
function. The type of the variable is a `GSList *`. You
must not add your own `*`.
This macro can be used to avoid having to do explicit cleanups of
local variables when exiting functions. It often vastly simplifies
handling of error conditions, removing the need for various tricks
such as `goto out` or repeating of cleanup code. It is also helpful
for non-error cases.
See also: `g_autolist()`, `g_autoptr()` and `g_steal_pointer()`.
Since: 2.56
`g_autoqueue(TypeName)`
: Helper to declare a double-ended queue variable with automatic deep cleanup.
The queue is deeply freed, in a way appropriate to the specified type, when the
variable goes out of scope. The type must support this.
This feature is only supported on GCC and clang. This macro is not
defined on other compilers and should not be used in programs that
are intended to be portable to those compilers.
This is meant to be used to declare queues of a type with a cleanup
function. The type of the variable is a `GQueue *`. You
must not add your own `*`.
This macro can be used to avoid having to do explicit cleanups of
local variables when exiting functions. It often vastly simplifies
handling of error conditions, removing the need for various tricks
such as `goto out` or repeating of cleanup code. It is also helpful
for non-error cases.
See also: `g_autolist()`, `g_autoptr()` and `g_steal_pointer()`.
Since: 2.62
## Type definition
`G_DEFINE_AUTOPTR_CLEANUP_FUNC(TypeName, func)`
: Defines the appropriate cleanup function for a pointer type.
The function will not be called if the variable to be cleaned up
contains `NULL`.
This will typically be the `_free()` or `_unref()` function for the given
type.
With this definition, it will be possible to use `g_autoptr()` with
the given `TypeName`.
G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref)
This macro should be used unconditionally; it is a no-op on compilers
where cleanup is not supported.
Since: 2.44
`G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(TypeName, func)`
: Defines the appropriate cleanup function for a type.
This will typically be the `_clear()` function for the given type.
With this definition, it will be possible to use `g_auto()` with
the given `TypeName`.
G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear)
This macro should be used unconditionally; it is a no-op on compilers
where cleanup is not supported.
Since: 2.44
`G_DEFINE_AUTO_CLEANUP_FREE_FUNC(TypeName, func, none_value)`
: Defines the appropriate cleanup function for a type.
With this definition, it will be possible to use `g_auto()` with the
given `TypeName`.
This function will be rarely used. It is used with pointer-based
typedefs and non-pointer types where the value of the variable
represents a resource that must be freed. Two examples are `GStrv`
and file descriptors.
`none_value` specifies the "none" value for the type in question. It
is probably something like `NULL` or `-1`.If the variable is found to
contain this value then the free function will not be called.
G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL)
This macro should be used unconditionally; it is a no-op on compilers
where cleanup is not supported.
Since: 2.44

20
docs/reference/glib/base64.md Normal file
View File

@ -0,0 +1,20 @@
Title: Base64 Encoding
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2006, 2009 Matthias Clasen
# Base64 Encoding
Base64 is an encoding that allows a sequence of arbitrary bytes to be
encoded as a sequence of printable ASCII characters. For the definition
of Base64, see [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) or
[RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
Base64 is most commonly used as a MIME transfer encoding for email.
GLib supports incremental encoding using [func@GLib.base64_encode_step] and
[func@GLib.base64_encode_close]. Incremental decoding can be done with
[func@GLib.base64_decode_step]. To encode or decode data in one go, use
[func@GLib.base64_encode] or [func@GLib.base64_decode]. To avoid memory
allocation when decoding, you can use [func@GLib.base64_decode_inplace].
Support for Base64 encoding was added in GLib 2.12.

180
docs/reference/glib/building.md Normal file
View File

@ -0,0 +1,180 @@
Title: Building GLib
# Building GLib
GLib uses the [Meson build system](https://mesonbuild.com). The normal
sequence for compiling and installing the GLib library is thus:
$ meson setup _build
$ meson compile -C _build
$ meson install -C _build
On FreeBSD, you will need something more complex:
$ env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib -Wl,--disable-new-dtags" \
> meson setup \
> -Dxattr=false \
> -Dinstalled_tests=true \
> -Db_lundef=false \
> _build
$ meson compile -C _build
The standard options provided by Meson may be passed to the `meson` command. Please see the Meson documentation or run:
meson configure --help
for information about the standard options.
GLib is compiled with
[strict aliasing](https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing)
disabled. It is strongly recommended that this is not re-enabled by overriding
the compiler flags, as GLib has not been tested with strict aliasing and cannot
be guaranteed to work.
## Dependencies
Before you can compile the GLib library, you need to have various other
tools and libraries installed on your system. If you are building from a
release archive, you will need a [compliant C
toolchain](https://gitlab.gnome.org/GNOME/glib/-/blob/main/docs/toolchain-requirements.md),
Meson, and pkg-config; the requirements are the same when building from a
Git repository clone of GLib.
- [`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/) is a
tool for tracking the compilation flags needed for libraries that are used
by the GLib library. (For each library, a small `.pc` text file is
installed in a standard location that contains the compilation flags
needed for that library along with version number information).
A UNIX build of GLib requires that the system implements at least the
original 1990 version of POSIX. Beyond this, it depends on a number of other
libraries.
- The [GNU libiconv library](http://www.gnu.org/software/libiconv/) is
needed to build GLib if your system doesn't have the `iconv()` function
for doing conversion between character encodings. Most modern systems
should have `iconv()`, however many older systems lack an `iconv()`
implementation. On such systems, you must install the libiconv library.
This can be found at: http://www.gnu.org/software/libiconv.
If your system has an `iconv()` implementation but you want to use libiconv
instead, make sure it is installed to the default compiler header/library
search path (for instance, in `/usr/local/`). The `iconv.h` that libiconv
installs hides the system iconv. Meson then detects this, recognizes that the
system iconv is unusable and the external one is mandatory, and automatically
forces it to be used.
If you are using the native iconv implementation on Solaris instead of
libiconv, you'll need to make sure that you have the converters between
locale encodings and UTF-8 installed. At a minimum you'll need the
SUNWuiu8 package. You probably should also install the SUNWciu8, SUNWhiu8,
SUNWjiu8, and SUNWkiu8 packages.
The native iconv on Compaq Tru64 doesn't contain support for UTF-8, so
you'll need to use GNU libiconv instead. (When using GNU libiconv for
GLib, you'll need to use GNU libiconv for GNU gettext as well.) This
probably applies to related operating systems as well.
- Python 3.5 or newer is required. Your system Python must conform to
[PEP 394](https://www.python.org/dev/peps/pep-0394/) For FreeBSD, this means
that the `lang/python3` port must be installed.
- The libintl library from the [GNU
gettext](http://www.gnu.org/software/gettext) package is needed if your
system doesn't have the `gettext()` functionality for handling message
translation databases.
- A thread implementation is needed. The thread support in GLib can be based
upon POSIX threads or win32 threads.
- GRegex uses the [PCRE library](http://www.pcre.org/) for regular
expression matching. The system version of PCRE is used, unless not available
(which is the case on Android), in which case a fallback subproject is used.
- The optional extended attribute support in GIO requires the `getxattr()`
family of functions that may be provided by the C library or by the
standalone libattr library. To build GLib without extended attribute
support, use the `-Dxattr=false` option.
- The optional SELinux support in GIO requires libselinux. To build GLib
without SELinux support, use the `-Dselinux=disabled` option.
- The optional support for DTrace requires the `sys/sdt.h` header, which is
provided by SystemTap on Linux. To build GLib without DTrace, use the
`-Ddtrace=false` option.
- The optional support for SystemTap can be disabled with the
`-Dsystemtap=false` option. Additionally, you can control the location
where GLib installs the SystemTap probes, using the
`-Dtapset_install_dir=DIR` option.
- [gobject-introspection](https://gitlab.gnome.org/GNOME/gobject-introspection/)
is needed to generate introspection data for consumption by other projects,
and to generate the GLib documentation via
[gi-docgen](https://gitlab.gnome.org/GNOME/gi-docgen). There is a dependency
cycle between GLib and gobject-introspection. This can be broken by building
GLib first with `-Dintrospection=disabled`, then building
gobject-introspection against this copy of GLib, then re-building GLib against
the new gobject-introspection with `-Dintrospection=enabled`. The GLib API
documentation can be built during this second build process if
`-Ddocumentation=true` is also set.
## Extra Configuration Options
In addition to the normal options, these additional ones are supported when
configuring the GLib library:
`--buildtype`
: This is a standard Meson option which specifies how much debugging and
optimization to enable. If the build type is `debug`, `G_ENABLE_DEBUG` will be
defined and GLib will be built with additional debug code enabled. You can
override this behavior using `-Dglib_debug`.
`-Dforce_posix_threads=true`
: Normally, Meson should be able to work out the correct thread implementation
to use. This option forces POSIX threads to be used even if the platform
provides another threading API (for example, on Windows).
`-Dbsymbolic_functions=false` and `-Dbsymbolic_functions=true`
: By default, GLib uses the `-Bsymbolic-functions` linker flag to avoid
intra-library PLT jumps. A side-effect of this is that it is no longer
possible to override internal uses of GLib functions with `LD_PRELOAD`.
Therefore, it may make sense to turn this feature off in some
situations. The `-Dbsymbolic_functions=false` option allows to do that.
`-Ddocumentation=false` and `-Ddocumentation=true`
: By default, GLib will not build documentation for the library and tools. This
option can be used to enable building the documentation.
`-Dman-pages=disabled` and `-Dman-pages=enabled`
: By default, GLib will detect whether `rst2man` and the necessary DocBook
stylesheets are installed. If they are, then it will use them to build
the included man pages from the reStructuredText sources. These options can be
used to explicitly control whether man pages should be built and used.
`-Dxattr=false` and `-Dxattr=true`
: By default, GLib will detect whether the `getxattr()` family of functions is
available. If it is, then extended attribute support will be included in
GIO. These options can be used to explicitly control whether extended
attribute support should be included or not. `getxattr()` and friends can be
provided by glibc or by the standalone libattr library.
`-Dselinux=auto`, `-Dselinux=enabled` or `-Dselinux=disabled`
: By default, GLib will detect if libselinux is available and include SELinux
support in GIO if it is. These options can be used to explicitly control
whether SELinux support should be included.
`-Ddtrace=false` and `-Ddtrace=true`
: By default, GLib will detect if DTrace support is available, and use it.
These options can be used to explicitly control whether DTrace support is
compiled into GLib.
`-Dsystemtap=false` and `-Dsystemtap=true`
: This option requires DTrace support. If it is available, then GLib will also
check for the presence of SystemTap.
`-Db_coverage=true` and `-Db_coverage=false`
: Enable the generation of coverage reports for the GLib tests. This requires
the lcov frontend to gcov from the Linux Test Project. To generate a
coverage report, use `ninja coverage-html`. The report is placed in the
`meson-logs` directory.

339
docs/reference/glib/building.xml
View File

@ -1,339 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-building">
<refmeta>
<refentrytitle>Compiling the GLib package</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Compiling the GLib Package</refname>
<refpurpose>How to compile GLib itself</refpurpose>
</refnamediv>
<refsect1 id="building">
<title>Building the Library on UNIX</title>
<para>
On UNIX, GLib uses the standard <application>Meson</application> build
system. The normal sequence for compiling and installing the GLib library
is thus:
<literallayout>
<userinput>meson setup _build</userinput>
<userinput>meson compile -C _build</userinput>
<userinput>meson install -C _build</userinput>
</literallayout>
On FreeBSD:
<literallayout>
<userinput>env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib -Wl,--disable-new-dtags" meson setup -Dxattr=false -Dinstalled_tests=true -Db_lundef=false _build</userinput>
<userinput>meson compile -C _build</userinput>
</literallayout>
</para>
<para>
The standard options provided by <application>Meson</application> may be
passed to the <command>meson</command> command. Please see the
<application>Meson</application> documentation or run
<command>meson configure --help</command> for information about
the standard options.
</para>
<para>
GLib is compiled with
<ulink url="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing">strict aliasing</ulink>
disabled. It is strongly recommended that this is not re-enabled by
overriding the compiler flags, as GLib has not been tested with strict
aliasing and cannot be guaranteed to work.
</para>
<para>
The GTK documentation contains
<ulink url="https://developer.gnome.org/gtk3/stable/gtk-building.html">further details</ulink>
about the build process and ways to influence it.
</para>
</refsect1>
<refsect1 id="dependencies">
<title>Dependencies</title>
<para>
Before you can compile the GLib library, you need to have
various other tools and libraries installed on your system.
If you are building from a release archive, you will need
<ulink url="https://gitlab.gnome.org/GNOME/glib/-/blob/main/docs/toolchain-requirements.md">a compliant C toolchain</ulink>,
<application>Meson</application>, and <application>pkg-config</application>;
the requirements are the same when building from a Git repository clone
of GLib.
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
is a tool for tracking the compilation flags needed for
libraries that are used by the GLib library. (For each
library, a small <literal>.pc</literal> text file is
installed in a standard location that contains the compilation
flags needed for that library along with version number
information).
</para>
</listitem>
</itemizedlist>
<para>
A UNIX build of GLib requires that the system implements at
least the original 1990 version of POSIX. Beyond this, it
depends on a number of other libraries.
</para>
<itemizedlist>
<listitem>
<para>
The <ulink url="http://www.gnu.org/software/libiconv/">GNU
libiconv library</ulink> is needed to build GLib if your
system doesn't have the <function>iconv()</function>
function for doing conversion between character
encodings. Most modern systems should have
<function>iconv()</function>, however many older systems lack
an <function>iconv()</function> implementation. On such systems,
you must install the libiconv library. This can be found at:
<ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
</para>
<para>
If your system has an <function>iconv()</function> implementation but
you want to use libiconv instead, make sure it is installed to the
default compiler header/library search path (for instance, in
<filename>/usr/local/</filename>). The <filename>iconv.h</filename>
that libiconv installs hides the system iconv. Meson then detects
this, recognizes that the system iconv is unusable and the external
one is mandatory, and automatically forces it to be used.
</para>
<para>
If you are using the native iconv implementation on Solaris
instead of libiconv, you'll need to make sure that you have
the converters between locale encodings and UTF-8 installed.
At a minimum you'll need the SUNWuiu8 package. You probably
should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
SUNWkiu8 packages.
</para>
<para>
The native iconv on Compaq Tru64 doesn't contain support for
UTF-8, so you'll need to use GNU libiconv instead. (When
using GNU libiconv for GLib, you'll need to use GNU libiconv
for GNU gettext as well.) This probably applies to related
operating systems as well.
</para>
</listitem>
<listitem>
<para>
Python 3.5 or newer is required. Your system Python must
conform to <ulink
url="https://www.python.org/dev/peps/pep-0394/">PEP 394
</ulink>
For FreeBSD, this means that the
<literal>lang/python3</literal> port must be installed.
</para>
</listitem>
<listitem>
<para>
The libintl library from the <ulink
url="http://www.gnu.org/software/gettext">GNU gettext
package</ulink> is needed if your system doesn't have the
<function>gettext()</function> functionality for handling
message translation databases.
</para>
</listitem>
<listitem>
<para>
A thread implementation is needed. The thread support in GLib
can be based upon POSIX threads or win32 threads.
</para>
</listitem>
<listitem>
<para>
GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink>
for regular expression matching. The system version of PCRE is used,
unless not available (which is the case on Android), in which case a
fallback subproject is used.
</para>
</listitem>
<listitem>
<para>
The optional extended attribute support in GIO requires the
<function>getxattr()</function> family of functions that may be
provided by the C library or by the standalone libattr library. To
build GLib without extended attribute support, use the
<option>-Dxattr=false</option> option.
</para>
</listitem>
<listitem>
<para>
The optional SELinux support in GIO requires libselinux.
To build GLib without SELinux support, use the
<option>-Dselinux=disabled</option> option.
</para>
</listitem>
<listitem>
<para>
The optional support for DTrace requires the
<filename>sys/sdt.h</filename> header, which is provided
by SystemTap on Linux. To build GLib without DTrace, use
the <option>-Ddtrace=false</option> option.
</para>
</listitem>
<listitem>
<para>
The optional support for
<ulink url="http://sourceware.org/systemtap/">SystemTap</ulink>
can be disabled with the <option>-Dsystemtap=false</option>
option. Additionally, you can control the location
where GLib installs the SystemTap probes, using the
<option>-Dtapset_install_dir=DIR</option> option.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 id="extra-configuration-options">
<title>Extra Configuration Options</title>
<para>
In addition to the normal options, these additional ones are supported
when configuring the GLib library:
</para>
<formalpara>
<title><option>--buildtype</option></title>
<para>
This is a standard <application>Meson</application> option which
specifies how much debugging and optimization to enable. If the build
type is <literal>debug</literal>,
<literal>G_ENABLE_DEBUG</literal> will be defined and GLib will be built
with additional debug code enabled. You can override this behavior using
<option>-Dglib_debug</option>.
</para>
</formalpara>
<formalpara>
<title><option>-Dforce_posix_threads=true</option></title>
<para>
Normally, <application>Meson</application> should be able to work out
the correct thread implementation to use. This option forces POSIX
threads to be used even if the platform provides another threading API
(for example, on Windows).
</para>
</formalpara>
<formalpara>
<title><option>-Dbsymbolic_functions=false</option> and
<option>-Dbsymbolic_functions=true</option></title>
<para>
By default, GLib uses the <option>-Bsymbolic-functions</option>
linker flag to avoid intra-library PLT jumps. A side-effect
of this is that it is no longer possible to override
internal uses of GLib functions with
<envar>LD_PRELOAD</envar>. Therefore, it may make
sense to turn this feature off in some situations.
The <option>-Dbsymbolic_functions=false</option> option allows
to do that.
</para>
</formalpara>
<formalpara>
<title><option>-Dgtk_doc=false</option> and
<option>-Dgtk_doc=true</option></title>
<para>
By default, GLib will detect whether the
<application>gtk-doc</application> package is installed.
If it is, then it will use it to extract and build the
documentation for the GLib library. These options
can be used to explicitly control whether
<application>gtk-doc</application> should be
used or not. If it is not used, the distributed,
pre-generated HTML files will be installed instead of
building them on your machine.
</para>
</formalpara>
<formalpara>
<title><option>-Dman=false</option> and
<option>-Dman=true</option></title>
<para>
By default, GLib will detect whether <application>xsltproc</application>
and the necessary DocBook stylesheets are installed.
If they are, then it will use them to rebuild the included
man pages from the XML sources. These options can be used
to explicitly control whether man pages should be rebuilt
used or not. The distribution includes pre-generated man
pages.
</para>
</formalpara>
<formalpara>
<title><option>-Dxattr=false</option> and
<option>-Dxattr=true</option></title>
<para>
By default, GLib will detect whether the
<function>getxattr()</function>
family of functions is available. If it is, then extended
attribute support will be included in GIO. These options can
be used to explicitly control whether extended attribute
support should be included or not. <function>getxattr()</function>
and friends can be provided by glibc or by the standalone
libattr library.
</para>
</formalpara>
<formalpara>
<title><option>-Dselinux=auto</option>,
<option>-Dselinux=enabled</option> or
<option>-Dselinux=disabled</option></title>
<para>
By default, GLib will detect if libselinux is available and
include SELinux support in GIO if it is. These options can be
used to explicitly control whether SELinux support should
be included.
</para>
</formalpara>
<formalpara>
<title><option>-Ddtrace=false</option> and
<option>-Ddtrace=true</option></title>
<para>
By default, GLib will detect if DTrace support is available, and use it.
These options can be used to explicitly control whether DTrace support
is compiled into GLib.
</para>
</formalpara>
<formalpara>
<title><option>-Dsystemtap=false</option> and
<option>-Dsystemtap=true</option></title>
<para>
This option requires DTrace support. If it is available, then
GLib will also check for the presence of SystemTap.
</para>
</formalpara>
<formalpara>
<title><option>-Db_coverage=true</option> and
<option>-Db_coverage=false</option></title>
<para>
Enable the generation of coverage reports for the GLib tests.
This requires the lcov frontend to gcov from the
<ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>.
To generate a coverage report, use
<command>ninja coverage-html</command>. The report is placed in the
<filename>meson-logs</filename> directory.
</para>
</formalpara>
</refsect1>
</refentry>

174
docs/reference/glib/changes.xml
View File

@ -1,174 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-changes" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Changes to GLib</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Changes to GLib</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Changes to GLib</refname>
<refpurpose>
Incompatible changes made between successive versions of GLib
</refpurpose>
</refnamediv>
<refsect1>
<title>Incompatible changes from 2.0 to 2.2</title>
<itemizedlist>
<listitem>
<para>
GLib changed the seeding algorithm for the pseudo-random number
generator Mersenne Twister, as used by <structname>GRand</structname>
and <structname>GRandom</structname>. This was necessary, because some
seeds would yield very bad pseudo-random streams. Also the
pseudo-random integers generated by
<function>g_rand*_int_range()</function> will have a
slightly better equal distribution with the new version of GLib.
</para>
<para>
Further information can be found at the website of the Mersenne
Twister random number generator at <ulink
url="http://www.math.keio.ac.jp/~matumoto/emt.html">http://www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
</para>
<para>
The original seeding and generation algorithms, as found in GLib
2.0.x, can be used instead of the new ones by setting the environment
variable <envar>G_RANDOM_VERSION</envar> to the value of '2.0'. Use
the GLib-2.0 algorithms only if you have sequences of numbers generated
with Glib-2.0 that you need to reproduce exactly.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1>
<title>Incompatible changes from 1.2 to 2.0</title>
<itemizedlist>
<listitem>
<para>
The event loop functionality <structname>GMain</structname> has extensively
been revised to support multiple separate main loops in separate threads.
All sources (timeouts, idle functions, etc.) are associated with a
<structname>GMainContext</structname>.
</para>
<para>
Compatibility functions exist so that most application code dealing with
the main loop will continue to work. However, code that creates new custom
types of sources will require modification.
</para>
<para>
The main changes here are:
<itemizedlist>
<listitem>
<para>
Sources are now exposed as <type>GSource *</type>, rather than simply as
numeric ids.
</para>
</listitem>
<listitem>
<para>
New types of sources are created by structure "derivation" from
<structname>GSource</structname>, so the <literal>source_data</literal>
parameter to the <structname>GSource</structname> virtual functions has been
replaced with a <type>GSource *</type>.
</para>
</listitem>
<listitem>
<para>
Sources are first created, then later added to a specific
<structname>GMainContext</structname>.
</para>
</listitem>
<listitem>
<para>
Dispatching has been modified so both the callback and data are passed
in to the <function>dispatch()</function> virtual function.
</para>
</listitem>
</itemizedlist>
To go along with this change, the vtable for
<structname>GIOChannel</structname> has changed and
<function>add_watch()</function> has been replaced by
<function>create_watch()</function>.
</para>
</listitem>
<listitem>
<para>
<function>g_list_foreach()</function> and
<function>g_slist_foreach()</function> have been changed so they
are now safe against removal of the current item, not the next item.
</para>
<para>
It's not recommended to mutate the list in the callback to these
functions in any case.
</para>
</listitem>
<listitem>
<para>
<structname>GDate</structname> now works in UTF-8, not in the current locale.
If you want to use it with the encoding of the locale, you need to convert
strings using <function>g_locale_to_utf8()</function> first.
</para>
</listitem>
<listitem>
<para>
<function>g_strsplit()</function> has been fixed to:
<itemizedlist>
<listitem>
<para>
include trailing empty tokens, rather than stripping them
</para>
</listitem>
<listitem>
<para>
split into a maximum of <literal>max_tokens</literal> tokens, rather
than <literal>max_tokens + 1</literal>
</para>
</listitem>
</itemizedlist>
Code depending on either of these bugs will need to be fixed.
</para>
</listitem>
<listitem>
<para>
Deprecated functions that got removed:
<function>g_set_error_handler()</function>,
<function>g_set_warning_handler()</function>,
<function>g_set_message_handler()</function>, use
<function>g_log_set_handler()</function> instead.
</para>
</listitem>
</itemizedlist>
</refsect1>
</refentry>

91
docs/reference/glib/character-set.md Normal file
View File

@ -0,0 +1,91 @@
Title: Character Set Conversions
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010, 2012, 2014 Matthias Clasen
# Character Set Conversions
The [`func@GLib.convert`] family of function wraps the functionality of
iconv(). In addition to pure character set conversions, GLib has functions
to deal with the extra complications of encodings for file names.
## File Name Encodings
Historically, UNIX has not had a defined encoding for file names: a file
name is valid as long as it does not have path separators in it ("/").
However, displaying file names may require conversion: from the character
set in which they were created, to the character set in which the
application operates. Consider the Spanish file name "Presentación.sxi". If
the application which created it uses ISO-8859-1 for its encoding,
```
Character: P r e s e n t a c i ó n . s x i
Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
```
However, if the application use UTF-8, the actual file name on disk would
look like this:
```
Character: P r e s e n t a c i ó n . s x i
Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
```
Glib uses UTF-8 for its strings, and GUI toolkits like GTK that use GLib do
the same thing. If you get a file name from the file system, for example,
from `readdir()` or from [`method@GLib.Dir.read_name`], and you wish to
display the file name to the user, you will need to convert it into UTF-8.
The opposite case is when the user types the name of a file they wish to
save: the toolkit will give you that string in UTF-8 encoding, and you will
need to convert it to the character set used for file names before you can
create the file with `open()` or `fopen()`.
By default, GLib assumes that file names on disk are in UTF-8 encoding. This
is a valid assumption for file systems which were created relatively
recently: most applications use UTF-8 encoding for their strings, and that
is also what they use for the file names they create. However, older file
systems may still contain file names created in "older" encodings, such as
ISO-8859-1. In this case, for compatibility reasons, you may want to
instruct GLib to use that particular encoding for file names rather than
UTF-8. You can do this by specifying the encoding for file names in the
`G_FILENAME_ENCODING` environment variable. For example, if your installation
uses ISO-8859-1 for file names, you can put this in your `~/.profile`:
export G_FILENAME_ENCODING=ISO-8859-1
GLib provides the functions [`func@GLib.filename_to_utf8`] and
[`func@GLib.filename_from_utf8`] to perform the necessary conversions. These
functions convert file names from the encoding specified in
`G_FILENAME_ENCODING` to UTF-8 and vice-versa. This diagram illustrates how
these functions are used to convert between UTF-8 and the encoding for file
names in the file system.
## Conversion between file name encodings
![](file-name-encodings.png)
## Checklist for Application Writers
This section is a practical summary of the detailed things to do to make
sure your applications process file name encodings correctly.
1. If you get a file name from the file system from a function such as
`readdir()` or `gtk_file_chooser_get_filename()`, you do not need to do
any conversion to pass that file name to functions like `open()`,
`rename()`, or `fopen()` -- those are "raw" file names which the file
system understands.
2. If you need to display a file name, convert it to UTF-8 first by using
[`func@GLib.filename_to_utf8`]. If conversion fails, display a string
like "Unknown file name". Do not convert this string back into the
encoding used for file names if you wish to pass it to the file system;
use the original file name instead.
3. For example, the document window of a word processor could display
"Unknown file name" in its title bar but still let the user save the
file, as it would keep the raw file name internally. This can happen if
the user has not set the `G_FILENAME_ENCODING` environment variable even
though he has files whose names are not encoded in UTF-8.
4. If your user interface lets the user type a file name for saving or
renaming, convert it to the encoding used for file names in the file
system by using [`func@GLib.filename_from_utf8`]. Pass the converted file
name to functions like `fopen()`. If conversion fails, ask the user to
enter a different file name. This can happen if the user types Japanese
characters when `G_FILENAME_ENCODING` is set to ISO-8859-1, for example.

30
docs/reference/glib/checked-math.md Normal file
View File

@ -0,0 +1,30 @@
Title: Bounds-checking Integer Arithmetic
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2015 Allison Lortie
# Bounds-checking Integer Arithmetic
GLib offers a set of macros for doing additions and multiplications
of unsigned integers, with checks for overflows.
The helpers all have three arguments. A pointer to the destination
is always the first argument and the operands to the operation are
the other two.
Following standard GLib convention, the helpers return true in case
of success (ie: no overflow).
The helpers may be macros, normal functions or inlines. They may be
implemented with inline assembly or compiler intrinsics where
available.
Since: 2.48
The APIs are:
* [func@GLib.uint_checked_add]
* [func@GLib.uint_checked_mul]
* [func@GLib.uint64_checked_add]
* [func@GLib.uint64_checked_mul]
* [func@GLib.size_checked_add]
* [func@GLib.size_checked_mul]

71
docs/reference/glib/compiling.md Normal file
View File

@ -0,0 +1,71 @@
Title: Compiling GLib Applications
# Compiling GLib Applications
To compile a GLib application, you need to tell the compiler where to find
the GLib header files and libraries. This is done with the
[`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/)
utility.
The following interactive shell session demonstrates how pkg-config is used
(the actual output on your system may be different):
$ pkg-config --cflags glib-2.0
-I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
$ pkg-config --libs glib-2.0
-L/usr/lib -lm -lglib-2.0
See the `pkg-config` website for more information about `pkg-config`.
If your application uses or GObject features, it must be compiled and linked
with the options returned by the following `pkg-config` invocation:
$ pkg-config --cflags --libs gobject-2.0
If your application uses modules, it must be compiled and linked with the
options returned by one of the following pkg-config invocations:
$ pkg-config --cflags --libs gmodule-no-export-2.0
$ pkg-config --cflags --libs gmodule-2.0
The difference between the two is that `gmodule-2.0` adds `--export-dynamic`
to the linker flags, which is often not needed.
The simplest way to compile a program is to use the "backticks" feature of
the shell. If you enclose a command in backticks (not single quotes), then
its output will be substituted into the command line before execution. So to
compile a GLib Hello, World, you would type the following:
$ cc `pkg-config --cflags glib-2.0` hello.c -o hello `pkg-config --libs glib-2.0`
Deprecated GLib functions are annotated to make the compiler emit warnings
when they are used (e.g. with GCC, you need to use the
`-Wdeprecated-declarations option`). If these warnings are problematic, they
can be turned off by defining the preprocessor symbol
`GLIB_DISABLE_DEPRECATION_WARNINGS` by using the commandline option
`-DGLIB_DISABLE_DEPRECATION_WARNINGS`
GLib deprecation annotations are versioned; by defining the macros
`GLIB_VERSION_MIN_REQUIRED` and `GLIB_VERSION_MAX_ALLOWED`, you can specify the
range of GLib versions whose API you want to use. APIs that were deprecated
before or introduced after this range will trigger compiler warnings.
Since GLib 2.62, the older deprecation mechanism of hiding deprecated
interfaces entirely from the compiler by using the preprocessor symbol
`G_DISABLE_DEPRECATED` has been removed. All deprecations are now handled
using the above mechanism.
The recommended way of using GLib has always been to only include the
toplevel headers `glib.h`, `glib-object.h`, `gio.h`. Starting with 2.32, GLib
enforces this by generating an error when individual headers are directly
included.
Still, there are some exceptions; these headers have to be included
separately:
- `gmodule.h`
- `glib-unix.h`
- `glib/gi18n-lib.h` or `glib/gi18n.h` (see the section on
[Internationalization](i18n.html))
- `glib/gprintf.h` and `glib/gstdio.h` (we don't want to pull in all of
stdio)

125
docs/reference/glib/compiling.xml
View File

@ -1,125 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-compiling" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Compiling GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Compiling GLib Applications</refname>
<refpurpose>
How to compile your GLib application
</refpurpose>
</refnamediv>
<refsect1>
<title>Compiling GLib Applications on UNIX</title>
<para>
To compile a GLib application, you need to tell the compiler where to
find the GLib header files and libraries. This is done with the
<application>pkg-config</application> utility.
</para>
<para>
The following interactive shell session demonstrates how
<application>pkg-config</application> is used (the actual output on
your system may be different):
<programlisting>
$ pkg-config --cflags glib-2.0
-I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
$ pkg-config --libs glib-2.0
-L/usr/lib -lm -lglib-2.0
</programlisting>
</para>
<para>
See the <ulink url="http://www.freedesktop.org/wiki/Software/pkg-config">pkg-config website</ulink>
for more information about <application>pkg-config</application>.
</para>
<para>
If your application uses or <structname>GObject</structname>
features, it must be compiled and linked with the options returned
by the following <application>pkg-config</application> invocation:
<programlisting>
$ pkg-config --cflags --libs gobject-2.0
</programlisting>
</para>
<para>
If your application uses modules, it must be compiled and linked
with the options returned by one of the following
<application>pkg-config</application> invocations:
<programlisting>
$ pkg-config --cflags --libs gmodule-no-export-2.0
$ pkg-config --cflags --libs gmodule-2.0
</programlisting>
The difference between the two is that gmodule-2.0 adds
<option>--export-dynamic</option> to the linker flags,
which is often not needed.
</para>
<para>
The simplest way to compile a program is to use command substitution
feature of a shell. A command written in the format
<literal>$(command)</literal> gets substituted into the command line
before execution. So to compile a GLib Hello, World, you would type
the following:
<programlisting>
$ cc hello.c $(pkg-config --cflags --libs glib-2.0) -o hello
</programlisting>
</para>
<note><para>
Note that the name of the file must come before the other options
(such as <emphasis>pkg-config</emphasis>), or else you may get an
error from the linker.
</para></note>
<para>
Deprecated GLib functions are annotated to make the compiler
emit warnings when they are used (e.g. with gcc, you need to use
the -Wdeprecated-declarations option). If these warnings are
problematic, they can be turned off by defining the preprocessor
symbol %GLIB_DISABLE_DEPRECATION_WARNINGS by using the commandline
option <literal>-DGLIB_DISABLE_DEPRECATION_WARNINGS</literal>
</para>
<para>
GLib deprecation annotations are versioned; by defining the
macros %GLIB_VERSION_MIN_REQUIRED and %GLIB_VERSION_MAX_ALLOWED,
you can specify the range of GLib versions whose API you want
to use. APIs that were deprecated before or introduced after
this range will trigger compiler warnings.
</para>
<para>
Since GLib 2.62, the older deprecation mechanism of hiding deprecated interfaces
entirely from the compiler by using the preprocessor symbol
<literal>G_DISABLE_DEPRECATED</literal> has been removed. All deprecations
are now handled using the above mechanism.
</para>
<para>
The recommended way of using GLib has always been to only include the
toplevel headers <filename>glib.h</filename>,
<filename>glib-object.h</filename>, <filename>gio.h</filename>.
Starting with 2.32, GLib enforces this by generating an error
when individual headers are directly included.
</para>
<para>
Still, there are some exceptions; these headers have to be included
separately:
<filename>gmodule.h</filename>,
<filename>glib-unix.h</filename>,
<filename>glib/gi18n-lib.h</filename> or
<filename>glib/gi18n.h</filename> (see
the <link linkend="glib-I18N">Internationalization section</link>),
<filename>glib/gprintf.h</filename> and
<filename>glib/gstdio.h</filename>
(we don't want to pull in all of stdio).
</para>
</refsect1>
</refentry>

281
docs/reference/glib/conversion-macros.md Normal file
View File

@ -0,0 +1,281 @@
Title: Conversion Macros
# Conversion Macros
## Type Conversion
Many times GLib, GTK, and other libraries allow you to pass "user data" to a
callback, in the form of a void pointer. From time to time you want to pass
an integer instead of a pointer. You could allocate an integer, with
something like:
```c
int *ip = g_new (int, 1);
*ip = 42;
```
But this is inconvenient, and it's annoying to have to free the memory at
some later time.
Pointers are always at least 32 bits in size (on all platforms GLib intends
to support). Thus you can store at least 32-bit integer values in a pointer
value. Naively, you might try this, but it's incorrect:
```c
gpointer p;
int i;
p = (void*) 42;
i = (int) p;
```
Again, that example was not correct, don't copy it.
The problem is that on some systems you need to do this:
```c
gpointer p;
int i;
p = (void*) (long) 42;
i = (int) (long) p;
```
The GLib macros `GPOINTER_TO_INT()`, `GINT_TO_POINTER()`, etc. take care to
do the right thing on every platform.
**Warning**: You may not store pointers in integers. This is not portable in
any way, shape or form. These macros only allow storing integers in
pointers, and only preserve 32 bits of the integer; values outside the range
of a 32-bit integer will be mangled.
``GINT_TO_POINTER(value)``, ``GPOINTER_TO_INT(value)``
: Stuffs an integer into a pointer type, and vice versa. Remember, you may not
store pointers in integers. This is not portable in any way, shape or form.
These macros only allow storing integers in pointers, and only preserve 32
bits of the integer; values outside the range of a 32-bit integer will be
mangled.
``GUINT_TO_POINTER(value)``, ``GPOINTER_TO_UINT(value)``
: Stuffs an unsigned integer into a pointer type, and vice versa.
``GSIZE_TO_POINTER(value)``, ``GPOINTER_TO_SIZE(value)``
: Stuffs a `size_t` into a pointer type, and vice versa.
## Byte Order Conversion
These macros provide a portable way to determine the host byte order and to
convert values between different byte orders.
The byte order is the order in which bytes are stored to create larger data
types such as the #gint and #glong values. The host byte order is the byte
order used on the current machine.
Some processors store the most significant bytes (i.e. the bytes that hold
the largest part of the value) first. These are known as big-endian
processors. Other processors (notably the x86 family) store the most
significant byte last. These are known as little-endian processors.
Finally, to complicate matters, some other processors store the bytes in a
rather curious order known as PDP-endian. For a 4-byte word, the 3rd most
significant byte is stored first, then the 4th, then the 1st and finally the
2nd.
Obviously there is a problem when these different processors communicate
with each other, for example over networks or by using binary file formats.
This is where these macros come in. They are typically used to convert
values into a byte order which has been agreed on for use when communicating
between different processors. The Internet uses what is known as 'network
byte order' as the standard byte order (which is in fact the big-endian byte
order).
Note that the byte order conversion macros may evaluate their arguments
multiple times, thus you should not use them with arguments which have
side-effects.
`G_BYTE_ORDER`
: The host byte order. This can be either `G_LITTLE_ENDIAN` or `G_BIG_ENDIAN`.
`G_LITTLE_ENDIAN`
: Specifies the little endian byte order.
`G_BIG_ENDIAN`
: Specifies the big endian byte order.
`G_PDP_ENDIAN`
: Specifies the PDP endian byte order.
### Signed
`GINT_FROM_BE(value)`
: Converts an `int` value from big-endian to host byte order.
`GINT_FROM_LE(value)`
: Converts an `int` value from little-endian to host byte order.
`GINT_TO_BE(value)`
: Converts an `int` value from host byte order to big-endian.
`GINT_TO_LE(value)`
: Converts an `int` value from host byte order to little-endian.
`GLONG_FROM_BE(value)`
: Converts a `long` value from big-endian to the host byte order.
`GLONG_FROM_LE(value)`
: Converts a `long` value from little-endian to host byte order.
`GLONG_TO_BE(value)`
: Converts a `long` value from host byte order to big-endian.
`GLONG_TO_LE(value)`
: Converts a `long` value from host byte order to little-endian.
`GSSIZE_FROM_BE(value)`
: Converts a `ssize_t` value from big-endian to host byte order.
`GSSIZE_FROM_LE(value)`
: Converts a `ssize_t` value from little-endian to host byte order.
`GSSIZE_TO_BE(value)`
: Converts a `ssize_t` value from host byte order to big-endian.
`GSSIZE_TO_LE(value)`
: Converts a `ssize_t` value from host byte order to little-endian.
`GINT16_FROM_BE(value)`
: Converts an `int16_t` value from big-endian to host byte order.
`GINT16_FROM_LE(value)`
: Converts an `int16_t` value from little-endian to host byte order.
`GINT16_TO_BE(value)`
: Converts an `int16_t` value from host byte order to big-endian.
`GINT16_TO_LE(value)`
: Converts an `int16_t` value from host byte order to little-endian.
`GINT32_FROM_BE(value)`
: Converts an `int32_t` value from big-endian to host byte order.
`GINT32_FROM_LE(value)`
: Converts an `int32_t` value from little-endian to host byte order.
`GINT32_TO_BE(value)`
: Converts an `int32_t` value from host byte order to big-endian.
`GINT32_TO_LE(value)`
: Converts an `int32_t` value from host byte order to little-endian.
`GINT64_FROM_BE(value)`
: Converts an `int64_t` value from big-endian to host byte order.
`GINT64_FROM_LE(value)`
: Converts an `int64_t` value from little-endian to host byte order.
`GINT64_TO_BE(value)`
: Converts an `int64_t` value from host byte order to big-endian.
`GINT64_TO_LE(value)`
: Converts an `int64_t` value from host byte order to little-endian.
### Unsigned
`GUINT_FROM_BE(value)`
: Converts an `unsigned int` value from big-endian to host byte order.
`GUINT_FROM_LE(value)`
: Converts an `unsigned int` value from little-endian to host byte order.
`GUINT_TO_BE(value)`
: Converts an `unsigned int` value from host byte order to big-endian.
`GUINT_TO_LE(value)`
: Converts an `unsigned int` value from host byte order to little-endian.
`GULONG_FROM_BE(value)`
: Converts an `unsigned long` value from big-endian to host byte order.
`GULONG_FROM_LE(value)`
: Converts an `unsigned long` value from little-endian to host byte order.
`GULONG_TO_BE(value)`
: Converts an `unsigned long` value from host byte order to big-endian.
`GULONG_TO_LE(value)`
: Converts an `unsigned long` value from host byte order to little-endian.
`GSIZE_FROM_BE(value)`
: Converts a `size_t` value from big-endian to the host byte order.
`GSIZE_FROM_LE(value)`
: Converts a `size_t` value from little-endian to host byte order.
`GSIZE_TO_BE(value)`
: Converts a `size_t` value from host byte order to big-endian.
`GSIZE_TO_LE(value)`
: Converts a `size_t` value from host byte order to little-endian.
`GUINT16_FROM_BE(value)`
: Converts an `uint16_t` value from big-endian to host byte order.
`GUINT16_FROM_LE(value)`
: Converts an `uint16_t` value from little-endian to host byte order.
`GUINT16_TO_BE(value)`
: Converts an `uint16_t` value from host byte order to big-endian.
`GUINT16_TO_LE(value)`
: Converts an `uint16_t` value from host byte order to little-endian.
`GUINT32_FROM_BE(value)`
: Converts an `uint32_t` value from big-endian to host byte order.
`GUINT32_FROM_LE(value)`
: Converts an `uint32_t` value from little-endian to host byte order.
`GUINT32_TO_BE(value)`
: Converts an `uint32_t` value from host byte order to big-endian.
`GUINT32_TO_LE(value)`
: Converts an `uint32_t` value from host byte order to little-endian.
`GUINT64_FROM_BE(value)`
: Converts an `uint64_t` value from big-endian to host byte order.
`GUINT64_FROM_LE(value)`
: Converts an `uint64_t` value from little-endian to host byte order.
`GUINT64_TO_BE(value)`
: Converts an `uint64_t` value from host byte order to big-endian.
`GUINT64_TO_LE(value)`
: Converts an `uint64_t` value from host byte order to little-endian.
`GUINT16_SWAP_BE_PDP(value)`
: Converts an `uint16_t` value between big-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
`GUINT16_SWAP_LE_BE(value)`
: Converts an `uint16_t` value between little-endian and big-endian byte order.
The conversion is symmetric so it can be used both ways.
`GUINT16_SWAP_LE_PDP(value)`
: Converts an `uint16_t` value between little-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
`GUINT32_SWAP_BE_PDP(value)`
: Converts an `uint32_t` value between big-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
`GUINT32_SWAP_LE_BE(value)`
: Converts an `uint32_t` value between little-endian and big-endian byte order.
The conversion is symmetric so it can be used both ways.
`GUINT32_SWAP_LE_PDP(value)`
: Converts an `uint32_t` value between little-endian and pdp-endian byte order.
The conversion is symmetric so it can be used both ways.
`GUINT64_SWAP_LE_BE(value)`
: Converts a `uint64_t` value between little-endian and big-endian byte order.
The conversion is symmetric so it can be used both ways.

88
docs/reference/glib/cross-compiling.md Normal file
View File

@ -0,0 +1,88 @@
Title: Cross-compiling the GLib package
# Cross-compiling the GLib Package
## Building the Library for a different architecture
Cross-compilation is the process of compiling a program or library on a
different architecture or operating system then it will be run upon. GLib is
slightly more difficult to cross-compile than many packages because much of
GLib is about hiding differences between different systems.
These notes cover things specific to cross-compiling GLib; for general
information about cross-compilation, see the [Meson
documentation](http://mesonbuild.com/Cross-compilation.html).
GLib tries to detect as much information as possible about the target system
by compiling and linking programs without actually running anything;
however, some information GLib needs is not available this way. This
information needs to be provided to meson via a ‘cross file’.
As an example of using a cross file, to cross compile for the ‘MingW32’
Win64 runtime environment on a Linux system, create a file `cross_file.txt`
with the following contents:
```
[host_machine]
system = 'windows'
cpu_family = 'x86_64'
cpu = 'x86_64'
endian = 'little'
[properties]
c_args = []
c_link_args = []
[binaries]
c = 'x86_64-w64-mingw32-gcc'
cpp = 'x86_64-w64-mingw32-g++'
ar = 'x86_64-w64-mingw32-ar'
ld = 'x86_64-w64-mingw32-ld'
objcopy = 'x86_64-w64-mingw32-objcopy'
strip = 'x86_64-w64-mingw32-strip'
pkgconfig = 'x86_64-w64-mingw32-pkg-config'
windres = 'x86_64-w64-mingw32-windres'
```
Then execute the following commands:
meson setup --cross-file cross_file.txt builddir
The complete list of cross properties follows. Most of these won't need to
be set in most cases.
## Cross properties
`have_[function]`
: When meson checks if a function is supported, the test can be overridden by
setting the `have_function` property to `true` or `false`. For example:
Checking for function "fsync" : YES
can be overridden by setting
have_fsync = false
`growing_stack=[true/false]`
: Whether the stack grows up or down. Most places will want `false`. A few
architectures, such as PA-RISC need `true`.
`have_strlcpy=[true/false]`
: Whether you have `strlcpy()` that matches OpenBSD. Defaults to `false`,
which is safe, since GLib uses a built-in version in that case.
`va_val_copy=[true/false]`
: Whether `va_list` can be copied as a pointer. If set to `false`, then
`memcopy()` will be used. Only matters if you don't have `va_copy()` or
`__va_copy()`. (So, doesn't matter for GCC.) Defaults to `true` which is
slightly more common than `false`.
`have_c99_vsnprintf=[true/false]`
: Whether you have a `vsnprintf()` with C99 semantics. (C99 semantics means
returning the number of bytes that would have been written had the output
buffer had enough space.) Defaults to `false`.
`have_c99_snprintf=[true/false]`
: Whether you have a `snprintf()` with C99 semantics. (C99 semantics means
returning the number of bytes that would have been written had the output
buffer had enough space.) Defaults to `false`.

Some files were not shown because too many files have changed in this diff Show More