Functions ¶

Return type:

In many cases using libostree, a program may need to “break” hardlinks by performing a copy. For example, in order to logically append to a file.

This function performs full copying, including e.g. extended attributes and permissions of both regular files and symbolic links.

If the file is not hardlinked, this function does nothing and returns successfully.

This function does not perform synchronization via fsync() or fdatasync(); the idea is this will commonly be done as part of an ostree_repo_commit_transaction(), which itself takes care of synchronization.

New in version 2017.15.

OSTree.check_version(required_year, required_release)¶

Parameters:

required_year (int) – Major/year required
required_release (int) – Release version required

Returns:

True if current libostree has at least the requested version, False otherwise

Return type:

New in version 2017.4.

OSTree.checksum_b64_from_bytes(csum)¶

Parameters:

csum (bytes) – An binary checksum of length 32

Returns:

Modified base64 encoding of csum

The “modified” term refers to the fact that instead of ‘/’, the ‘_’ character is used.

Return type:

str

New in version 2016.8.

OSTree.checksum_b64_to_bytes(checksum)¶

Parameters:: checksum (str) – An ASCII checksum
Returns:: Binary version of checksum.
Return type:: bytes

New in version 2016.8.

OSTree.checksum_bytes_peek(bytes)¶

Parameters:: bytes (GLib.Variant) – GLib.Variant of type ay
Returns:: Binary checksum data in bytes; do not free. If bytes does not have the correct length, return None.
Return type:: bytes

OSTree.checksum_bytes_peek_validate(bytes)¶

Parameters:: bytes (GLib.Variant) – GLib.Variant of type ay
Raises:: GLib.Error
Returns:: Binary checksum data
Return type:: bytes

Like OSTree.checksum_bytes_peek(), but also throws error.

OSTree.checksum_file(f, objtype, cancellable)¶

Parameters:

f (Gio.File) – File path
objtype (OSTree.ObjectType) – Object type
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Returns:

out_csum:: Return location for binary checksum

Return type:

(bool, out_csum: bytes)

Compute the OSTree checksum for a given file.

OSTree.checksum_file_async(f, objtype, io_priority, cancellable, callback, *user_data)¶

Parameters:

f (Gio.File) – File path
objtype (OSTree.ObjectType) – Object type
io_priority (int) – Priority for operation, see %G_IO_PRIORITY_DEFAULT
cancellable (Gio.Cancellable or None) – Cancellable
callback (Gio.AsyncReadyCallback or None) – Invoked when operation is complete
user_data (object or None) – Data for callback

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

OSTree.checksum_file_async_finish(f, result)¶

Parameters:

f (Gio.File) – File path
result (Gio.AsyncResult) – Async result

Raises:

Returns:

out_csum:: Return location for binary checksum

Return type:

(bool, out_csum: bytes)

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

OSTree.checksum_file_at(dfd, path, stbuf, objtype, flags, out_checksum, cancellable)¶

Parameters:

dfd (int) – Directory file descriptor
path (str) – Subpath stbuf (allow-none): Optional stat buffer
stbuf (object or None) –
objtype (OSTree.ObjectType) – Object type
flags (OSTree.ChecksumFlags) – Flags out_checksum (out) (transfer full): Return location for hex checksum
out_checksum (str) –
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Return type:

Compute the OSTree checksum for a given file. This is an fd-relative version of OSTree.checksum_file() which also takes flags and fills in a caller allocated buffer.

New in version 2017.13.

OSTree.checksum_file_from_input(file_info, xattrs, in_, objtype, cancellable)¶

Parameters:

file_info (Gio.FileInfo) – File information
xattrs (GLib.Variant or None) – Optional extended attributes
in (Gio.InputStream or None) – File content, should be None for symbolic links
objtype (OSTree.ObjectType) – Object type
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Returns:

out_csum:: Return location for binary checksum

Return type:

(bool, out_csum: bytes)

Compute the OSTree checksum for a given input.

OSTree.checksum_from_bytes(csum)¶

Parameters:: csum (bytes) – An binary checksum of length 32
Returns:: String form of csum
Return type:: str

OSTree.checksum_from_bytes_v(csum_v)¶

