Functions

  break_hardlink (dfd, path, skip_xattrs, cancellable)
  check_version (required_year, required_release)
  checksum_b64_from_bytes (csum)
  checksum_b64_to_bytes (checksum)
  checksum_bytes_peek (bytes)
  checksum_bytes_peek_validate (bytes)
  checksum_file (f, objtype, cancellable)
  checksum_file_async (f, objtype, io_priority, cancellable, callback, *user_data)
  checksum_file_async_finish (f, result)
  checksum_file_at (dfd, path, stbuf, objtype, flags, out_checksum, cancellable)
  checksum_file_from_input (file_info, xattrs, in_, objtype, cancellable)
  checksum_from_bytes (csum)
  checksum_from_bytes_v (csum_v)
  checksum_inplace_to_bytes (checksum, buf)
  checksum_to_bytes (checksum)
  checksum_to_bytes_v (checksum)
  cmd__private__ ()
  cmp_checksum_bytes (a, b)
  collection_ref_dupv (refs)
  collection_ref_equal (ref1, ref2)
  collection_ref_freev (refs)
  collection_ref_hash (ref)
  commit_get_content_checksum (commit_variant)
  commit_get_parent (commit_variant)
  commit_get_timestamp (commit_variant)
  content_file_parse (compressed, content_path, trusted, cancellable)
  content_file_parse_at (compressed, parent_dfd, path, trusted, cancellable)
  content_stream_parse (compressed, input, input_length, trusted, cancellable)
  create_directory_metadata (dir_info, xattrs)
  diff_dirs (flags, a, b, modified, removed, added, cancellable)
  diff_dirs_with_options (flags, a, b, modified, removed, added, options, cancellable)
  diff_print (a, b, modified, removed, added)
  gpg_error_quark ()
  hash_object_name (a)
  metadata_variant_type (objtype)
  object_from_string (str)
  object_name_deserialize (variant)
  object_name_serialize (checksum, objtype)
  object_to_string (checksum, objtype)
  object_type_from_string (str)
  object_type_to_string (objtype)
  parse_refspec (refspec)
  raw_file_to_archive_z2_stream (input, file_info, xattrs, cancellable)
  raw_file_to_archive_z2_stream_with_options (input, file_info, xattrs, options, cancellable)
  raw_file_to_content_stream (input, file_info, xattrs, cancellable)
  repo_commit_traverse_iter_cleanup (p)
  repo_finder_resolve_all_async (finders, refs, parent_repo, cancellable, callback, *user_data)
  repo_finder_resolve_all_finish (result)
  repo_finder_result_freev (results)
  validate_checksum_string (sha256)
  validate_collection_id (collection_id)
  validate_remote_name (remote_name)
  validate_rev (rev)
  validate_structureof_checksum_string (checksum)
  validate_structureof_commit (commit)
  validate_structureof_csum_v (checksum)
  validate_structureof_dirmeta (dirmeta)
  validate_structureof_dirtree (dirtree)
  validate_structureof_file_mode (mode)
  validate_structureof_objtype (objtype)

Details

Parameters:
  • dfd (int) – Directory fd
  • path (str) – Path relative to dfd
  • skip_xattrs (bool) – Do not copy extended attributes
  • cancellable (Gio.Cancellable or None) –
Raises:

GLib.Error

Return type:

bool

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:

bool

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
OSTree.checksum_b64_to_bytes(checksum)
Parameters:checksum (str) – An ASCII checksum
Returns:Binary version of checksum.
Return type:bytes
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:
Raises:

GLib.Error

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:

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

OSTree.checksum_file_async_finish(f, result)
Parameters:
Raises:

GLib.Error

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:
Raises:

GLib.Error

Return type:

bool

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:
Raises:

GLib.Error

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.cmd__private__()
Return type:OSTree.CmdPrivateVTable
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_equal(ref1, ref2)
Parameters:
Returns:

True if ref1 and ref2 are equal, False otherwise

Return type:

bool

Compare ref1 and ref2 and return True if they have the same collection ID and ref name, and False otherwise. Both ref1 and ref2 must be non-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.collection_ref_hash(ref)
Parameters:ref (object or None) – an OSTree.CollectionRef
Returns:hash value for ref
Return type:int

Hash the given ref. This function is suitable for use with GLib.HashTable. ref must be non-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).

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
OSTree.commit_get_timestamp(commit_variant)
Parameters:commit_variant (GLib.Variant) –
Return type:int
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:

GLib.Error

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:

GLib.Error

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:

GLib.Error

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:
Returns:

A new GLib.Variant containing OSTree.ObjectType.DIR_META

Return type:

GLib.Variant

OSTree.diff_dirs(flags, a, b, modified, removed, added, cancellable)
Parameters:
Raises:

GLib.Error

Return type:

bool

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:
Raises:

GLib.Error

Return type:

bool

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

OSTree.diff_print(a, b, modified, removed, added)
Parameters:

Print the contents of a diff to stdout.

OSTree.gpg_error_quark()
Return type:int
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.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:
Returns:

