API Reference (Binary Module)

List of structures

• pll_binary_header_t
• pll_block_map_t
• pll_block_header_t

List of functions

• FILE * pllmod_binary_create
• FILE * pllmod_binary_open
• FILE * pllmod_binary_append_open
• int pllmod_binary_close
• pll_block_map_t * pllmod_binary_get_map
• int pllmod_binary_partition_dump
• pll_partition_t * pllmod_binary_partition_load
• int pllmod_binary_clv_dump
• int pllmod_binary_clv_load
• int pllmod_binary_utree_dump
• pll_utree_t * pllmod_binary_utree_load
• int pllmod_binary_custom_dump
• void * pllmod_binary_custom_load

Structure descriptions

###pll_binary_header_t

typedef struct
{
  unsigned int n_blocks;      //! number of blocks in the file
  unsigned int max_blocks;    //! maximum number of blocks (size of block map)
  unsigned int access_type;   //! PLLMOD_BIN_ACCESS_{SEQUENTIAL|RANDOM}
  char pad[4];                //! padding
  long map_offset;            //! offset of the block map
} pll_binary_header_t;

This is the main header of the binary stream. Access type can be sequential or random. If sequential, right after the header comes the first block, and we can jump from one block to the next one using block_len. If access is random, after the header comes a table with the offsets of the different blocks, such can we access directly.

index

###pll_block_map_t

typedef struct
{
  long block_id;             //! user-defined block id
  long block_offset;         //! offset in the file
} pll_block_map_t;

Block map for random access

index

###pll_block_header_t

typedef struct
{
  long block_id;             //! user-defined block id
  unsigned int type;         //! block type PLLMOD_BIN_BLOCK_...
  unsigned int attributes;   //! custom block attributes
  unsigned int alignment;    //! if memory should be aligned
  char pad[4];               //! padding
  size_t block_len;          //! block length
} pll_block_header_t;

Header stored before each block. If the binary file was created for random access, it may be important that attributes contain PLLMOD_BIN_ATTRIB_UPDATE_MAP such that the block map is updated. Otherwise the block will be only accessible sequentially after reading the previous block.

index

Function descriptions

pllmod_binary_create

FILE * pllmod_binary_create(const char * filename,
                            pll_binary_header_t * header,
                            unsigned int access_type,
                            unsigned int n_blocks);

Creates a new binary file for writing.

Parameters:

• filename: File to create
• header: Output parameter filled with the initial header information. In general users do not need to care about it anymore after calling this function.
• access_type: Should be either PLLMOD_BIN_ACCESS_SEQUENTIAL for sequential access file, or PLLMOD_BIN_ACCESS_RANDOM for random access file.
• n_blocks: If access_type is PLL_BINARY_ACCESS_RANDOM, we need to know or estimate a (maximum) number of blocks that will be stored in the file such that the space for the map can be allocated.

Returns pointer to the file or NULL if an error occurs (check pll_errno and pll_errmsg).

index

###pllmod_binary_open

FILE * pllmod_binary_open(const char * filename,
                          pll_binary_header_t * header);

Open a binary file for reading.

Parameters:

• filename Binary file to read from.
• header File header (output parameter).

Returns pointer to the file, or NULL if an error occurs (check pll_errno and pll_errmsg).

index

###pllmod_binary_append_open

FILE * pllmod_binary_append_open(const char * filename,
                                 pll_binary_header_t * header);

Opens an already created binary file for appending.

Parameters:

• filename: File to append to.
• header: File header.

Returns pointer to the file or NULL if an error occurs (check pll_errno and pll_errmsg).

index

###pllmod_binary_close

int pllmod_binary_close(FILE * bin_file);

Close the binary file

Parameters:

• bin_file: Binary file to close.

Returns PLL_SUCCESS if OK, or PLL_FAILURE if an error occurs (check pll_errno and pll_errmsg).

index

###pllmod_binary_get_map

pll_block_map_t * pllmod_binary_get_map(FILE * bin_file,
                                        unsigned int * n_blocks);

index

###pllmod_binary_partition_dump

int pllmod_binary_partition_dump(FILE * bin_file,
                                 int block_id,
                                 pll_partition_t * partition,
                                 unsigned int attributes);