Parameters:: csum_v (GLib.Variant) – GLib.Variant of type ay
Returns:: String form of csum_bytes
Return type:: str

OSTree.checksum_inplace_to_bytes(checksum, buf)¶

Parameters:

checksum (str) – a SHA256 string
buf (int) – Output buffer with at least 32 bytes of space

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

OSTree.checksum_to_bytes(checksum)¶

Parameters:: checksum (str) – An ASCII checksum
Returns:: Binary checksum from checksum of length 32; free with GLib.free().
Return type:: bytes

OSTree.checksum_to_bytes_v(checksum)¶

Parameters:: checksum (str) – An ASCII checksum
Returns:: New GLib.Variant of type ay with length 32
Return type:: GLib.Variant

OSTree.cmp_checksum_bytes(a, b)¶

Parameters:

a (int) – A binary checksum
b (int) – A binary checksum

Return type:

int

Compare two binary checksums, using memcmp().

OSTree.collection_ref_dupv(refs)¶

Parameters:: refs ([OSTree.CollectionRef]) – None-terminated array of OSTree.CollectionRefs
Returns:: a newly allocated copy of refs
Return type:: [OSTree.CollectionRef]

Copy an array of OSTree.CollectionRefs, including deep copies of all its elements. refs must be None-terminated; it may be empty, but must not be None.

New in version 2018.6.

OSTree.collection_ref_freev(refs)¶

Parameters:: refs ([OSTree.CollectionRef]) – an array of OSTree.CollectionRefs

Free the given array of refs, including freeing all its elements. refs must be None-terminated; it may be empty, but must not be None.

New in version 2018.6.

OSTree.commit_get_content_checksum(commit_variant)¶

Parameters:: commit_variant (GLib.Variant) – A commit object
Returns:: A SHA-256 hex string, or None if commit_variant is not well-formed
Return type:: str or None

There are use cases where one wants a checksum just of the content of a commit. OSTree commits by default capture the current timestamp, and may have additional metadata, which means that re-committing identical content often results in a new checksum.

By comparing checksums of content, it’s possible to easily distinguish cases where nothing actually changed.

The content checksums is simply defined as SHA256(root dirtree_checksum || root_dirmeta_checksum), i.e. the SHA-256 of the root “dirtree” object’s checksum concatenated with the root “dirmeta” checksum (both in binary form, not hexadecimal).

New in version 2018.2.

OSTree.commit_get_object_sizes(commit_variant)¶

Parameters:

commit_variant (GLib.Variant) – variant of type OSTree.ObjectType.COMMIT

Raises:

Returns:

out_sizes_entries:: return location for an array of object size entries

Return type:

(bool, out_sizes_entries: [OSTree.CommitSizesEntry])

Reads a commit’s “ostree.sizes” metadata and returns an array of OSTree.CommitSizesEntry in out_sizes_entries. Each element represents an object in the commit. If the commit does not contain the “ostree.sizes” metadata, a Gio.IOErrorEnum.NOT_FOUND error will be returned.

New in version 2020.1.

OSTree.commit_get_parent(commit_variant)¶

Parameters:: commit_variant (GLib.Variant) – Variant of type OSTree.ObjectType.COMMIT
Returns:: Checksum of the parent commit of commit_variant, or None if none
Return type:: str or None

OSTree.commit_get_timestamp(commit_variant)¶

Parameters:: commit_variant (GLib.Variant) – Commit object
Returns:: timestamp in seconds since the Unix epoch, UTC
Return type:: int

New in version 2016.3.

OSTree.commit_metadata_for_bootable(root, dict, cancellable)¶

Parameters:

root (Gio.File) – Root filesystem to be committed
dict (GLib.VariantDict) – Dictionary to update
cancellable (Gio.Cancellable or None) –

Raises:

Return type:

Update provided dict with standard metadata for bootable OSTree commits.

New in version 2021.1.

OSTree.content_file_parse(compressed, content_path, trusted, cancellable)¶

Parameters:

compressed (bool) – Whether or not the stream is zlib-compressed
content_path (Gio.File) – Path to file containing content
trusted (bool) – If True, assume the content has been validated
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Returns:

