for OSTree 2013.6


I. OSTree Overview
Introduction
Comparison with "package managers"
Comparison with block/image replication
Atomic transitions between parallel-installable read-only filesystem trees
II. Anatomy of an OSTree repository
Core object types and data model
Repository types and locations
Refs
III. Deployments
Overview
"osname": Group of deployments that share /var
Contents of a deployment
The system /boot
IV. Atomic Upgrades
You can turn off the power anytime you want...
Simple upgrades via HTTP
Upgrades via external tools (e.g. package managers)
Assembling a new deployment directory
Atomically swapping boot configuration
V. Adapting existing mainstream distributions
System layout
Booting and initramfs technology
/lib/passwd
Adapting existing package managers
API Reference
Core repository-independent functions — Create, validate, and convert core data types
Content-addressed object store — A git-like storage system for operating system binaries
API Index

Part I. OSTree Overview

Introduction

OSTree is best summarized in a single sentence as "git for operating system binaries". At its core architecture is a userspace content-addressed filesystem, and layered on top of that is an administrative layer that is designed to atomically parallel install multiple bootable Unix-like operating systems.

While it takes over some of the roles of tradtional "package managers" like dpkg and rpm, it is not a package system; nor is it a tool for managing full disk images. Instead, OSTree sits between those levels, offering a blend of the advantages (and disadvantages) of both.

Comparison with "package managers"

Because OSTree is designed for deploying core operating systems, a comparison with traditional "package managers" such as dpkg and rpm is illustrative. Packages are traditionally composed of partial filesystem trees with metadata and scripts attached, and these are dynamically assembled on the client machine, after a process of dependency resolution.

In contrast, OSTree only supports recording and deploying complete (bootable) filesystem trees. It has no built-in knowledge of how a given filesystem tree was generated or the origin of individual files, or dependencies, descriptions of individual components. This means that, for example, if you are distributing software which is licensed under the GNU General Public License, the burden lies with the tool generating these filesystem trees to ensure sufficent metadata is included for compliance.

The OSTree core emphasizes replicating read-only OS trees via HTTP, and where the OS includes (if desired) an entirely separate mechanism to install applications, stored in /var if they're system global, or /home for per-user application installation.

However, it is entirely possible to use OSTree underneath a package system, where the contents of /usr are computed on the client. For example, when installing a package, rather than mutating the currently running filesystem, the package manager could assemble a new filesystem tree that includes the new package, record it in the local OSTree repository, and then set it up for the next boot. To support this model, OSTree provides an (introspectable) C shared library.

Comparison with block/image replication

OSTree shares some similarity with "dumb" replication and stateless deployments, such as the model common in "cloud" deployments where nodes are booted from an (effectively) readonly disk, and user data is kept on a different volumes. The advantage of "dumb" replication, shared by both OSTree and the cloud model, is that it's reliable and predictable.

But unlike many default image-based deployments, OSTree supports exactly two persistent writable directories that are preserved across upgrades: /etc and /var.

Because OSTree operates at the Unix filesystem layer, it works on top of any filesystem or block storage layout; it's possible to replicate a given filesystem tree from an OSTree repository into plain ext4, BTRFS, XFS, or in general any Unix-compatible filesystem that supports hard links. Note: OSTree will transparently take advantage of some BTRFS features if deployed on it.

Atomic transitions between parallel-installable read-only filesystem trees

Another deeply fundamental difference between both package managers and image-based replication is that OSTree is designed to parallel-install multiple versions of multiple independent operating systems. OSTree relies on a new toplevel ostree directory; it can in fact parallel install inside an existing OS or distribution occupying the physical / root.

On each client machine, there is an OSTree repository stored in /ostree/repo, and a set of "deployments" stored in /ostree/deploy/OSNAME/CHECKSUM. Each deployment is primarily composed of a set of hardlinks into the repository. This means each version is deduplicated; an upgrade process only costs disk space proportional to the new files, plus some constant overhead.

The model OSTree emphasizes is that the OS read-only content is kept in the classic Unix /usr; it comes with code to create a Linux read-only bind mount to prevent inadvertent corruption. There is exactly one /var writable directory shared between each deployment for a given OS. The OSTree core code does not touch content in this directory; it is up to the code in each operating system for how to manage and upgrade state.

Finally, each deployment has its own writable copy of the configuration store /etc. On upgrade, OSTree will perform a basic 3-way diff, and apply any local changes to the new copy, while leaving the old untouched.

Part II. Anatomy of an OSTree repository

Core object types and data model

OSTree is deeply inspired by git; the core layer is a userspace content-addressed versioning filesystem. It is worth taking some time to familiarize yourself with Git Internals, as this section will assume some knowledge of how git works.

Its object types are similar to git; it has commit objects and content objects. Git has "tree" objects, whereas OSTree splits them into "dirtree" and "dirmeta" objects. But unlike git, OSTree's checksums are SHA256. And most crucially, its content objects include uid, gid, and extended attributes (but still no timestamps).

Commit objects

A commit object contains metadata such as a timestamp, a log message, and most importantly, a reference to a dirtree/dirmeta pair of checksums which describe the root directory of the filesystem.

Also like git, each commit in OSTree can have a parent. It is designed to store a history of your binary builds, just like git stores a history of source control. However, OSTree also makes it easy to delete data, under the assumption that you can regenerate it from source code.

Dirtree objects

A dirtree contains a sorted array of (filename, checksum) pairs for content objects, and a second sorted array of (filename, dirtree checksum, dirmeta checksum), which are subdirectories.

Dirmeta objects

In git, tree objects contain the metadata such as permissions for their children. But OSTree splits this into a separate object to avoid duplicating extended attribute listings.

Content objects

Unlike the first three object types which are metadata, designed to be mmap()ed, the content object has a separate internal header and payload sections. The header contains uid, gid, mode, and symbolic link target (for symlinks), as well as extended attributes. After the header, for regular files, the content follows.

Repository types and locations

Also unlike git, an OSTree repository can be in one of two separate modes: bare and archive-z2. A bare repository is one where content files are just stored as regular files; it's designed to be the source of a "hardlink farm", where each operating system checkout is merely links into it. If you want to store files owned by e.g. root in this mode, you must run OSTree as root. In contrast, the archive-z2 mode is designed for serving via plain HTTP. Like tar files, it can be read/written by non-root users.

On an OSTree-deployed system, the "system repository" is /ostree/repo. It can be read by any uid, but only written by root. Unless the --repo argument is given to the ostree command, it will operate on the system repository.

Refs

Like git, OSTree uses "refs" to which are text files that point to particular commits (i.e. filesystem trees). For example, the gnome-ostree operating system creates trees named like gnome-ostree/buildmaster/x86_64-runtime and gnome-ostree/buildmaster/x86_64-devel-debug. These two refs point to two different generated filesystem trees. In this example, the "runtime" tree contains just enough to run a basic GNOME system, and "devel-debug" contains all of the developer tools.

The ostree supports a simple syntax using the carat ^ to refer to the parent of a given commit. For example, gnome-ostree/buildmaster/x86_64-runtime^ refers to the previous build, and gnome-ostree/buildmaster/x86_64-runtime^^ refers to the one before that.

Part III. Deployments

Overview

Built on top of the OSTree versioning filesystem core is a layer that knows how to deploy, parallel install, and manage Unix-like operating systems (accessible via ostree admin). The core content of these operating systems are treated as read-only, but they transparently share storage.

A deployment is physically located at a path of the form /ostree/deploy/osname/deploy/checksum. OSTree is designed to boot directly into exactly one deployment at a time; each deployment is intended to be a target for chroot() or equivalent.

"osname": Group of deployments that share /var

Each deployment is grouped in exactly one "osname". From above, you can see that an osname is physically represented in the /ostree/deploy/osname directory. For example, OSTree can allow parallel installing Debian in /ostree/deploy/debian and Red Hat Enterprise Linux in /ostree/deploy/rhel (subject to operating system support, present released versions of these operating systems may not support this).

Each osname has exactly one copy of the traditional Unix /var, stored physically in /ostree/deploy/osname/var. OSTree provides support tools for systemd to create a Linux bind mount that ensures the booted deployment sees the shared copy of /var.

OSTree does not touch the contents of /var. Operating system components such as daemon services are required to create any directories they require there at runtime (e.g. /var/cache/daemonname), and to manage upgrading data formats inside those directories.

Contents of a deployment

A deployment begins with a specific commit (represented as a SHA256 hash) in the OSTree repository in /ostree/repo. This commit refers to a filesystem tree that represents the underlying basis of a deployment. For short, we will call this the "tree", to distinguish it from the concept of a deployment.

First, the tree must include a kernel stored as /boot/vmlinuz-checksum. The checksum should be a SHA256 hash of the kernel contents; it must be pre-computed before storing the kernel in the repository. Optionally, the tree can contain an initramfs, stored as /boot/initramfs-checksum. If this exists, the checksum must include both the kernel and initramfs contents. OSTree will use this to determine which kernels are shared. The rationale for this is to avoid computing checksums on the client by default.

The deployment should not have a traditional UNIX /etc; instead, it should include /usr/etc. This is the "default configuration". When OSTree creates a deployment, it performs a 3-way merge using the old default configuration, the active system's /etc, and the new default configuration. In the final filesystem tree for a deployment then, /etc is a regular writable directory.

Besides the exceptions of /var and /etc then, the rest of the contents of the tree are checked out as hard links into the repository. It's strongly recommended that operating systems ship all of their content in /usr, but this is not a hard requirement.

Finally, a deployment may have a .origin file, stored next to its directory. This file tells ostree admin upgrade how to upgrade it. At the moment, OSTree only supports upgrading a single refspec. However, in the future OSTree may support a syntax for composing layers of trees, for example.

The system /boot

While OSTree parallel installs deployments cleanly inside the /ostree directory, ultimately it has to control the system's /boot directory. The way this works is via the boot loader specification, which is a standard for bootloader-independent drop-in configuration files.

When a tree is deployed, it will have a configuration file generated of the form /boot/loader/entries/ostree-osname-checksum.serial.conf. This configuration file will include a special ostree= kernel argument that allows the initramfs to find (and chroot() into) the specified deployment.

