C typedef declarations
In C, typedef declarations create synonyms, not new types. Look up
the declarations to discover the real type. For example, the signature
of H5Fclose is
herr_t H5Fclose(hid_t file_id);
The types herr_t and hid_t are declared in the HDF5 header files as
typedef int herr_t;
typedef int hid_t;
So to create a Scheme procedure that wraps H5Fclose, use
(pointer->procedure int (dynamic-func "H5Fclose" ...) (list int))
Alternatively, the same synonyms can be defined in Scheme:
(define herr_t int)
(define hid_t int)
Then you can write
(pointer->procedure herr_t (dynamic-func "H5Fclose" ...) (list hid_t))
Passing structs by pointer
In C, structs are usually passed to and from functions by pointer. For
example, the signature of callbacks passed to
H5Literate
is
herr_t op(hid_t group, const char *name, const H5L_info_t *info, void *op_data);
H5L_info_t is a struct type which is passed by pointer.
The representation of the callback's argument types in Scheme is
(list int '* '* '*)
The functions make-c-struct and parse-c-struct
(reference)
create and read struct pointers. They need to know the layout of the
struct, which is given as a list with the types of the struct members.
Passing structs by value
Guile also supports passing structs by value, though it isn't
documented. The functions pointer->procedure and
procedure->pointer
(reference)
take the return and argument types. To denote a struct that is passed
by value, use a list with the types of the struct members.
Manipulation of the struct values in Scheme is still done using
make-c-struct and parse-c-struct (the struct values are
automatically converted to pointers and back).
Example
The following example demonstrates how to pass a Scheme procedure to
the C function H5Literate. It is a translation of "Iterate over
Groups w/ H5Literate" from the HDF5 C
Examples.
The sample data file
h5ex_g_iterate.h5
needs to be in the working directory.
A lot of code is required to replicate the types and constants from
the HDF5 headers, but the actual program is quite short (it's at the
very end).
(use-modules
(system foreign)
(rnrs bytevectors))
(define libhdf5 (dynamic-link "libhdf5"))
;; HDF5 typedefs
;; typedef int herr_t;
(define herr_t int)
;; typedef int hid_t;
(define hid_t int)
;; typedef enum H5_index_t {
;; H5_INDEX_UNKNOWN = -1, /* Unknown index type */
;; H5_INDEX_NAME, /* Index on names */
;; H5_INDEX_CRT_ORDER, /* Index on creation order */
;; H5_INDEX_N /* Number of indices defined */
;; } H5_index_t;
(define H5_index_t int)
(define H5_INDEX_NAME 0)
;; typedef enum {
;; H5_ITER_UNKNOWN = -1, /* Unknown order */
;; H5_ITER_INC, /* Increasing order */
;; H5_ITER_DEC, /* Decreasing order */
;; H5_ITER_NATIVE, /* No particular order, whatever is fastest */
;; H5_ITER_N /* Number of iteration orders */
;; } H5_iter_order_t;
(define H5_iter_order_t int)
(define H5_ITER_NATIVE 2)
;; typedef herr_t (*H5L_iterate_t)(hid_t group, const char *name, const H5L_info_t *info,
;; void *op_data);
(define H5L_iterate_t '*)
;; typedef uint64_t haddr_t;
(define haddr_t uint64)
;; typedef enum H5O_type_t {
;; H5O_TYPE_UNKNOWN = -1, /* Unknown object type */
;; H5O_TYPE_GROUP, /* Object is a group */
;; H5O_TYPE_DATASET, /* Object is a dataset */
;; H5O_TYPE_NAMED_DATATYPE, /* Object is a named data type */
;; H5O_TYPE_NTYPES /* Number of different object types (must be last!) */
;; } H5O_type_t;
(define H5O_type_t int)
(define H5O_TYPE_GROUP 0)
(define H5O_TYPE_DATASET 1)
(define H5O_TYPE_NAMED_DATATYPE 2)
;; time_t is long on POSIX systems
(define time_t long)
;; typedef unsigned long long hsize_t;
;; (system foreign) doesn't have long long, use uint64 and cross our fingers
(define hsize_t uint64)
;; typedef struct H5O_hdr_info_t {
;; unsigned version; /* Version number of header format in file */
;; unsigned nmesgs; /* Number of object header messages */
;; unsigned nchunks; /* Number of object header chunks */
;; unsigned flags; /* Object header status flags */
;; struct {
;; hsize_t total; /* Total space for storing object header in file */
;; hsize_t meta; /* Space within header for object header metadata information */
;; hsize_t mesg; /* Space within header for actual message information */
;; hsize_t free; /* Free space within object header */
;; } space;
;; struct {
;; uint64_t present; /* Flags to indicate presence of message type in header */
;; uint64_t shared; /* Flags to indicate message type is shared in header */
;; } mesg;
;; } H5O_hdr_info_t;
(define H5O_hdr_info_t
(list
unsigned-int
unsigned-int
unsigned-int
unsigned-int
(list
hsize_t
hsize_t
hsize_t
hsize_t)
(list
uint64
uint64)))
;; typedef struct H5_ih_info_t {
;; hsize_t index_size; /* btree and/or list */
;; hsize_t heap_size;
;; } H5_ih_info_t;
(define H5_ih_info_t
(list
hsize_t
hsize_t))
;; typedef struct H5O_info_t {
;; unsigned long fileno; /* File number that object is located in */
;; haddr_t addr; /* Object address in file */
;; H5O_type_t type; /* Basic object type (group, dataset, etc.) */
;; unsigned rc; /* Reference count of object */
;; time_t atime; /* Access time */
;; time_t mtime; /* Modification time */
;; time_t ctime; /* Change time */
;; time_t btime; /* Birth time */
;; hsize_t num_attrs; /* # of attributes attached to object */
;; H5O_hdr_info_t hdr; /* Object header information */
;; /* Extra metadata storage for obj & attributes */
;; struct {
;; H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
;; H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
;; } meta_size;
;; } H5O_info_t;
(define H5O_info_t
(list
unsigned-long
haddr_t
H5O_type_t
unsigned-int
time_t
time_t
time_t
time_t
hsize_t
H5O_hdr_info_t
(list
H5_ih_info_t
H5_ih_info_t)))
(define (make-H5O_info_t)
"Returns a pointer to a zero-initialized H50_info_t struct."
(bytevector->pointer (make-bytevector (sizeof H5O_info_t) 0)))
(define (parse-H5O_info_t foreign)
(parse-c-struct foreign H5O_info_t))
(define (H5O_info_t-type vals)
(list-ref vals 2))
;; HDF5 constants
;; #define H5F_ACC_RDONLY (H5CHECK 0x0000u)
(define H5F_ACC_RDONLY 0)
;; #define H5P_DEFAULT (hid_t)0
(define H5P_DEFAULT 0)
;; HDF5 functions
;; hid_t
;; H5Fopen(const char *filename, unsigned flags, hid_t fapl_id);
(define H5Fopen
(pointer->procedure
hid_t
(dynamic-func "H5Fopen" libhdf5)
(list '* unsigned-int hid_t)))
;; herr_t
;; H5Literate(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order,
;; hsize_t *idx_p, H5L_iterate_t op, void *op_data);
(define H5Literate
(pointer->procedure
herr_t
(dynamic-func "H5Literate" libhdf5)
(list hid_t H5_index_t H5_iter_order_t '* H5L_iterate_t '*)))
;; herr_t
;; H5Fclose(hid_t file_id);
(define H5Fclose
(pointer->procedure
herr_t
(dynamic-func "H5Fclose" libhdf5)
(list hid_t)))
;; herr_t
;; H5Oget_info_by_name(hid_t loc_id, const char *name, H5O_info_t *oinfo, hid_t lapl_id);
(define H5Oget_info_by_name
(pointer->procedure
herr_t
(dynamic-func "H5Oget_info_by_name" libhdf5)
(list hid_t '* '* hid_t)))
(define FILE "h5ex_g_iterate.h5")
(define (main)
(let ((status 0)
(file (H5Fopen (string->pointer FILE) H5F_ACC_RDONLY H5P_DEFAULT)))
(display "Objects in root group:\n")
(set! status (H5Literate file H5_INDEX_NAME H5_ITER_NATIVE %null-pointer
op_func_ptr %null-pointer))
(set! status (H5Fclose file))
0))
;; Operator function. Prints the name and type of the object
;; being examined.
;;
;; C signature:
;; herr_t op_func (hid_t loc_id, const char *name, const H5L_info_t *info,
;; void *operator_data)
(define (op_func loc_id name info operator_data)
(let ((status 0)
(name-str (pointer->string name))
(infobuf (make-H5O_info_t)))
(set! status (H5Oget_info_by_name loc_id name infobuf H5P_DEFAULT))
(let ((type (H5O_info_t-type (parse-H5O_info_t infobuf))))
(cond
((= type H5O_TYPE_GROUP)
(format #t " Group: ~a\n" name-str))
((= type H5O_TYPE_DATASET)
(format #t " Dataset: ~a\n" name-str))
((= type H5O_TYPE_NAMED_DATATYPE)
(format #t " Datatype: ~a\n" name-str))
(else
(format #t " Unknown: ~a\n" name-str))))
0))
(define op_func_ptr (procedure->pointer herr_t op_func (list hid_t '* '* '*)))
(main)