Save a partition to the binary file

Parameters:

• bin_file: Binary file.
• block_id: Custom block identifier. It is also the index for finding the offset in the random access map. For instance, the client code can define block_id=1..10 for partitions, 11..20 for trees, etc. There are no constraints for sequential access files, but it must be unique for random access.
• partition: The partition to save.
• attributes: Custom attributes for the function. For random access, it should contain at least PLL_BINARY_ATTRIB_UPDATE_MAP such that the map is updated accordingly. Also, it can contain PLLMOD_BIN_ATTRIB_PARTITION_DUMP_CLV for storing the CLVs and PLLMOD_BIN_ATTRIB_PARTITION_DUMP_WGT for storing the pattern weights.

Returns PLL_SUCCESS if OK

index

###pllmod_binary_partition_load

pll_partition_t * pllmod_binary_partition_load(FILE * bin_file,
                                               int block_id,
                                               pll_partition_t * partition,
                                               unsigned int * attributes,
                                               long int offset);

Load a partition from the binary file

Parameters:

• bin_file: binary file.
• block_id: Custom block identifier.
• partition: if NULL, creates a new partition.
• attributes: the loaded attributes.
• offset: offset to the data block, if known.
  • 0, if access is sequential.
  • PLLMOD_BIN_ACCESS_SEEK, for searching in the file header.

Returns pointer to the updated (or new) partition, or NULL if an error occurs (check pll_errno and pll_errmsg).

index

###pllmod_binary_clv_dump

int pllmod_binary_clv_dump(FILE * bin_file,
                           int block_id,
                           pll_partition_t * partition,
                           unsigned int clv_index,
                           unsigned int attributes);

Save a partition to the binary file

Parameters:

• bin_file: binary file.
• block_id: Custom block identifier. It is also the index for finding the offset in the random access map. For instance, the client code can define block_id=1..10 for partitions, 11..20 for trees, etc. There are no constraints for sequential access files, but it must be unique for random access.
• partition: the partition containing the saved CLV.
• clv_index: the index of the CLV.
• attributes: Custom attributes for the function. For random access, it should contain at least PLL_BINARY_ATTRIB_UPDATE_MAP such that the map is updated accordingly.

Returns PLL_SUCCESS if OK, or PLL_FAILURE if an error occurs (check pll_errno and pll_errmsg).

index

###pllmod_binary_clv_load

int pllmod_binary_clv_load(FILE * bin_file,
                           int block_id,
                           pll_partition_t * partition,
                           unsigned int clv_index,
                           unsigned int * attributes,
                           long int offset);

index

###pllmod_binary_utree_dump

int pllmod_binary_utree_dump(FILE * bin_file,
                             int block_id,
                             pll_utree_t * tree,
                             unsigned int tip_count,
                             unsigned int attributes);

index

###pllmod_binary_utree_load

pll_utree_t * pllmod_binary_utree_load(FILE * bin_file,
                                       int block_id,
                                       unsigned int * attributes,
                                       long int offset);

index

###pllmod_binary_custom_dump

int pllmod_binary_custom_dump(FILE * bin_file,
                              int block_id,
                              void * data,
                              size_t size,
                              unsigned int attributes);

Parameters:

• bin_file: The file pointer returned by the previous function.
• block_id: Custom block identifier. It is also the index for finding the offset in the random access map. For instance, the client code can define block_id=1..10 for partitions, 11..20 for trees, etc. There are no constraints for sequential access files, but it must be unique for random access. There are no constraints for sequential access files, but it must be unique for random access.
• data: The memory block to be saved.
• size: The size of data.
• attributes: Custom attributes for the function. For random access, it should contain at least PLL_BINARY_ATTRIB_UPDATE_MAP such that the map is updated accordingly.

Returns PLL_SUCCESS if OK, or PLL_FAILURE if the block could not be dumped (check pll_errno and pll_errmsg).

index

###pllmod_binary_custom_load

void * pllmod_binary_custom_load(FILE * bin_file,
                                 int block_id,
                                 size_t * size,
                                 unsigned int * type,
                                 unsigned int * attributes,
                                 long int offset);

index