Function tskit::bindings::tsk_table_collection_loadf

pub unsafe extern "C" fn tsk_table_collection_loadf(
    self_: *mut tsk_table_collection_t,
    file: *mut FILE,
    options: tsk_flags_t
) -> c_int

@brief Load a table collection from a stream.

@rst Loads a tables definition from the specified file stream to this table collection. By default, the table collection is also initialised. The resources allocated must be freed using :c:func:tsk_table_collection_free even in error conditions.

If the :c:macro:TSK_NO_INIT option is set, the table collection is not initialised, allowing an already initialised table collection to be overwritten with the data from a file.

The stream can be an arbitrary file descriptor, for example a network socket. No seek operations are performed.

If the stream contains multiple table collection definitions, this function will load the next table collection from the stream. If the stream contains no more table collection definitions the error value :c:macro:TSK_ERR_EOF will be returned. Note that EOF is only returned in the case where zero bytes are read from the stream — malformed files or other errors will result in different error conditions. Please see the :ref:sec_c_api_examples_file_streaming section for an example of how to sequentially load tree sequences from a stream.

Please note that this streaming behaviour is not supported if the :c:macro:TSK_LOAD_SKIP_TABLES or :c:macro:TSK_LOAD_SKIP_REFERENCE_SEQUENCE option is set. If the :c:macro:TSK_LOAD_SKIP_TABLES option is set, only the non-table information from the table collection will be read, leaving all tables with zero rows and no metadata or schema. If the :c:macro:TSK_LOAD_SKIP_REFERENCE_SEQUENCE option is set, the table collection is read without loading the reference sequence. When attempting to read from a stream with multiple table collection definitions and either of these two options set, the requested information from the first table collection will be read on the first call to :c:func:tsk_table_collection_loadf, with subsequent calls leading to errors.

Options**

Options can be specified by providing one or more of the following bitwise flags:

• :c:macro:TSK_NO_INIT
• :c:macro:TSK_LOAD_SKIP_TABLES
• :c:macro:TSK_LOAD_SKIP_REFERENCE_SEQUENCE @endrst

@param self A pointer to an uninitialised tsk_table_collection_t object if the TSK_NO_INIT option is not set (default), or an initialised tsk_table_collection_t otherwise. @param file A FILE stream opened in an appropriate mode for reading (e.g. “r”, “r+” or “w+”) positioned at the beginning of a table collection definition. @param options Bitwise options. See above for details. @return Return 0 on success or a negative value on failure.