At present, not all bootloaders implement the BootLoaderSpec, so OSTree contains code for some of these to regenerate native config files (such as /boot/syslinux/syslinux.conf based on the entries.

Part IV. Atomic Upgrades

You can turn off the power anytime you want...

At the time of this writing, it's common for released versions of mainstream operating systems (the Playstation OS, Microsoft Windows, Debian GNU/Linux, and Red Hat Enterprise Linux) to have non-atomic upgrades; that is, the good ones pop up a screen that says "Please do not turn off the power". The bad ones don't even tell you that it's unsafe. The really bad ones actually mutate your running filesystem without taking precautions to prevent corrupting running processes.

In contrast, OSTree is designed to implement fully atomic and safe upgrades; more generally, atomic transitions between lists of bootable deployments. If the system crashes or you pull the power, you will have either the old system, or the new one.

Simple upgrades via HTTP

First, the most basic model OSTree supports is one where it replicates pre-generated filesystem trees from a server over HTTP, tracking exactly one ref, which is stored in the .origin file for the deployment. The command ostree admin upgrade implements this.

To begin a simple upgrade, OSTree fetches the contents of the ref from the remote server. Suppose we're tracking a ref named gnome-ostree/buildmaster/x86_64-runtime. OSTree fetches the URL http://example.com/repo/refs/gnome-ostree/buildmaster/x86_64-runtime, which contains a SHA256 checksum. This determines the tree to deploy, and /etc will be merged from currently booted tree.

If we do not have this commit, then, then we perform a pull process. At present (without static deltas), this involves quite simply just fetching each individual object that we do not have, asynchronously. Put in other words, we only download changed files (zlib-compressed). Each object has its checksum validated and is stored in /ostree/repo/objects/.

Once the pull is complete, we have all the objects locally we need to perform a deployment.

Upgrades via external tools (e.g. package managers)

As mentioned in the introduction, OSTree is also designed to allow a model where filesystem trees are computed on the client. It is completely agnostic as to how those trees are generated; they could be computed with traditional packages, packages with post-deployment scripts on top, or built by developers directly from revision control locally, etc.

At a practical level, most package managers today (dpkg and rpm) operate "live" on the currently booted filesystem. The way they could work with OSTree is instead to take the list of installed packages in the currently booted tree, and compute a new filesystem from that. A later chapter describes in more details how this could work: Part V, “Adapting existing mainstream distributions”.

For the purposes of this section, let's assume that we have a newly generated filesystem tree stored in the repo (which shares storage with the existing booted tree). We can then move on to checking it back out of the repo into a deployment.

Assembling a new deployment directory

Given a commit to deploy, OSTree first allocates a directory for it. This is of the form /boot/loader/entries/ostree-osname-checksum.serial.conf. The serial is normally 0, but if a given commit is deployed more than once, it will be incremented. This is supported because the previous deployment may have configuration in /etc that we do not want to use or overwrite.

Now that we have a deployment directory, a 3-way merge is performed between the (by default) currently booted deployment's /etc, its default configuration, and the new deployment (based on its /usr/etc).

Atomically swapping boot configuration

At this point, a new deployment directory has been created as a hardlink farm; the running system is untouched, and the bootloader configuration is untouched. We want to add this deployment to the "deployment list".

To support a more general case, OSTree supports atomic transitioning between arbitrary sets of deployments, with the restriction that the currently booted deployment must always be in the new set. In the normal case, we have exactly one deployment, which is the booted one, and we want to add the new deployment to the list. A more complex command might allow creating 100 deployments as part of one atomic transaction, so that one can set up an automated system to bisect across them.

The bootversion

OSTree allows swapping between boot configurations by implementing the "swapped directory pattern" in /boot. This means it is a symbolic link to one of two directories /ostree/boot.[0|1]. To swap the contents atomically, if the current version is 0, we create /ostree/boot.1, populate it with the new contents, then atomically swap the symbolic link. Finally, the old contents can be garbage collected at any point.

The /ostree/boot directory

However, we want to optimize for the case where we the set of kernel/initramfs pairs is the same between both the old and new deployment lists. This happens when doing an upgrade that does not include the kernel; think of a simple translation update. OSTree optimizes for this case because on some systems /boot may be on a separate medium such as flash storage not optimized for significant amounts of write traffic.

To implement this, OSTree also maintains the directory /ostree/boot.bootversion, which is a set of symbolic links to the deployment directories. The bootversion here must match the version of /boot. However, in order to allow atomic transitions of this directory, this is also a swapped directory, so just like /boot, it has a version of 0 or 1 appended.

Each bootloader entry has a special ostree= argument which refers to one of these symbolic links. This is parsed at runtime in the initramfs.

Part V. Adapting existing mainstream distributions

System layout

First, OSTree encourages systems to implement UsrMove. This is simply to avoid the need for more bind mounts. By default OSTree's dracut hook creates a read-only bind mount over /usr; you can of course generate individual bind-mounts for /bin, all the /lib variants, etc. So it is not intended to be a hard requirement.

Remember, because by default the system is booted into a chroot equivalent, there has to be some way to refer to the actual physical root filesystem. Therefore, your operating system tree should contain an empty /sysroot directory; at boot time, OSTree will make this a bind mount to the physical / root directory. There is precedent for this name in the initramfs context. You should furthermore make a toplevel symbolic link /ostree which points to /sysroot/ostree, so that the OSTree tool at runtime can consistently find the system data regardless of whether it's operating on a physical root or inside a deployment.

Because OSTree only preserves /var across upgrades (each deployment's chroot directory will be garbage collected eventually), you will need to choose how to handle other toplevel writable directories specified by the Filesystem Hierarchy Standard. Your operating system may of course choose not to support some of these such as /usr/local, but following is the recommended set:

  • /home to /var/home

  • /opt to /var/opt

  • /srv to /var/srv

  • /root to /var/roothome

  • /usr/local to /var/local

  • /mnt to /var/mnt

  • /tmp to /sysroot/tmp

Furthermore, since /var is empty by default, your operating system will need to dynamically create the targets of these at boot. A good way to do this is using systemd-tmpfiles, if your OS uses systemd. For example:

      
d /var/log/journal 0755 root root -
L /var/home - - - - ../sysroot/home
d /var/opt 0755 root root -
d /var/srv 0755 root root -
d /var/roothome 0700 root root -
d /var/usrlocal 0755 root root -
d /var/usrlocal/bin 0755 root root -
d /var/usrlocal/etc 0755 root root -
d /var/usrlocal/games 0755 root root -
d /var/usrlocal/include 0755 root root -
d /var/usrlocal/lib 0755 root root -
d /var/usrlocal/man 0755 root root -
d /var/usrlocal/sbin 0755 root root -
d /var/usrlocal/share 0755 root root -
d /var/usrlocal/src 0755 root root -
d /var/mnt 0755 root root -
d /run/media 0755 root root -
      

Particularly note here the double indirection of /home. By default, each deployment will share the global toplevel /home directory on the physical root filesystem. It is then up to higher levels of management tools to keep /etc/passwd or equivalent synchronized between operating systems.

Each deployment can easily be reconfigured to have its own home directory set simply by making /var/home a real directory.

Booting and initramfs technology

OSTree comes with optional dracut+systemd integration code that parses the ostree= kernel command line argument in the initramfs, and then sets up the read-only bind mount on /usr, a bind mount on the deployment's /sysroot to the physical /, and then finally uses mount(MS_MOVE) to make the deployment root appear to be the root filesystem before telling systemd to switch root.

If you are not using dracut or systemd, using OSTree should still be possible, but you will have to write the integration code. Patches to support other initramfs technologies and init systems, if sufficiently clean, will likely be accepted upstream.

A further specific note regarding sysvinit: OSTree used to support recording device files such the /dev/initctl FIFO, but no longer does. It's recommended to just patch your initramfs to create this at boot.

/lib/passwd

In order to ship an OS that contains both system users and users dynamically created on client machines, you will need to choose a solution for /etc/passwd. The core problem is that if you add a user to the system for a daemon, the OSTree upgrade process for /etc will simply notice that because /etc/passwd differs from the previous default, it will keep the modified config file, and your new OS user will not be visible.

The solution chosen for the gnome-ostree operating system is to create /lib/passwd, and to include a NSS module nss-altfiles which instructs glibc to read from it. Then, the build system places all system users there, freeing up /etc/passwd to be purely a database of local users.

Adapting existing package managers

The largest endeavor is likely to be redesigning your distribution's package manager to be on top of OSTree, particularly if you want to keep compatibility with the "old way" of installing into the physical /. This section will use examples from both dpkg and rpm as the author has familiarity with both; but the abstract concepts should apply to most traditional package managers.

There are many levels of possible integration; initially, we will describe the most naive implementation which is the simplest but also the least efficient. We will assume here that the admin is booted into an OSTree-enabled system, and wants to add a set of packages.

Many package managers store their state in /var; but since in the OSTree model that directory is shared between independent versions, the package database must first be found in the per-deployment /usr directory. It becomes read-only; remember, all upgrades involve constructing a new filesystem tree, so your package manager will also need to create a copy of its database. Most likely, if you want to continue supporting non-OSTree deployments, simply have your package manager fall back to the legacy /var location if the one in /usr is not found.

To install a set of new packages (without removing any existing ones), enumerate the set of packages in the currently booted deployment, and perform dependency resolution to compute the complete set of new packages. Download and unpack these new packages to a temporary directory.

Now, because we are merely installing new packages and not removing anything, we can make the major optimization of reusing our existing filesystem tree, and merely layering the composed filesystem tree of these new packages on top. A command lke this: ostree commit -b osname/releasename/description --tree=ref=osname/releasenamename/description --tree=dir=/var/tmp/newpackages.13A8D0/ will create a new commit in the osname/releasename/description branch. The OSTree SHA256 checksum of all the files in /var/tmp/newpackages.13A8D0/ will be computed, but we will not re-checksum the present existing tree. In this layering model, earlier directories will take precedence, but files in later layers will silently override earlier layers.

Then to actually deploy this tree for the next boot: ostree admin deploy osname/releasenamename/description

API Reference

Core repository-independent functions — Create, validate, and convert core data types
Content-addressed object store — A git-like storage system for operating system binaries
API Index

Core repository-independent functions

Core repository-independent functions — Create, validate, and convert core data types

Synopsis

#define             OSTREE_MAX_METADATA_SIZE
#define             OSTREE_MAX_RECURSION
enum                OstreeObjectType;
#define             OSTREE_OBJECT_TYPE_IS_META          (t)
#define             OSTREE_OBJECT_TYPE_LAST
#define             OSTREE_FILE_HEADER_GVARIANT_FORMAT
#define             OSTREE_DIRMETA_GVARIANT_FORMAT
#define             OSTREE_TREE_GVARIANT_FORMAT
#define             OSTREE_COMMIT_GVARIANT_FORMAT
#define             OSTREE_ZLIB_FILE_HEADER_GVARIANT_FORMAT
const GVariantType * ostree_metadata_variant_type       (OstreeObjectType objtype);
gboolean            ostree_validate_checksum_string     (const char *sha256,
                                                         GError **error);
guchar *            ostree_checksum_to_bytes            (const char *checksum);
GVariant *          ostree_checksum_to_bytes_v          (const char *checksum);
char *              ostree_checksum_from_bytes          (const guchar *csum);
char *              ostree_checksum_from_bytes_v        (GVariant *csum_v);
void                ostree_checksum_inplace_from_bytes  (const guchar *csum,
                                                         char *buf);
void                ostree_checksum_inplace_to_bytes    (const char *checksum,
                                                         guchar *buf);
const guchar *      ostree_checksum_bytes_peek          (GVariant *bytes);
int                 ostree_cmp_checksum_bytes           (const guchar *a,
                                                         const guchar *b);
gboolean            ostree_validate_rev                 (const char *rev,
                                                         GError **error);
gboolean            ostree_parse_refspec                (const char *refspec,
                                                         char **out_remote,
                                                         char **out_ref,
                                                         GError **error);
void                ostree_checksum_update_meta         (GChecksum *checksum,
                                                         GFileInfo *file_info,
                                                         GVariant *xattrs);
const char *        ostree_object_type_to_string        (OstreeObjectType objtype);
OstreeObjectType    ostree_object_type_from_string      (const char *str);
guint               ostree_hash_object_name             (gconstpointer a);
GVariant *          ostree_object_name_serialize        (const char *checksum,
                                                         OstreeObjectType objtype);
void                ostree_object_name_deserialize      (GVariant *variant,
                                                         const char **out_checksum,
                                                         OstreeObjectType *out_objtype);
char *              ostree_object_to_string             (const char *checksum,
                                                         OstreeObjectType objtype);
void                ostree_object_from_string           (const char *str,
                                                         gchar **out_checksum,
                                                         OstreeObjectType *out_objtype);
char *              ostree_get_relative_object_path     (const char *checksum,
                                                         OstreeObjectType type,
                                                         gboolean compressed);
gboolean            ostree_get_xattrs_for_file          (GFile *f,
                                                         GVariant **out_xattrs,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_set_xattrs                   (GFile *f,
                                                         GVariant *xattrs,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_map_metadata_file            (GFile *file,
                                                         OstreeObjectType expected_type,
                                                         GVariant **out_variant,
                                                         GError **error);
gboolean            ostree_write_variant_with_size      (GOutputStream *output,
                                                         GVariant *variant,
                                                         guint64 alignment_offset,
                                                         gsize *out_bytes_written,
                                                         GChecksum *checksum,
                                                         GCancellable *cancellable,
                                                         GError **error);
GVariant *          ostree_file_header_new              (GFileInfo *file_info,
                                                         GVariant *xattrs);
GVariant *          ostree_zlib_file_header_new         (GFileInfo *file_info,
                                                         GVariant *xattrs);
gboolean            ostree_file_header_parse            (GVariant *metadata,
                                                         GFileInfo **out_file_info,
                                                         GVariant **out_xattrs,
                                                         GError **error);
gboolean            ostree_zlib_file_header_parse       (GVariant *metadata,
                                                         GFileInfo **out_file_info,
                                                         GVariant **out_xattrs,
                                                         GError **error);
gboolean            ostree_content_stream_parse         (gboolean compressed,
                                                         GInputStream *input,
                                                         guint64 input_length,
                                                         gboolean trusted,
                                                         GInputStream **out_input,
                                                         GFileInfo **out_file_info,
                                                         GVariant **out_xattrs,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_content_file_parse           (gboolean compressed,
                                                         GFile *content_path,
                                                         gboolean trusted,
                                                         GInputStream **out_input,
                                                         GFileInfo **out_file_info,
                                                         GVariant **out_xattrs,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_write_file_header_update_checksum
                                                        (GOutputStream *out,
                                                         GVariant *variant,
                                                         GChecksum *checksum,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_raw_file_to_content_stream   (GInputStream *input,
                                                         GFileInfo *file_info,
                                                         GVariant *xattrs,
                                                         GInputStream **out_input,
                                                         guint64 *out_length,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_checksum_file_from_input     (GFileInfo *file_info,
                                                         GVariant *xattrs,
                                                         GInputStream *in,
                                                         OstreeObjectType objtype,
                                                         guchar **out_csum,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_checksum_file                (GFile *f,
                                                         OstreeObjectType objtype,
                                                         guchar **out_csum,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                ostree_checksum_file_async          (GFile *f,
                                                         OstreeObjectType objtype,
                                                         int io_priority,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            ostree_checksum_file_async_finish   (GFile *f,
                                                         GAsyncResult *result,
                                                         guchar **out_csum,
                                                         GError **error);
GVariant *          ostree_create_directory_metadata    (GFileInfo *dir_info,
                                                         GVariant *xattrs);
gboolean            ostree_create_file_from_input       (GFile *dest_file,
                                                         GFileInfo *finfo,
                                                         GVariant *xattrs,
                                                         GInputStream *input,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_create_temp_file_from_input  (GFile *dir,
                                                         const char *prefix,
                                                         const char *suffix,
                                                         GFileInfo *finfo,
                                                         GVariant *xattrs,
                                                         GInputStream *input,
                                                         GFile **out_file,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_create_temp_dir              (GFile *dir,
                                                         const char *prefix,
                                                         const char *suffix,
                                                         GFile **out_file,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_validate_structureof_objtype (guchar objtype,
                                                         GError **error);
gboolean            ostree_validate_structureof_csum_v  (GVariant *checksum,
                                                         GError **error);
gboolean            ostree_validate_structureof_checksum_string
                                                        (const char *checksum,
                                                         GError **error);
gboolean            ostree_validate_structureof_file_mode
                                                        (guint32 mode,
                                                         GError **error);
gboolean            ostree_validate_structureof_commit  (GVariant *commit,
                                                         GError **error);
gboolean            ostree_validate_structureof_dirtree (GVariant *dirtree,
                                                         GError **error);
gboolean            ostree_validate_structureof_dirmeta (GVariant *dirmeta,
                                                         GError **error);
gchar *             ostree_commit_get_parent            (GVariant *commit_variant);

Description

These functions implement repository-independent algorithms for operating on the core OSTree data formats, such as converting GFileInfo into a GVariant.

There are 4 types of objects; file, dirmeta, tree, and commit. The last 3 are metadata, and the file object is the only content object type.

All metadata objects are stored as GVariant (big endian). The rationale for this is the same as that of the ext{2,3,4} family of filesystems; most developers will be using LE, and so it's better to continually test the BE->LE swap.

The file object is a custom format in order to support streaming.

Details

OSTREE_MAX_METADATA_SIZE

#define OSTREE_MAX_METADATA_SIZE (1 << 26)

Maximum permitted size in bytes of metadata objects.


OSTREE_MAX_RECURSION

#define OSTREE_MAX_RECURSION (256)

Maximum depth of metadata.


enum OstreeObjectType

typedef enum {
  OSTREE_OBJECT_TYPE_FILE = 1,      /* .file */
  OSTREE_OBJECT_TYPE_DIR_TREE = 2,  /* .dirtree */
  OSTREE_OBJECT_TYPE_DIR_META = 3,  /* .dirmeta */
  OSTREE_OBJECT_TYPE_COMMIT = 4     /* .commit */
} OstreeObjectType;

Enumeration for core object types; OSTREE_OBJECT_TYPE_FILE is for content, the other types are metadata.

OSTREE_OBJECT_TYPE_FILE

Content; regular file, symbolic link

OSTREE_OBJECT_TYPE_DIR_TREE

List of children (trees or files), and metadata

OSTREE_OBJECT_TYPE_DIR_META

Directory metadata

OSTREE_OBJECT_TYPE_COMMIT

Toplevel object, refers to tree and dirmeta for root

OSTREE_OBJECT_TYPE_IS_META()

#define OSTREE_OBJECT_TYPE_IS_META(t) (t >= 2 && t <= 4)

t :

An OstreeObjectType

Returns :

TRUE if object type is metadata

OSTREE_OBJECT_TYPE_LAST

#define OSTREE_OBJECT_TYPE_LAST OSTREE_OBJECT_TYPE_COMMIT

Last valid object type; use this to validate ranges.


OSTREE_FILE_HEADER_GVARIANT_FORMAT

#define OSTREE_FILE_HEADER_GVARIANT_FORMAT G_VARIANT_TYPE ("(uuuusa(ayay))")

File objects are stored as a stream, with one GVariant header, followed by content.

The file header is of the following form:

<BE guint32 containing variant length> u - uid u - gid u - mode u - rdev s - symlink target a(ayay) - xattrs

Then the rest of the stream is data.


OSTREE_DIRMETA_GVARIANT_FORMAT

#define OSTREE_DIRMETA_GVARIANT_FORMAT G_VARIANT_TYPE ("(uuua(ayay))")

u - uid u - gid u - mode a(ayay) - xattrs


OSTREE_TREE_GVARIANT_FORMAT

#define OSTREE_TREE_GVARIANT_FORMAT G_VARIANT_TYPE ("(a(say)a(sayay))")

a(say) - array of (filename, checksum) for files a(sayay) - array of (dirname, tree_checksum, meta_checksum) for directories


OSTREE_COMMIT_GVARIANT_FORMAT

#define OSTREE_COMMIT_GVARIANT_FORMAT G_VARIANT_TYPE ("(a{sv}aya(say)sstayay)")

a{sv} - Metadata ay - parent checksum (empty string for initial) a(say) - Related objects s - subject s - body t - Timestamp in seconds since the epoch (UTC) ay - Root tree contents ay - Root tree metadata


OSTREE_ZLIB_FILE_HEADER_GVARIANT_FORMAT

#define OSTREE_ZLIB_FILE_HEADER_GVARIANT_FORMAT G_VARIANT_TYPE ("(tuuuusa(ayay))")

This is a variation on OSTREE_FILE_HEADER_GVARIANT_FORMAT, used for storing zlib-compressed content objects.

<BE guint32 containing variant length> t - size u - uid u - gid u - mode u - rdev s - symlink target a(ayay) - xattrs --- zlib-compressed data


ostree_metadata_variant_type ()

const GVariantType * ostree_metadata_variant_type       (OstreeObjectType objtype);

ostree_validate_checksum_string ()

gboolean            ostree_validate_checksum_string     (const char *sha256,
                                                         GError **error);

Use this function to see if input strings are checksums.

sha256 :

SHA256 hex string

error :

Error

Returns :

TRUE if sha256 is a valid checksum string, FALSE otherwise

ostree_checksum_to_bytes ()

guchar *            ostree_checksum_to_bytes            (const char *checksum);

checksum :

An ASCII checksum

Returns :

Binary checksum from checksum of length 32; free with g_free(). [transfer full][array fixed-size=32]

ostree_checksum_to_bytes_v ()

GVariant *          ostree_checksum_to_bytes_v          (const char *checksum);

checksum :

An ASCII checksum

Returns :

New GVariant of type ay with length 32. [transfer full]

ostree_checksum_from_bytes ()

char *              ostree_checksum_from_bytes          (const guchar *csum);

csum :

An binary checksum of length 32. [array fixed-size=32]

Returns :

String form of csum. [transfer full]

ostree_checksum_from_bytes_v ()

char *              ostree_checksum_from_bytes_v        (GVariant *csum_v);

csum_v :

GVariant of type ay

Returns :

String form of csum_bytes. [transfer full]

ostree_checksum_inplace_from_bytes ()

void                ostree_checksum_inplace_from_bytes  (const guchar *csum,
                                                         char *buf);

Overwrite the contents of buf with stringified version of csum.

csum :

An binary checksum of length 32. [array fixed-size=32]

buf :

Output location, must be at least 65 bytes in length

ostree_checksum_inplace_to_bytes ()

void                ostree_checksum_inplace_to_bytes    (const char *checksum,
                                                         guchar *buf);

Convert checksum from a string to binary in-place, without allocating memory. Use this function in hot code paths.

checksum :

a SHA256 string

buf :

Output buffer with at least 32 bytes of space

ostree_checksum_bytes_peek ()

const guchar *      ostree_checksum_bytes_peek          (GVariant *bytes);

bytes :

GVariant of type ay

Returns :

Binary checksum data in bytes; do not free. [transfer none]

ostree_cmp_checksum_bytes ()

int                 ostree_cmp_checksum_bytes           (const guchar *a,
                                                         const guchar *b);

Compare two binary checksums, using memcmp().

a :

A binary checksum

b :

A binary checksum

ostree_validate_rev ()

gboolean            ostree_validate_rev                 (const char *rev,
                                                         GError **error);

rev :

A revision string

error :

Error

Returns :

TRUE if rev is a valid ref string

ostree_parse_refspec ()

gboolean            ostree_parse_refspec                (const char *refspec,
                                                         char **out_remote,
                                                         char **out_ref,
                                                         GError **error);

Split a refspec like "gnome-ostree:gnome-ostree/buildmaster" into two parts; out_remote will be set to "gnome-ostree", and out_ref will be "gnome-ostree/buildmaster".

If refspec refers to a local ref, out_remote will be NULL.

refspec :

A "refspec" string

out_remote :

The remote name, or NULL if the refspec refs to a local ref. [out][allow-none]

out_ref :

Name of ref. [out][allow-none]

error :

Error

ostree_checksum_update_meta ()

void                ostree_checksum_update_meta         (GChecksum *checksum,
                                                         GFileInfo *file_info,
                                                         GVariant *xattrs);

ostree_object_type_to_string ()

const char *        ostree_object_type_to_string        (OstreeObjectType objtype);

Serialize objtype to a string; this is used for file extensions.

objtype :

an OstreeObjectType

ostree_object_type_from_string ()

OstreeObjectType    ostree_object_type_from_string      (const char *str);

The reverse of ostree_object_type_to_string().

str :

A stringified version of OstreeObjectType

ostree_hash_object_name ()

guint               ostree_hash_object_name             (gconstpointer a);

Use this function with GHashTable and ostree_object_name_serialize().

a :

A GVariant containing a serialized object

ostree_object_name_serialize ()

GVariant *          ostree_object_name_serialize        (const char *checksum,
                                                         OstreeObjectType objtype);

checksum :

An ASCII checksum

objtype :

An object type

Returns :

A new floating GVariant containing checksum string and objtype. [transfer floating]

ostree_object_name_deserialize ()

void                ostree_object_name_deserialize      (GVariant *variant,
                                                         const char **out_checksum,
                                                         OstreeObjectType *out_objtype);

Reverse ostree_object_name_serialize(). Note that out_checksum is only valid for the lifetime of variant, and must not be freed.

variant :

A GVariant of type (su)

out_checksum :

Pointer into string memory of variant with checksum. [out][transfer none]

out_objtype :

Return object type. [out]

ostree_object_to_string ()

char *              ostree_object_to_string             (const char *checksum,
                                                         OstreeObjectType objtype);

checksum :

An ASCII checksum

objtype :

Object type

Returns :

A string containing both checksum and a stringifed version of objtype

ostree_object_from_string ()

void                ostree_object_from_string           (const char *str,
                                                         gchar **out_checksum,
                                                         OstreeObjectType *out_objtype);

Reverse ostree_object_to_string().

str :

An ASCII checksum

out_checksum :

Parsed checksum. [out][transfer full]

out_objtype :

Parsed object type. [out]

ostree_get_relative_object_path ()

char *              ostree_get_relative_object_path     (const char *checksum,
                                                         OstreeObjectType type,
                                                         gboolean compressed);

checksum :

ASCII checksum string

type :

Object type

compressed :

Whether or not the repository object is compressed

Returns :

Relative path for a loose object. [transfer full]

ostree_get_xattrs_for_file ()

gboolean            ostree_get_xattrs_for_file          (GFile *f,
                                                         GVariant **out_xattrs,
                                                         GCancellable *cancellable,
                                                         GError **error);

Read all extended attributes of f in a canonical sorted order, and set out_xattrs with the result.

If the filesystem does not support extended attributes, out_xattrs will have 0 elements, and this function will return successfully.

f :

a GFile

out_xattrs :

A new GVariant containing the extended attributes. [out]

cancellable :

Cancellable

error :

Error

ostree_set_xattrs ()

gboolean            ostree_set_xattrs                   (GFile *f,
                                                         GVariant *xattrs,
                                                         GCancellable *cancellable,
                                                         GError **error);

For each attribute in xattrs, replace the value (if any) of f for that attribute. This function does not clear other existing attributes.

f :

a file

xattrs :

Extended attribute list

cancellable :

Cancellable

error :

Error

ostree_map_metadata_file ()

gboolean            ostree_map_metadata_file            (GFile *file,
                                                         OstreeObjectType expected_type,
                                                         GVariant **out_variant,
                                                         GError **error);

ostree_write_variant_with_size ()

gboolean            ostree_write_variant_with_size      (GOutputStream *output,
                                                         GVariant *variant,
                                                         guint64 alignment_offset,
                                                         gsize *out_bytes_written,
                                                         GChecksum *checksum,
                                                         GCancellable *cancellable,
                                                         GError **error);

Use this function for serializing a chain of 1 or more variants into a stream; the alignment_offset parameter is used to ensure that each variant begins on an 8-byte alignment so it can be safely accessed.

output :

Stream

variant :

A variant

alignment_offset :

Used to determine whether or not we should write padding bytes

out_bytes_written :

Number of bytes written. [out]

checksum :

If provided, update with written data. [allow-none]

cancellable :

Cancellable

error :

Error

ostree_file_header_new ()

GVariant *          ostree_file_header_new              (GFileInfo *file_info,
                                                         GVariant *xattrs);

ostree_zlib_file_header_new ()

GVariant *          ostree_zlib_file_header_new         (GFileInfo *file_info,
                                                         GVariant *xattrs);

file_info :

a GFileInfo

xattrs :

Optional extended attribute array. [allow-none]

Returns :

A new GVariant containing file header for an archive-z2 repository. [transfer full]

ostree_file_header_parse ()

gboolean            ostree_file_header_parse            (GVariant *metadata,
                                                         GFileInfo **out_file_info,
                                                         GVariant **out_xattrs,
                                                         GError **error);

Load file header information into standard Gio GFileInfo object, along with extended attributes tored in out_xattrs.

metadata :

A metadata variant of type OSTREE_FILE_HEADER_GVARIANT_FORMAT

out_file_info :

Parsed file information. [out]

out_xattrs :

Parsed extended attribute set. [out]

error :

Error

ostree_zlib_file_header_parse ()

gboolean            ostree_zlib_file_header_parse       (GVariant *metadata,
                                                         GFileInfo **out_file_info,
                                                         GVariant **out_xattrs,
                                                         GError **error);

Like ostree_file_header_parse(), but operates on zlib-compressed content.

metadata :

A metadata variant of type OSTREE_FILE_HEADER_GVARIANT_FORMAT

out_file_info :

Parsed file information. [out]

out_xattrs :

Parsed extended attribute set. [out]

error :

Error

ostree_content_stream_parse ()

gboolean            ostree_content_stream_parse         (gboolean compressed,
                                                         GInputStream *input,
                                                         guint64 input_length,
                                                         gboolean trusted,
                                                         GInputStream **out_input,
                                                         GFileInfo **out_file_info,
                                                         GVariant **out_xattrs,
                                                         GCancellable *cancellable,
                                                         GError **error);

The reverse of ostree_raw_file_to_content_stream(); this function converts an object content stream back into components.

compressed :

Whether or not the stream is zlib-compressed

input :

Object content stream

input_length :

Length of stream

trusted :

If TRUE, assume the content has been validated

out_input :

The raw file content stream. [out]

out_file_info :

Normal metadata. [out]

out_xattrs :

Extended attributes. [out]

cancellable :

Cancellable

error :

Error

ostree_content_file_parse ()

gboolean            ostree_content_file_parse           (gboolean compressed,
                                                         GFile *content_path,
                                                         gboolean trusted,
                                                         GInputStream **out_input,
                                                         GFileInfo **out_file_info,
                                                         GVariant **out_xattrs,
                                                         GCancellable *cancellable,
                                                         GError **error);

A thin wrapper for ostree_content_stream_parse(); this function converts an object content stream back into components.

compressed :

Whether or not the stream is zlib-compressed

content_path :

Path to file containing content

trusted :

If TRUE, assume the content has been validated

out_input :

The raw file content stream. [out]

out_file_info :

Normal metadata. [out]

out_xattrs :

Extended attributes. [out]

cancellable :

Cancellable

error :

Error

ostree_write_file_header_update_checksum ()

gboolean            ostree_write_file_header_update_checksum
                                                        (GOutputStream *out,
                                                         GVariant *variant,
                                                         GChecksum *checksum,
                                                         GCancellable *cancellable,
                                                         GError **error);

Write a file header variant to the provided out stream, optionally updating checksum.

out :

Stream

variant :

A variant, should be a file header

checksum :

If provided, update with written data. [allow-none]

cancellable :

Cancellable

error :

Error

ostree_raw_file_to_content_stream ()

gboolean            ostree_raw_file_to_content_stream   (GInputStream *input,
                                                         GFileInfo *file_info,
                                                         GVariant *xattrs,
                                                         GInputStream **out_input,
                                                         guint64 *out_length,
                                                         GCancellable *cancellable,
                                                         GError **error);

Convert from a "bare" file representation into an OSTREE_OBJECT_TYPE_FILE stream. This is a fundamental operation for writing data to an OstreeRepo.

input :

File raw content stream

file_info :

A file info

xattrs :

Optional extended attributes. [allow-none]

out_input :

Serialized object stream. [out]

out_length :

Length of stream. [out]

cancellable :

Cancellable

error :

Error

ostree_checksum_file_from_input ()

gboolean            ostree_checksum_file_from_input     (GFileInfo *file_info,
                                                         GVariant *xattrs,
                                                         GInputStream *in,
                                                         OstreeObjectType objtype,
                                                         guchar **out_csum,
                                                         GCancellable *cancellable,
                                                         GError **error);

Compute the OSTree checksum for a given input.

file_info :

File information

xattrs :

Optional extended attributes. [allow-none]

in :

File content, should be NULL for symbolic links. [allow-none]

objtype :

Object type

out_csum :

Return location for binary checksum. [out][array fixed-size=32]

cancellable :

Cancellable

error :

Error

ostree_checksum_file ()

gboolean            ostree_checksum_file                (GFile *f,
                                                         OstreeObjectType objtype,
                                                         guchar **out_csum,
                                                         GCancellable *cancellable,
                                                         GError **error);

Compute the OSTree checksum for a given file.

f :

File path

objtype :

Object type

out_csum :

Return location for binary checksum. [out][array fixed-size=32]

cancellable :

Cancellable

error :

Error

ostree_checksum_file_async ()

void                ostree_checksum_file_async          (GFile *f,
                                                         OstreeObjectType objtype,
                                                         int io_priority,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously compute the OSTree checksum for a given file; complete with ostree_checksum_file_async_finish().

f :

File path

objtype :

Object type

io_priority :

Priority for operation, see G_IO_PRIORITY_DEFAULT

cancellable :

Cancellable

callback :

Invoked when operation is complete

user_data :

Data for callback

ostree_checksum_file_async_finish ()

gboolean            ostree_checksum_file_async_finish   (GFile *f,
                                                         GAsyncResult *result,
                                                         guchar **out_csum,
                                                         GError **error);

Finish computing the OSTree checksum for a given file; see ostree_checksum_file_async().

f :

File path

result :

Async result

out_csum :

Return location for binary checksum. [out][array fixed-size=32]

error :

Error

ostree_create_directory_metadata ()

GVariant *          ostree_create_directory_metadata    (GFileInfo *dir_info,
                                                         GVariant *xattrs);

dir_info :

a GFileInfo containing directory information

xattrs :

Optional extended attributes. [allow-none]

Returns :

A new GVariant containing OSTREE_OBJECT_TYPE_DIR_META. [transfer full]

ostree_create_file_from_input ()

gboolean            ostree_create_file_from_input       (GFile *dest_file,
                                                         GFileInfo *finfo,
                                                         GVariant *xattrs,
                                                         GInputStream *input,
                                                         GCancellable *cancellable,
                                                         GError **error);

Create a directory, regular file, or symbolic link, based on finfo. Append extended attributes from xattrs if provided. For G_FILE_TYPE_REGULAR, set content based on input.

dest_file :

Destination; must not exist

finfo :

File information

xattrs :

Optional extended attributes. [allow-none]

input :

Optional file content, must be NULL for symbolic links. [allow-none]

cancellable :

Cancellable

error :

Error

ostree_create_temp_file_from_input ()

gboolean            ostree_create_temp_file_from_input  (GFile *dir,
                                                         const char *prefix,
                                                         const char *suffix,
                                                         GFileInfo *finfo,
                                                         GVariant *xattrs,
                                                         GInputStream *input,
                                                         GFile **out_file,
                                                         GCancellable *cancellable,
                                                         GError **error);

Like ostree_create_file_from_input(), but securely allocates a randomly-named target in dir. This is a unified version of mkstemp()/mkdtemp() that also supports symbolic links.

dir :

Target directory

prefix :

Optional prefix

suffix :

Optional suffix

finfo :

File information

xattrs :

Optional extended attributes. [allow-none]

input :

Optional file content, must be NULL for symbolic links. [allow-none]

out_file :

Path for newly created directory, file, or symbolic link. [out]

cancellable :

Cancellable

error :

Error

ostree_create_temp_dir ()

gboolean            ostree_create_temp_dir              (GFile *dir,
                                                         const char *prefix,
                                                         const char *suffix,
                                                         GFile **out_file,
                                                         GCancellable *cancellable,
                                                         GError **error);

Securely create a randomly-named temporary subdirectory of dir.

dir :

Use this as temporary base

prefix :

Optional prefix. [allow-none]

suffix :

Optional suffix. [allow-none]

out_file :

Path for newly created directory, file, or symbolic link. [out]

cancellable :

Cancellable

error :

Error

ostree_validate_structureof_objtype ()

gboolean            ostree_validate_structureof_objtype (guchar objtype,
                                                         GError **error);

error :

Error

Returns :

TRUE if objtype represents a valid object type

ostree_validate_structureof_csum_v ()

gboolean            ostree_validate_structureof_csum_v  (GVariant *checksum,
                                                         GError **error);

checksum :

a GVariant of type "ay"

error :

Error

Returns :

TRUE if checksum is a valid binary SHA256 checksum

ostree_validate_structureof_checksum_string ()

gboolean            ostree_validate_structureof_checksum_string
                                                        (const char *checksum,
                                                         GError **error);

checksum :

an ASCII string

error :

Error

Returns :

TRUE if checksum is a valid ASCII SHA256 checksum

ostree_validate_structureof_file_mode ()

gboolean            ostree_validate_structureof_file_mode
                                                        (guint32 mode,
                                                         GError **error);

mode :

A Unix filesystem mode

error :

Error

Returns :

TRUE if mode represents a valid file type and permissions

ostree_validate_structureof_commit ()

gboolean            ostree_validate_structureof_commit  (GVariant *commit,
                                                         GError **error);

Use this to validate the basic structure of commit, independent of any other objects it references.

commit :

A commit object, OSTREE_OBJECT_TYPE_COMMIT

error :

Error

Returns :

TRUE if commit is structurally valid

ostree_validate_structureof_dirtree ()

gboolean            ostree_validate_structureof_dirtree (GVariant *dirtree,
                                                         GError **error);

Use this to validate the basic structure of dirtree, independent of any other objects it references.

dirtree :

A dirtree object, OSTREE_OBJECT_TYPE_DIR_TREE

error :

Error

Returns :

TRUE if dirtree is structurally valid

ostree_validate_structureof_dirmeta ()

gboolean            ostree_validate_structureof_dirmeta (GVariant *dirmeta,
                                                         GError **error);

Use this to validate the basic structure of dirmeta.

dirmeta :

A dirmeta object, OSTREE_OBJECT_TYPE_DIR_META

error :

Error

Returns :

TRUE if dirmeta is structurally valid

ostree_commit_get_parent ()

gchar *             ostree_commit_get_parent            (GVariant *commit_variant);

commit_variant :

Variant of type OSTREE_OBJECT_TYPE_COMMIT

Returns :

Binary checksum with parent of commit_variant, or NULL if none

Content-addressed object store

Content-addressed object store — A git-like storage system for operating system binaries

Synopsis

enum                OstreeRepoMode;
OstreeRepo *        ostree_repo_new                     (GFile *path);
gboolean            ostree_repo_check                   (OstreeRepo *self,
                                                         GError **error);
GFile *             ostree_repo_get_path                (OstreeRepo *self);
OstreeRepoMode      ostree_repo_get_mode                (OstreeRepo *self);
gboolean            ostree_repo_mode_from_string        (const char *mode,
                                                         OstreeRepoMode *out_mode,
                                                         GError **error);
GKeyFile *          ostree_repo_get_config              (OstreeRepo *self);
GKeyFile *          ostree_repo_copy_config             (OstreeRepo *self);
OstreeRepo *        ostree_repo_get_parent              (OstreeRepo *self);
gboolean            ostree_repo_write_config            (OstreeRepo *self,
                                                         GKeyFile *new_config,
                                                         GError **error);
gboolean            ostree_repo_prepare_transaction     (OstreeRepo *self,
                                                         gboolean enable_commit_hardlink_scan,
                                                         gboolean *out_transaction_resume,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_commit_transaction      (OstreeRepo *self,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_commit_transaction_with_stats
                                                        (OstreeRepo *self,
                                                         guint *out_metadata_objects_total,
                                                         guint *out_metadata_objects_written,
                                                         guint *out_content_objects_total,
                                                         guint *out_content_objects_written,
                                                         guint64 *out_content_bytes_written,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_abort_transaction       (OstreeRepo *self,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_has_object              (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *checksum,
                                                         gboolean *out_have_object,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_stage_metadata          (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *expected_checksum,
                                                         GVariant *object,
                                                         guchar **out_csum,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                ostree_repo_stage_metadata_async    (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *expected_checksum,
                                                         GVariant *object,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            ostree_repo_stage_metadata_finish   (OstreeRepo *self,
                                                         GAsyncResult *result,
                                                         guchar **out_csum,
                                                         GError **error);
gboolean            ostree_repo_stage_metadata_trusted  (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *checksum,
                                                         GVariant *variant,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_stage_content           (OstreeRepo *self,
                                                         const char *expected_checksum,
                                                         GInputStream *object_input,
                                                         guint64 length,
                                                         guchar **out_csum,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_stage_content_trusted   (OstreeRepo *self,
                                                         const char *checksum,
                                                         GInputStream *object_input,
                                                         guint64 length,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                ostree_repo_stage_content_async     (OstreeRepo *self,
                                                         const char *expected_checksum,
                                                         GInputStream *object,
                                                         guint64 length,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            ostree_repo_stage_content_finish    (OstreeRepo *self,
                                                         GAsyncResult *result,
                                                         guchar **out_csum,
                                                         GError **error);
gboolean            ostree_repo_resolve_rev             (OstreeRepo *self,
                                                         const char *refspec,
                                                         gboolean allow_noent,
                                                         char **out_rev,
                                                         GError **error);
gboolean            ostree_repo_write_ref               (OstreeRepo *self,
                                                         const char *remote,
                                                         const char *name,
                                                         const char *rev,
                                                         GError **error);
gboolean            ostree_repo_write_refspec           (OstreeRepo *self,
                                                         const char *refspec,
                                                         const char *rev,
                                                         GError **error);
gboolean            ostree_repo_list_refs               (OstreeRepo *self,
                                                         const char *refspec_prefix,
                                                         GHashTable **out_all_refs,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_load_variant_c          (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const guchar *csum,
                                                         GVariant **out_variant,
                                                         GError **error);
gboolean            ostree_repo_load_variant            (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *sha256,
                                                         GVariant **out_variant,
                                                         GError **error);
gboolean            ostree_repo_load_variant_if_exists  (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *sha256,
                                                         GVariant **out_variant,
                                                         GError **error);
gboolean            ostree_repo_load_file               (OstreeRepo *self,
                                                         const char *checksum,
                                                         GInputStream **out_input,
                                                         GFileInfo **out_file_info,
                                                         GVariant **out_xattrs,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_load_object_stream      (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *checksum,
                                                         GInputStream **out_input,
                                                         guint64 *out_size,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_query_object_storage_size
                                                        (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *sha256,
                                                         guint64 *out_size,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_delete_object           (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *sha256,
                                                         GCancellable *cancellable,
                                                         GError **error);
enum                OstreeRepoCommitFilterResult;
OstreeRepoCommitFilterResult (*OstreeRepoCommitFilter)  (OstreeRepo *repo,
                                                         const char *path,
                                                         GFileInfo *file_info,
                                                         gpointer user_data);
typedef             OstreeRepoCommitModifier;
OstreeRepoCommitModifier * ostree_repo_commit_modifier_new
                                                        (OstreeRepoCommitModifierFlags flags,
                                                         OstreeRepoCommitFilter commit_filter,
                                                         gpointer user_data);
OstreeRepoCommitModifier * ostree_repo_commit_modifier_ref
                                                        (OstreeRepoCommitModifier *modifier);
void                ostree_repo_commit_modifier_unref   (OstreeRepoCommitModifier *modifier);
gboolean            ostree_repo_stage_directory_to_mtree
                                                        (OstreeRepo *self,
                                                         GFile *dir,
                                                         OstreeMutableTree *mtree,
                                                         OstreeRepoCommitModifier *modifier,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_stage_archive_to_mtree  (OstreeRepo *self,
                                                         GFile *archive,
                                                         OstreeMutableTree *tree,
                                                         OstreeRepoCommitModifier *modifier,
                                                         gboolean autocreate_parents,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_stage_mtree             (OstreeRepo *self,
                                                         OstreeMutableTree *mtree,
                                                         char **out_contents_checksum,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_stage_commit            (OstreeRepo *self,
                                                         const char *branch,
                                                         const char *parent,
                                                         const char *subject,
                                                         const char *body,
                                                         const char *root_contents_checksum,
                                                         const char *root_metadata_checksum,
                                                         char **out_commit,
                                                         GCancellable *cancellable,
                                                         GError **error);
enum                OstreeRepoCheckoutMode;
enum                OstreeRepoCheckoutOverwriteMode;
gboolean            ostree_repo_checkout_tree           (OstreeRepo *self,
                                                         OstreeRepoCheckoutMode mode,
                                                         OstreeRepoCheckoutOverwriteMode overwrite_mode,
                                                         GFile *destination,
                                                         OstreeRepoFile *source,
                                                         GFileInfo *source_info,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_checkout_gc             (OstreeRepo *self,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_read_commit             (OstreeRepo *self,
                                                         const char *rev,
                                                         GFile **out_root,
                                                         GCancellable *cancellable,
                                                         GError **error);
enum                OstreeRepoListObjectsFlags;
#define             OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE
gboolean            ostree_repo_list_objects            (OstreeRepo *self,
                                                         OstreeRepoListObjectsFlags flags,
                                                         GHashTable **out_objects,
                                                         GCancellable *cancellable,
                                                         GError **error);
GHashTable *        ostree_repo_traverse_new_reachable  (void);
gboolean            ostree_repo_traverse_dirtree        (OstreeRepo *repo,
                                                         const char *commit_checksum,
                                                         GHashTable *inout_reachable,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_repo_traverse_commit         (OstreeRepo *repo,
                                                         const char *commit_checksum,
                                                         int maxdepth,
                                                         GHashTable *inout_reachable,
                                                         GCancellable *cancellable,
                                                         GError **error);
enum                OstreeRepoPruneFlags;
gboolean            ostree_repo_prune                   (OstreeRepo *self,
                                                         OstreeRepoPruneFlags flags,
                                                         gint depth,
                                                         gint *out_objects_total,
                                                         gint *out_objects_pruned,
                                                         guint64 *out_pruned_object_size_total,
                                                         GCancellable *cancellable,
                                                         GError **error);
enum                OstreeRepoPullFlags;
gboolean            ostree_repo_pull                    (OstreeRepo *self,
                                                         const char *remote_name,
                                                         char **refs_to_fetch,
                                                         OstreeRepoPullFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);

Description

The OstreeRepo is like git, a content-addressed object store. Unlike git, it records uid, gid, and extended attributes.

There are two possible "modes" for an OstreeRepo; OSTREE_REPO_MODE_BARE is very simple - content files are represented exactly as they are, and checkouts are just hardlinks. A OSTREE_REPO_MODE_ARCHIVE_Z2 repository in contrast stores content files zlib-compressed. It is suitable for non-root-owned repositories that can be served via a static HTTP server.

To store content in the repo, first start a transaction with ostree_repo_prepare_transaction(). Then create a OstreeMutableTree, and apply functions such as ostree_repo_stage_directory_to_mtree() to traverse a physical filesystem and stage content, possibly multiple times.

Once the OstreeMutableTree is complete, stage all of its metadata with ostree_repo_stage_mtree(), and finally create a commit with ostree_repo_stage_commit().

Details

enum OstreeRepoMode

typedef enum {
  OSTREE_REPO_MODE_BARE,
  OSTREE_REPO_MODE_ARCHIVE_Z2
} OstreeRepoMode;

See the documentation of OstreeRepo for more information about the possible modes.

OSTREE_REPO_MODE_BARE

Files are stored as themselves; can only be written as root

OSTREE_REPO_MODE_ARCHIVE_Z2

Files are compressed, should be owned by non-root. Can be served via HTTP

ostree_repo_new ()

OstreeRepo *        ostree_repo_new                     (GFile *path);

path :

Path to a repository

Returns :

An accessor object for an OSTree repository located at path. [transfer full]

ostree_repo_check ()

gboolean            ostree_repo_check                   (OstreeRepo *self,
                                                         GError **error);

ostree_repo_get_path ()

GFile *             ostree_repo_get_path                (OstreeRepo *self);

Returns :

Path to repo. [transfer none]

ostree_repo_get_mode ()

OstreeRepoMode      ostree_repo_get_mode                (OstreeRepo *self);

ostree_repo_mode_from_string ()

gboolean            ostree_repo_mode_from_string        (const char *mode,
                                                         OstreeRepoMode *out_mode,
                                                         GError **error);

ostree_repo_get_config ()

GKeyFile *          ostree_repo_get_config              (OstreeRepo *self);

Returns :

The repository configuration; do not modify. [transfer none]

ostree_repo_copy_config ()

GKeyFile *          ostree_repo_copy_config             (OstreeRepo *self);

Returns :

A newly-allocated copy of the repository config. [transfer full]

ostree_repo_get_parent ()

OstreeRepo *        ostree_repo_get_parent              (OstreeRepo *self);

Before this function can be used, ostree_repo_init() must have been called.

self :

Repo

Returns :

Parent repository, or NULL if none. [transfer none]

ostree_repo_write_config ()

gboolean            ostree_repo_write_config            (OstreeRepo *self,
                                                         GKeyFile *new_config,
                                                         GError **error);

Save new_config in place of this repository's config file. Note that new_config should not be modified after - this function simply adds a reference.

self :

Repo

new_config :

Overwrite the config file with this data. Do not change later!

error :

a GError

ostree_repo_prepare_transaction ()

gboolean            ostree_repo_prepare_transaction     (OstreeRepo *self,
                                                         gboolean enable_commit_hardlink_scan,
                                                         gboolean *out_transaction_resume,
                                                         GCancellable *cancellable,
                                                         GError **error);

ostree_repo_commit_transaction ()

gboolean            ostree_repo_commit_transaction      (OstreeRepo *self,
                                                         GCancellable *cancellable,
                                                         GError **error);

ostree_repo_commit_transaction_with_stats ()

gboolean            ostree_repo_commit_transaction_with_stats
                                                        (OstreeRepo *self,
                                                         guint *out_metadata_objects_total,
                                                         guint *out_metadata_objects_written,
                                                         guint *out_content_objects_total,
                                                         guint *out_content_objects_written,
                                                         guint64 *out_content_bytes_written,
                                                         GCancellable *cancellable,
                                                         GError **error);

ostree_repo_abort_transaction ()

gboolean            ostree_repo_abort_transaction       (OstreeRepo *self,
                                                         GCancellable *cancellable,
                                                         GError **error);

ostree_repo_has_object ()

gboolean            ostree_repo_has_object              (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *checksum,
                                                         gboolean *out_have_object,
                                                         GCancellable *cancellable,
                                                         GError **error);

Set out_have_object to TRUE if self contains the given object; FALSE otherwise.

self :

Repo

objtype :

Object type

checksum :

ASCII SHA256 checksum

out_have_object :

TRUE if repository contains object. [out]

cancellable :

Cancellable

error :

Error

Returns :

FALSE if an unexpected error occurred, TRUE otherwise

ostree_repo_stage_metadata ()

gboolean            ostree_repo_stage_metadata          (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *expected_checksum,
                                                         GVariant *object,
                                                         guchar **out_csum,
                                                         GCancellable *cancellable,
                                                         GError **error);

Store the metadata object variant. Return the checksum as out_csum.

If expected_checksum is not NULL, verify it against the computed checksum.

self :

Repo

objtype :

Object type

expected_checksum :

If provided, validate content against this checksum. [allow-none]

object :

Metadata

out_csum :

Binary checksum. [out][array fixed-size=32][allow-none]

cancellable :

Cancellable

error :

Error

ostree_repo_stage_metadata_async ()

void                ostree_repo_stage_metadata_async    (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *expected_checksum,
                                                         GVariant *object,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously store the metadata object variant. If provided, the checksum expected_checksum will be verified.

self :

Repo

objtype :

Object type

expected_checksum :

If provided, validate content against this checksum. [allow-none]

object :

Metadata

cancellable :

Cancellable

callback :

Invoked when metadata is staged

user_data :

Data for callback

ostree_repo_stage_metadata_finish ()

gboolean            ostree_repo_stage_metadata_finish   (OstreeRepo *self,
                                                         GAsyncResult *result,
                                                         guchar **out_csum,
                                                         GError **error);

ostree_repo_stage_metadata_trusted ()

gboolean            ostree_repo_stage_metadata_trusted  (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *checksum,
                                                         GVariant *variant,
                                                         GCancellable *cancellable,
                                                         GError **error);

Store the metadata object variant; the provided checksum is trusted.

self :

Repo

objtype :

Object type

checksum :

Store object with this ASCII SHA256 checksum

variant :

Metadata object

cancellable :

Cancellable

error :

Error

ostree_repo_stage_content ()

gboolean            ostree_repo_stage_content           (OstreeRepo *self,
                                                         const char *expected_checksum,
                                                         GInputStream *object_input,
                                                         guint64 length,
                                                         guchar **out_csum,
                                                         GCancellable *cancellable,
                                                         GError **error);

Store the content object streamed as object_input, with total length length. The actual checksum will be returned as out_csum.

self :

Repo

expected_checksum :

If provided, validate content against this checksum. [allow-none]

object_input :

Content object stream

length :

Length of object_input

out_csum :

Binary checksum. [out][array fixed-size=32][allow-none]

cancellable :

Cancellable

error :

Error

ostree_repo_stage_content_trusted ()

gboolean            ostree_repo_stage_content_trusted   (OstreeRepo *self,
                                                         const char *checksum,
                                                         GInputStream *object_input,
                                                         guint64 length,
                                                         GCancellable *cancellable,
                                                         GError **error);

Store the content object streamed as object_input, with total length length. The given checksum will be treated as trusted.

This function should be used when importing file objects from local disk, for example.

self :

Repo

checksum :

Store content using this ASCII SHA256 checksum

object_input :

Content stream

length :

Length of object_input

cancellable :

Cancellable

error :

Data for callback

ostree_repo_stage_content_async ()

void                ostree_repo_stage_content_async     (OstreeRepo *self,
                                                         const char *expected_checksum,
                                                         GInputStream *object,
                                                         guint64 length,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously store the content object object. If provided, the checksum expected_checksum will be verified.

self :

Repo

expected_checksum :

If provided, validate content against this checksum. [allow-none]

object :

Input

length :

Length of object

cancellable :

Cancellable

callback :

Invoked when content is staged

user_data :

User data for callback

ostree_repo_stage_content_finish ()

gboolean            ostree_repo_stage_content_finish    (OstreeRepo *self,
                                                         GAsyncResult *result,
                                                         guchar **out_csum,
                                                         GError **error);

Completes an invocation of ostree_repo_stage_content_async().

self :

a OstreeRepo

result :

a GAsyncResult

out_csum :

A binary SHA256 checksum of the content object. [out][transfer full]

error :

a GError

ostree_repo_resolve_rev ()

gboolean            ostree_repo_resolve_rev             (OstreeRepo *self,
                                                         const char *refspec,
                                                         gboolean allow_noent,
                                                         char **out_rev,
                                                         GError **error);

Look up the given refspec, returning the checksum it references in the parameter out_rev.

self :

Repo

refspec :

A refspec

allow_noent :

Do not throw an error if refspec does not exist

out_rev :

A checksum,or NULL if allow_noent is true and it does not exist. [out][transfer full]

error :

Error

ostree_repo_write_ref ()

gboolean            ostree_repo_write_ref               (OstreeRepo *self,
                                                         const char *remote,
                                                         const char *name,
                                                         const char *rev,
                                                         GError **error);

If rev is not NULL, then it as the target of ref named name; if remote is provided, the ref will appear originate from that remote.

Otherwise, if rev is NULL, then delete the ref name if it exists.

This function merely changes the ref target; it is possible to use it to target earlier commits.

self :

Repo

remote :

Optional remote name. [allow-none]

name :

Name of ref, e.g. foo/bar/baz

rev :

(allow-none); ASCII SHA256 checksum; if NULL, then delete name

error :

Error

ostree_repo_write_refspec ()

gboolean            ostree_repo_write_refspec           (OstreeRepo *self,
                                                         const char *refspec,
                                                         const char *rev,
                                                         GError **error);

Like ostree_repo_write_ref(), but takes concatenated refspec format as input instead of separate remote and name arguments.

self :

Repo

refspec :

Optional remote with name of ref, e.g. remotename:foo/bar/baz

rev :

(allow-none); ASCII SHA256 checksum; if NULL, then delete refspec

error :

Error

ostree_repo_list_refs ()

gboolean            ostree_repo_list_refs               (OstreeRepo *self,
                                                         const char *refspec_prefix,
                                                         GHashTable **out_all_refs,
                                                         GCancellable *cancellable,
                                                         GError **error);

If refspec_prefix is NULL, list all local and remote refspecs, with their current values in out_all_refs. Otherwise, only list refspecs which have refspec_prefix as a prefix.

self :

Repo

refspec_prefix :

Only list refs which match this prefix. [allow-none]

out_all_refs :

Mapping from ref to checksum. [out][element-type utf8 utf8]

cancellable :

Cancellable

error :

Error

ostree_repo_load_variant_c ()

gboolean            ostree_repo_load_variant_c          (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const guchar *csum,
                                                         GVariant **out_variant,
                                                         GError **error);

Load the metadata object csum of type objtype, storing the result in out_variant.

self :

Repo

objtype :

Expected object type

csum :

Binary checksum

out_variant :

(transfer full): Metadata object. [out]

error :

Error

ostree_repo_load_variant ()

gboolean            ostree_repo_load_variant            (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *sha256,
                                                         GVariant **out_variant,
                                                         GError **error);

Load the metadata object sha256 of type objtype, storing the result in out_variant.

self :

Repo

objtype :

Expected object type

sha256 :

Checksum string

out_variant :

(transfer full): Metadata object. [out]

error :

Error

ostree_repo_load_variant_if_exists ()

gboolean            ostree_repo_load_variant_if_exists  (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *sha256,
                                                         GVariant **out_variant,
                                                         GError **error);

Attempt to load the metadata object sha256 of type objtype if it exists, storing the result in out_variant. If it doesn't exist, NULL is returned.

self :

Repo

objtype :

Object type

sha256 :

ASCII checksum

out_variant :

Metadata. [out][transfer full]

error :

Error

ostree_repo_load_file ()

gboolean            ostree_repo_load_file               (OstreeRepo *self,
                                                         const char *checksum,
                                                         GInputStream **out_input,
                                                         GFileInfo **out_file_info,
                                                         GVariant **out_xattrs,
                                                         GCancellable *cancellable,
                                                         GError **error);

Load content object, decomposing it into three parts: the actual content (for regular files), the metadata, and extended attributes.

self :

Repo

checksum :

ASCII SHA256 checksum

out_input :

File content. [out][allow-none]

out_file_info :

File information. [out][allow-none]

out_xattrs :

Extended attributes. [out][allow-none]

cancellable :

Cancellable

error :

Error

ostree_repo_load_object_stream ()

gboolean            ostree_repo_load_object_stream      (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *checksum,
                                                         GInputStream **out_input,
                                                         guint64 *out_size,
                                                         GCancellable *cancellable,
                                                         GError **error);

Load object as a stream; useful when copying objects between repositories.

self :

Repo

objtype :

Object type

checksum :

ASCII SHA256 checksum

out_input :

Stream for object. [out]

out_size :

Length of out_input. [out]

cancellable :

Cancellable

error :

Error

ostree_repo_query_object_storage_size ()

gboolean            ostree_repo_query_object_storage_size
                                                        (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *sha256,
                                                         guint64 *out_size,
                                                         GCancellable *cancellable,
                                                         GError **error);

Return the size in bytes of object with checksum sha256, after any compression has been applied.

self :

Repo

objtype :

Object type

sha256 :

Checksum

out_size :

Size in bytes object occupies physically. [out]

cancellable :

Cancellable

error :

Error

ostree_repo_delete_object ()

gboolean            ostree_repo_delete_object           (OstreeRepo *self,
                                                         OstreeObjectType objtype,
                                                         const char *sha256,
                                                         GCancellable *cancellable,
                                                         GError **error);

Remove the object of type objtype with checksum sha256 from the repository. An error of type G_IO_ERROR_NOT_FOUND is thrown if the object does not exist.

self :

Repo

objtype :

Object type

sha256 :

Checksum

cancellable :

Cancellable

error :

Error

enum OstreeRepoCommitFilterResult

typedef enum {
  OSTREE_REPO_COMMIT_FILTER_ALLOW,
  OSTREE_REPO_COMMIT_FILTER_SKIP
} OstreeRepoCommitFilterResult;

OSTREE_REPO_COMMIT_FILTER_ALLOW

Do commit this object

OSTREE_REPO_COMMIT_FILTER_SKIP

Ignore this object

OstreeRepoCommitFilter ()

OstreeRepoCommitFilterResult (*OstreeRepoCommitFilter)  (OstreeRepo *repo,
                                                         const char *path,
                                                         GFileInfo *file_info,
                                                         gpointer user_data);

repo :

Repo

path :

Path to file

file_info :

File information

user_data :

User data

Returns :

OstreeRepoCommitFilterResult saying whether or not to commit this file

OstreeRepoCommitModifier

typedef struct OstreeRepoCommitModifier OstreeRepoCommitModifier;

A structure allowing control over commits.


ostree_repo_commit_modifier_new ()

OstreeRepoCommitModifier * ostree_repo_commit_modifier_new
                                                        (OstreeRepoCommitModifierFlags flags,
                                                         OstreeRepoCommitFilter commit_filter,
                                                         gpointer user_data);

flags :

Control options for filter

commit_filter :

Function that can inspect individual files. [allow-none]

user_data :

User data. [allow-none]

Returns :

A new commit modifier. [transfer full]

ostree_repo_commit_modifier_ref ()

OstreeRepoCommitModifier * ostree_repo_commit_modifier_ref
                                                        (OstreeRepoCommitModifier *modifier);

ostree_repo_commit_modifier_unref ()

void                ostree_repo_commit_modifier_unref   (OstreeRepoCommitModifier *modifier);

ostree_repo_stage_directory_to_mtree ()

gboolean            ostree_repo_stage_directory_to_mtree
                                                        (OstreeRepo *self,
                                                         GFile *dir,
                                                         OstreeMutableTree *mtree,
                                                         OstreeRepoCommitModifier *modifier,
                                                         GCancellable *cancellable,
                                                         GError **error);

Store objects for dir and all children into the repository self, overlaying the resulting filesystem hierarchy into mtree.

self :

Repo

dir :

Path to a directory

mtree :

Overlay directory contents into this tree

modifier :

Optional modifier. [allow-none]

cancellable :

Cancellable

error :

Error

ostree_repo_stage_archive_to_mtree ()

gboolean            ostree_repo_stage_archive_to_mtree  (OstreeRepo *self,
                                                         GFile *archive,
                                                         OstreeMutableTree *tree,
                                                         OstreeRepoCommitModifier *modifier,
                                                         gboolean autocreate_parents,
                                                         GCancellable *cancellable,
                                                         GError **error);

ostree_repo_stage_mtree ()

gboolean            ostree_repo_stage_mtree             (OstreeRepo *self,
                                                         OstreeMutableTree *mtree,
                                                         char **out_contents_checksum,
                                                         GCancellable *cancellable,
                                                         GError **error);

Write all metadata objects for mtree to repo; the resulting out_contents_checksum contains the checksum for the OSTREE_OBJECT_TYPE_DIR_TREE object.

self :

Repo

mtree :

Mutable tree

out_contents_checksum :

Return location for ASCII checksum. [out]

cancellable :

Cancellable

error :

Error

ostree_repo_stage_commit ()

gboolean            ostree_repo_stage_commit            (OstreeRepo *self,
                                                         const char *branch,
                                                         const char *parent,
                                                         const char *subject,
                                                         const char *body,
                                                         const char *root_contents_checksum,
                                                         const char *root_metadata_checksum,
                                                         char **out_commit,
                                                         GCancellable *cancellable,
                                                         GError **error);

Write a commit metadata object, referencing root_contents_checksum and root_metadata_checksum.

self :

Repo

branch :

Name of ref

parent :

ASCII SHA256 checksum for parent, or NULL for none. [allow-none]

subject :

Subject

body :

Body

root_contents_checksum :

ASCII SHA256 checksum for OSTREE_OBJECT_TYPE_DIR_TREE

root_metadata_checksum :

ASCII SHA256 checksum for OSTREE_OBJECT_TYPE_DIR_META

out_commit :

Resulting ASCII SHA256 checksum for commit. [out]

cancellable :

Cancellable

error :

Error

enum OstreeRepoCheckoutMode

typedef enum {
  OSTREE_REPO_CHECKOUT_MODE_NONE = 0,
  OSTREE_REPO_CHECKOUT_MODE_USER = 1
} OstreeRepoCheckoutMode;

OSTREE_REPO_CHECKOUT_MODE_NONE

No special options

OSTREE_REPO_CHECKOUT_MODE_USER

Ignore uid/gid of files

enum OstreeRepoCheckoutOverwriteMode

typedef enum {
  OSTREE_REPO_CHECKOUT_OVERWRITE_NONE = 0,
  OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES = 1
} OstreeRepoCheckoutOverwriteMode;

OSTREE_REPO_CHECKOUT_OVERWRITE_NONE

No special options

OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES

When layering checkouts, overwrite earlier files, but keep earlier directories

ostree_repo_checkout_tree ()

gboolean            ostree_repo_checkout_tree           (OstreeRepo *self,
                                                         OstreeRepoCheckoutMode mode,
                                                         OstreeRepoCheckoutOverwriteMode overwrite_mode,
                                                         GFile *destination,
                                                         OstreeRepoFile *source,
                                                         GFileInfo *source_info,
                                                         GCancellable *cancellable,
                                                         GError **error);

Check out source into destination, which must live on the physical filesystem. source may be any subdirectory of a given commit. The mode and overwrite_mode allow control over how the files are checked out.

self :

Repo

mode :

Options controlling all files

overwrite_mode :

Whether or not to overwrite files

destination :

Place tree here

source :

Source tree

source_info :

Source info

cancellable :

Cancellable

error :

Error

ostree_repo_checkout_gc ()

gboolean            ostree_repo_checkout_gc             (OstreeRepo *self,
                                                         GCancellable *cancellable,
                                                         GError **error);

Call this after finishing a succession of checkout operations; it will delete any currently-unused uncompressed objects from the cache.

self :

Repo

cancellable :

Cancellable

error :

Error

ostree_repo_read_commit ()

gboolean            ostree_repo_read_commit             (OstreeRepo *self,
                                                         const char *rev,
                                                         GFile **out_root,
                                                         GCancellable *cancellable,
                                                         GError **error);

Load the content for rev into out_root.

self :

Repo

rev :

Revision (ref or ASCII checksum)

out_root :

An OstreeRepoFile corresponding to the root. [out]

cancellable :

Cancellable

error :

Error

enum OstreeRepoListObjectsFlags

typedef enum {
  OSTREE_REPO_LIST_OBJECTS_LOOSE = (1 << 0),
  OSTREE_REPO_LIST_OBJECTS_PACKED = (1 << 1),
  OSTREE_REPO_LIST_OBJECTS_ALL = (1 << 2)
} OstreeRepoListObjectsFlags;

OSTREE_REPO_LIST_OBJECTS_LOOSE

List only loose (plain file) objects

OSTREE_REPO_LIST_OBJECTS_PACKED

List only packed (compacted into blobs) objects

OSTREE_REPO_LIST_OBJECTS_ALL

List all objects

OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE

#define OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE (G_VARIANT_TYPE ("(bas)")

b - TRUE if object is available "loose" as - List of pack file checksums in which this object appears


ostree_repo_list_objects ()

gboolean            ostree_repo_list_objects            (OstreeRepo *self,
                                                         OstreeRepoListObjectsFlags flags,
                                                         GHashTable **out_objects,
                                                         GCancellable *cancellable,
                                                         GError **error);

This function synchronously enumerates all objects in the repository, returning data in out_objects. out_objects maps from keys returned by ostree_object_name_serialize() to GVariant values of type OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE.

self :

Repo

flags :

Flags controlling enumeration

out_objects :

Map of serialized object name to variant data. [out]

cancellable :

Cancellable

error :

Error

Returns :

TRUE on success, FALSE on error, and error will be set

ostree_repo_traverse_new_reachable ()

GHashTable *        ostree_repo_traverse_new_reachable  (void);

This hash table is a set of GVariant which can be accessed via ostree_object_name_deserialize().

Returns :

A new hash table. [transfer full][element-type GVariant GVariant]

ostree_repo_traverse_dirtree ()

gboolean            ostree_repo_traverse_dirtree        (OstreeRepo *repo,
                                                         const char *commit_checksum,
                                                         GHashTable *inout_reachable,
                                                         GCancellable *cancellable,
                                                         GError **error);

ostree_repo_traverse_commit ()

gboolean            ostree_repo_traverse_commit         (OstreeRepo *repo,
                                                         const char *commit_checksum,
                                                         int maxdepth,
                                                         GHashTable *inout_reachable,
                                                         GCancellable *cancellable,
                                                         GError **error);

enum OstreeRepoPruneFlags

typedef enum {
  OSTREE_REPO_PRUNE_FLAGS_NONE,
  OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE,
  OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY
} OstreeRepoPruneFlags;

OSTREE_REPO_PRUNE_FLAGS_NONE

No special options for pruning

OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE

Don't actually delete objects

OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY

Do not traverse individual commit objects, only follow refs

ostree_repo_prune ()

gboolean            ostree_repo_prune                   (OstreeRepo *self,
                                                         OstreeRepoPruneFlags flags,
                                                         gint depth,
                                                         gint *out_objects_total,
                                                         gint *out_objects_pruned,
                                                         guint64 *out_pruned_object_size_total,
                                                         GCancellable *cancellable,
                                                         GError **error);

Delete content from the repository. By default, this function will only delete "orphaned" objects not referred to by any commit. This can happen during a local commit operation, when we have written content objects but not saved the commit referencing them.

However, if OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY is provided, instead of traversing all commits, only refs will be used. Particularly when combined with depth, this is a convenient way to delete history from the repository.

Use the OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE to just determine statistics on objects that would be deleted, without actually deleting them.

self :

Repo

flags :

Options controlling prune process

depth :

Stop traversal after this many iterations (-1 for unlimited)

out_objects_total :

Number of objects found. [out]

out_objects_pruned :

Number of objects deleted. [out]

out_pruned_object_size_total :

Storage size in bytes of objects deleted. [out]

cancellable :

Cancellable

error :

Error

enum OstreeRepoPullFlags

typedef enum {
  OSTREE_REPO_PULL_FLAGS_NONE
} OstreeRepoPullFlags;

OSTREE_REPO_PULL_FLAGS_NONE

No special options for pull

ostree_repo_pull ()

gboolean            ostree_repo_pull                    (OstreeRepo *self,
                                                         const char *remote_name,
                                                         char **refs_to_fetch,
                                                         OstreeRepoPullFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);

Connect to the remote repository, fetching the specified set of refs refs_to_fetch. For each ref that is changed, download the commit, all metadata, and all content objects, storing them safely on disk in self.

self :

Repo

remote_name :

Name of remote

refs_to_fetch :

Optional list of refs; if NULL, fetch all configured refs. [array zero-terminated=1][element-type utf8][allow-none]

flags :

Options controlling fetch behavior

cancellable :

Cancellable

error :

Error

API Index

C

ostree_checksum_bytes_peek, function in Core repository-independent functions
ostree_checksum_file, function in Core repository-independent functions
ostree_checksum_file_async, function in Core repository-independent functions
ostree_checksum_file_async_finish, function in Core repository-independent functions
ostree_checksum_file_from_input, function in Core repository-independent functions
ostree_checksum_from_bytes, function in Core repository-independent functions
ostree_checksum_from_bytes_v, function in Core repository-independent functions
ostree_checksum_inplace_from_bytes, function in Core repository-independent functions
ostree_checksum_inplace_to_bytes, function in Core repository-independent functions
ostree_checksum_to_bytes, function in Core repository-independent functions
ostree_checksum_to_bytes_v, function in Core repository-independent functions
ostree_checksum_update_meta, function in Core repository-independent functions
ostree_cmp_checksum_bytes, function in Core repository-independent functions
ostree_commit_get_parent, function in Core repository-independent functions
OSTREE_COMMIT_GVARIANT_FORMAT, macro in Core repository-independent functions
ostree_content_file_parse, function in Core repository-independent functions
ostree_content_stream_parse, function in Core repository-independent functions
ostree_create_directory_metadata, function in Core repository-independent functions
ostree_create_file_from_input, function in Core repository-independent functions
ostree_create_temp_dir, function in Core repository-independent functions
ostree_create_temp_file_from_input, function in Core repository-independent functions

D

OSTREE_DIRMETA_GVARIANT_FORMAT, macro in Core repository-independent functions

F

OSTREE_FILE_HEADER_GVARIANT_FORMAT, macro in Core repository-independent functions
ostree_file_header_new, function in Core repository-independent functions
ostree_file_header_parse, function in Core repository-independent functions

G

ostree_get_relative_object_path, function in Core repository-independent functions
ostree_get_xattrs_for_file, function in Core repository-independent functions

H

ostree_hash_object_name, function in Core repository-independent functions

M

ostree_map_metadata_file, function in Core repository-independent functions
OSTREE_MAX_METADATA_SIZE, macro in Core repository-independent functions
OSTREE_MAX_RECURSION, macro in Core repository-independent functions
ostree_metadata_variant_type, function in Core repository-independent functions

O

OstreeObjectType, enum in Core repository-independent functions
ostree_object_from_string, function in Core repository-independent functions
ostree_object_name_deserialize, function in Core repository-independent functions
ostree_object_name_serialize, function in Core repository-independent functions
ostree_object_to_string, function in Core repository-independent functions
ostree_object_type_from_string, function in Core repository-independent functions
OSTREE_OBJECT_TYPE_IS_META, macro in Core repository-independent functions
OSTREE_OBJECT_TYPE_LAST, macro in Core repository-independent functions
ostree_object_type_to_string, function in Core repository-independent functions

P

ostree_parse_refspec, function in Core repository-independent functions

R

ostree_raw_file_to_content_stream, function in Core repository-independent functions
OstreeRepoCheckoutMode, enum in Content-addressed object store
OstreeRepoCheckoutOverwriteMode, enum in Content-addressed object store
OstreeRepoCommitFilter, user_function in Content-addressed object store
OstreeRepoCommitFilterResult, enum in Content-addressed object store
OstreeRepoCommitModifier, typedef in Content-addressed object store
OstreeRepoListObjectsFlags, enum in Content-addressed object store
OstreeRepoMode, enum in Content-addressed object store
OstreeRepoPruneFlags, enum in Content-addressed object store
OstreeRepoPullFlags, enum in Content-addressed object store
ostree_repo_abort_transaction, function in Content-addressed object store
ostree_repo_check, function in Content-addressed object store
ostree_repo_checkout_gc, function in Content-addressed object store
ostree_repo_checkout_tree, function in Content-addressed object store
ostree_repo_commit_modifier_new, function in Content-addressed object store
ostree_repo_commit_modifier_ref, function in Content-addressed object store
ostree_repo_commit_modifier_unref, function in Content-addressed object store
ostree_repo_commit_transaction, function in Content-addressed object store
ostree_repo_commit_transaction_with_stats, function in Content-addressed object store
ostree_repo_copy_config, function in Content-addressed object store
ostree_repo_delete_object, function in Content-addressed object store
ostree_repo_get_config, function in Content-addressed object store
ostree_repo_get_mode, function in Content-addressed object store
ostree_repo_get_parent, function in Content-addressed object store
ostree_repo_get_path, function in Content-addressed object store
ostree_repo_has_object, function in Content-addressed object store
ostree_repo_list_objects, function in Content-addressed object store
OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE, macro in Content-addressed object store
ostree_repo_list_refs, function in Content-addressed object store
ostree_repo_load_file, function in Content-addressed object store
ostree_repo_load_object_stream, function in Content-addressed object store
ostree_repo_load_variant, function in Content-addressed object store
ostree_repo_load_variant_c, function in Content-addressed object store
ostree_repo_load_variant_if_exists, function in Content-addressed object store
ostree_repo_mode_from_string, function in Content-addressed object store
ostree_repo_new, function in Content-addressed object store
ostree_repo_prepare_transaction, function in Content-addressed object store
ostree_repo_prune, function in Content-addressed object store
ostree_repo_pull, function in Content-addressed object store
ostree_repo_query_object_storage_size, function in Content-addressed object store
ostree_repo_read_commit, function in Content-addressed object store
ostree_repo_resolve_rev, function in Content-addressed object store
ostree_repo_stage_archive_to_mtree, function in Content-addressed object store
ostree_repo_stage_commit, function in Content-addressed object store
ostree_repo_stage_content, function in Content-addressed object store
ostree_repo_stage_content_async, function in Content-addressed object store
ostree_repo_stage_content_finish, function in Content-addressed object store
ostree_repo_stage_content_trusted, function in Content-addressed object store
ostree_repo_stage_directory_to_mtree, function in Content-addressed object store
ostree_repo_stage_metadata, function in Content-addressed object store
ostree_repo_stage_metadata_async, function in Content-addressed object store
ostree_repo_stage_metadata_finish, function in Content-addressed object store
ostree_repo_stage_metadata_trusted, function in Content-addressed object store
ostree_repo_stage_mtree, function in Content-addressed object store
ostree_repo_traverse_commit, function in Content-addressed object store
ostree_repo_traverse_dirtree, function in Content-addressed object store
ostree_repo_traverse_new_reachable, function in Content-addressed object store
ostree_repo_write_config, function in Content-addressed object store
ostree_repo_write_ref, function in Content-addressed object store
ostree_repo_write_refspec, function in Content-addressed object store

S

ostree_set_xattrs, function in Core repository-independent functions

T

OSTREE_TREE_GVARIANT_FORMAT, macro in Core repository-independent functions

V

ostree_validate_checksum_string, function in Core repository-independent functions
ostree_validate_rev, function in Core repository-independent functions
ostree_validate_structureof_checksum_string, function in Core repository-independent functions
ostree_validate_structureof_commit, function in Core repository-independent functions
ostree_validate_structureof_csum_v, function in Core repository-independent functions
ostree_validate_structureof_dirmeta, function in Core repository-independent functions
ostree_validate_structureof_dirtree, function in Core repository-independent functions
ostree_validate_structureof_file_mode, function in Core repository-independent functions
ostree_validate_structureof_objtype, function in Core repository-independent functions

W

ostree_write_file_header_update_checksum, function in Core repository-independent functions
ostree_write_variant_with_size, function in Core repository-independent functions

Z

OSTREE_ZLIB_FILE_HEADER_GVARIANT_FORMAT, macro in Core repository-independent functions
ostree_zlib_file_header_new, function in Core repository-independent functions
ostree_zlib_file_header_parse, function in Core repository-independent functions