A new floating GLib.Variant containing checksum string and objtype

Return type:

GLib.Variant

OSTree.object_to_string(checksum, objtype)
Parameters:
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:GLib.Error
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/buildmaster or just gnome-ostree/buildmaster into two parts. In the first case, out_remote will be set to gnome-ostree, and out_ref to gnome-ostree/buildmaster. In the second case (a local ref), out_remote will be None, and out_ref will be gnome-ostree/buildmaster. In both cases, True will be returned.

OSTree.raw_file_to_archive_z2_stream(input, file_info, xattrs, cancellable)
Parameters:
Raises:

GLib.Error

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.

OSTree.raw_file_to_archive_z2_stream_with_options(input, file_info, xattrs, options, cancellable)
Parameters:
Raises:

GLib.Error

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:
Raises:

GLib.Error

Returns:

out_input:Serialized object stream
out_length:Length of stream

Return type:

(bool, out_input: Gio.InputStream, out_length: int)

Convert from a “bare” file representation into an OSTree.ObjectType.FILE stream. This is a fundamental operation for writing data to an OSTree.Repo.

OSTree.repo_commit_traverse_iter_cleanup(p)
Parameters:p (object or None) –
OSTree.repo_finder_resolve_all_async(finders, refs, parent_repo, cancellable, callback, *user_data)
Parameters:

A version of OSTree.RepoFinder.resolve_async() which queries one or more finders in parallel and combines the results.

New in version 2018.6.

OSTree.repo_finder_resolve_all_finish(result)
Parameters:result (Gio.AsyncResult) – Gio.AsyncResult from the callback
Raises:GLib.Error
Returns:array of zero or more results
Return type:[OSTree.RepoFinderResult]

Get the results from a OSTree.RepoFinder.resolve_all_async() operation.

New in version 2018.6.

OSTree.repo_finder_result_freev(results)
Parameters:results ([OSTree.RepoFinderResult]) – an OSTree.RepoFinderResult

Free the given results array, freeing each element and the container.

New in version 2018.6.

OSTree.validate_checksum_string(sha256)
Parameters:sha256 (str) – SHA256 hex string
Raises:GLib.Error
Returns:True if sha256 is a valid checksum string, False otherwise
Return type:bool

Use this function to see if input strings are checksums.

OSTree.validate_collection_id(collection_id)
Parameters:collection_id (str or None) – A collection ID
Raises:GLib.Error
Returns:True if collection_id is a valid collection ID, False if it is invalid or None
Return type:bool

Check whether the given collection_id is valid. Return an error if it is invalid or None.

Valid collection IDs are reverse DNS names:

  • They are composed of 1 or more elements separated by a period (.) character. All elements must contain at least one character.
  • Each element must only contain the ASCII characters [A-Z][a-z][0-9]_ and must not begin with a digit.
  • They must contain at least one . (period) character (and thus at least two elements).
  • They must not begin with a . (period) character.
  • They must not exceed 255 characters in length.

(This makes their format identical to D-Bus interface names, for consistency.)

New in version 2018.6.

OSTree.validate_remote_name(remote_name)
Parameters:remote_name (str) – A remote name
Raises:GLib.Error
Returns:True if remote_name is a valid remote name
Return type:bool

New in version 2017.8.

OSTree.validate_rev(rev)
Parameters:rev (str) – A revision string
Raises:GLib.Error
Returns:True if rev is a valid ref string
Return type:bool
OSTree.validate_structureof_checksum_string(checksum)
Parameters:checksum (str) – an ASCII string
Raises:GLib.Error
Returns:True if checksum is a valid ASCII SHA256 checksum
Return type:bool
OSTree.validate_structureof_commit(commit)
Parameters:commit (GLib.Variant) – A commit object, OSTree.ObjectType.COMMIT
Raises:GLib.Error
Returns:True if commit is structurally valid
Return type:bool

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

OSTree.validate_structureof_csum_v(checksum)
Parameters:checksum (GLib.Variant) – a GLib.Variant of type “ay”
Raises:GLib.Error
Returns:True if checksum is a valid binary SHA256 checksum
Return type:bool
OSTree.validate_structureof_dirmeta(dirmeta)
Parameters:dirmeta (GLib.Variant) – A dirmeta object, OSTree.ObjectType.DIR_META
Raises:GLib.Error
Returns:True if dirmeta is structurally valid
Return type:bool

Use this to validate the basic structure of dirmeta.

OSTree.validate_structureof_dirtree(dirtree)
Parameters:dirtree (GLib.Variant) – A dirtree object, OSTree.ObjectType.DIR_TREE
Raises:GLib.Error
Returns:True if dirtree is structurally valid
Return type:bool

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

OSTree.validate_structureof_file_mode(mode)
Parameters:mode (int) – A Unix filesystem mode
Raises:GLib.Error
Returns:True if mode represents a valid file type and permissions
Return type:bool
OSTree.validate_structureof_objtype(objtype)
Parameters:objtype (int) –
Raises:GLib.Error
Returns:True if objtype represents a valid object type
Return type:bool