out_input:: The raw file content stream
out_file_info:: Normal metadata
out_xattrs:: Extended attributes

Return type:

(bool, out_input: Gio.InputStream, out_file_info: Gio.FileInfo, out_xattrs: GLib.Variant)

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

OSTree.content_file_parse_at(compressed, parent_dfd, path, trusted, cancellable)¶

Parameters:

compressed (bool) – Whether or not the stream is zlib-compressed
parent_dfd (int) – Directory file descriptor
path (str) – Subpath
trusted (bool) – If True, assume the content has been validated
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Returns:

out_input:: The raw file content stream
out_file_info:: Normal metadata
out_xattrs:: Extended attributes

Return type:

(bool, out_input: Gio.InputStream, out_file_info: Gio.FileInfo, out_xattrs: GLib.Variant)

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

OSTree.content_stream_parse(compressed, input, input_length, trusted, cancellable)¶

Parameters:

compressed (bool) – Whether or not the stream is zlib-compressed
input (Gio.InputStream) – Object content stream
input_length (int) – Length of stream
trusted (bool) – If True, assume the content has been validated
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Returns:

out_input:: The raw file content stream
out_file_info:: Normal metadata
out_xattrs:: Extended attributes

Return type:

(bool, out_input: Gio.InputStream, out_file_info: Gio.FileInfo, out_xattrs: GLib.Variant)

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

OSTree.create_directory_metadata(dir_info, xattrs)¶

Parameters:

dir_info (Gio.FileInfo) – a Gio.FileInfo containing directory information
xattrs (GLib.Variant or None) – Optional extended attributes

Returns:

A new GLib.Variant containing OSTree.ObjectType.DIR_META

Return type:

OSTree.diff_dirs(flags, a, b, modified, removed, added, cancellable)¶

Parameters:

flags (OSTree.DiffFlags) – Flags
a (Gio.File) – First directory path, or None
b (Gio.File) – First directory path
modified ([OSTree.DiffItem]) – Modified files
removed ([Gio.File]) – Removed files
added ([Gio.File]) – Added files
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Return type:

Compute the difference between directory a and b as 3 separate sets of OSTree.DiffItem in modified, removed, and added.

OSTree.diff_dirs_with_options(flags, a, b, modified, removed, added, options, cancellable)¶

Parameters:

flags (OSTree.DiffFlags) – Flags
a (Gio.File) – First directory path, or None
b (Gio.File) – First directory path
modified ([OSTree.DiffItem]) – Modified files
removed ([Gio.File]) – Removed files
added ([Gio.File]) – Added files
options (OSTree.DiffDirsOptions or None) – Options
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Return type:

Compute the difference between directory a and b as 3 separate sets of OSTree.DiffItem in modified, removed, and added.

New in version 2017.4.

OSTree.diff_print(a, b, modified, removed, added)¶

Parameters:

a (Gio.File) – First directory path
b (Gio.File) – First directory path
modified ([OSTree.DiffItem]) – Modified files
removed ([Gio.File]) – Removed files
added ([Gio.File]) – Added files

Print the contents of a diff to stdout.

OSTree.fs_get_all_xattrs(fd, cancellable)¶

Parameters:

fd (int) – File descriptor
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Returns:

A GLib.Variant of type a(ayay)

Return type:

Retrieve all extended attributes in a canonical (sorted) order from the given file descriptor.

OSTree.fs_get_all_xattrs_at(dfd, path, cancellable)¶

Parameters:

dfd (int) – Directory file descriptor
path (str) – Filesystem path
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Returns:

A GLib.Variant of type a(ayay)

Return type:

Retrieve all extended attributes in a canonical (sorted) order from the given path, relative to the provided directory file descriptor. The target path will not be dereferenced. Currently on Linux, this API must be used currently to retrieve extended attributes for symbolic links because while O_PATH exists, it cannot be used with fgetxattr().

OSTree.gpg_error_quark()¶

Return type:: int

New in version 2017.10.

OSTree.hash_object_name(a)¶

Parameters:: a (object or None) – A GLib.Variant containing a serialized object
Return type:: int

Use this function with GLib.HashTable and OSTree.object_name_serialize().

OSTree.kernel_args_cleanup(loc)¶

Parameters:: loc (object or None) – Address of an OSTree.KernelArgs pointer

Frees the OSTree.KernelArgs structure pointed by *loc

New in version 2019.3.

OSTree.metadata_variant_type(objtype)¶

Parameters:: objtype (OSTree.ObjectType) –
Return type:: GLib.VariantType

OSTree.object_from_string(str)¶

Parameters:

str (str) – An ASCII checksum

Returns:

out_checksum:: Parsed checksum
out_objtype:: Parsed object type

Return type:

(out_checksum: str, out_objtype: OSTree.ObjectType)

Reverse OSTree.object_to_string().

OSTree.object_name_deserialize(variant)¶

Parameters:

variant (GLib.Variant) – A GLib.Variant of type (su)

Returns:

out_checksum:: Pointer into string memory of variant with checksum
out_objtype:: Return object type

Return type:

(out_checksum: str, out_objtype: OSTree.ObjectType)

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

OSTree.object_name_serialize(checksum, objtype)¶

Parameters:

checksum (str) – An ASCII checksum
objtype (OSTree.ObjectType) – An object type

Returns:

A new floating GLib.Variant containing checksum string and objtype

Return type:

OSTree.object_to_string(checksum, objtype)¶

Parameters:

checksum (str) – An ASCII checksum
objtype (OSTree.ObjectType) – Object type

Returns:

A string containing both checksum and a stringifed version of objtype

Return type:

str

OSTree.object_type_from_string(str)¶

Parameters:: str (str) – A stringified version of OSTree.ObjectType
Return type:: OSTree.ObjectType

The reverse of OSTree.object_type_to_string().

OSTree.object_type_to_string(objtype)¶

Parameters:: objtype (OSTree.ObjectType) – an OSTree.ObjectType
Return type:: str

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

OSTree.parse_refspec(refspec)¶

Parameters:

refspec (str) – A “refspec” string

Raises:

Returns:

True on successful parsing, False otherwise

out_remote:: Return location for the remote name, or None if the refspec refs to a local ref
out_ref:: Return location for the ref name

Return type:

(bool, out_remote: str or None, out_ref: str)

Split a refspec like gnome-ostree:gnome-ostree/buildmain or just gnome-ostree/buildmain into two parts. In the first case, out_remote will be set to gnome-ostree, and out_ref to gnome-ostree/buildmain. In the second case (a local ref), out_remote will be None, and out_ref will be gnome-ostree/buildmain. In both cases, True will be returned.

OSTree.raw_file_to_archive_z2_stream(input, file_info, xattrs, cancellable)¶

Parameters:

input (Gio.InputStream) – File raw content stream
file_info (Gio.FileInfo) – A file info
xattrs (GLib.Variant or None) – Optional extended attributes
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Returns:

out_input:: Serialized object stream

Return type:

(bool, out_input: Gio.InputStream)

Convert from a “bare” file representation into an OSTree.ObjectType.FILE stream suitable for ostree pull.

New in version 2016.6.

OSTree.raw_file_to_archive_z2_stream_with_options(input, file_info, xattrs, options, cancellable)¶

Parameters:

input (Gio.InputStream) – File raw content stream
file_info (Gio.FileInfo) – A file info
xattrs (GLib.Variant or None) – Optional extended attributes
options (GLib.Variant or None) – A GLib.Variant a{sv} with an extensible set of flags
cancellable (Gio.Cancellable or None) – Cancellable

Raises:

Returns:

out_input:: Serialized object stream

Return type:

(bool, out_input: Gio.InputStream)

Like OSTree.raw_file_to_archive_z2_stream(), but supports an extensible set of flags. The following flags are currently defined:

compression-level (i): Level of compression to use, 0–9, with 0 being the least compression, and <0 giving the default level (currently 6).

New in version 2017.3.

OSTree.raw_file_to_content_stream(input, file_info, xattrs, cancellable)¶

Parameters:

input (Gio.InputStream) – File raw content stream
file_info (Gio.FileInfo) – A file info
xattrs (GLib.Variant or None) – Optional extended attributes
cancellable (Gio.Cancellable or None) – Cancellable

Raises: