9.3 Programming interface to generalised C buffers and strings

The API dealing with generalised C buffers and strings, is composed of syntaxes used to validate and normalise the arguments before handing them to the foreign function.

Validating generalised C buffer arguments for details on how to validation generalised C buffer arguments.

Validating generalised C string arguments for details on how to validation generalised C string arguments.

The following bindings are exported by the library (vicare arguments general-c-buffers).

Function: general-c-string? ?obj

Expand to an expression which evaluates ?obj once and returns #t if the result is a generalised C string.

Function: general-c-buffer? ?obj

Expand to an expression which evaluates ?obj once and returns #t if the result is a generalised C buffer.

Function: general-c-sticky-buffer? ?obj

Expand to an expression which evaluates ?obj once and returns #t if the result is a generalised C sticky buffer.

Function: assert-general-c-buffer-and-length who buf len

Function: assert-general-c-string-and-length who str len

Assume that buf and str have already been validated as general C buffer and general C string; validate len as valid length of buffer or string.

When successful: nothing happens. If the validation fails: raise an exception using procedure-arguments-consistency-violation. The argument who is used for the condition of type &who.

Function: general-c-buffer-len buf buf.len

Return the number of bytes in a generalised C buffer object.

buf must be a bytevector, pointer object or memory-block struct instance.

When buf is a pointer object: buf.len must be an exact integer (in the range of the C language type size_t) representing the number of bytes available in the referenced memory block. Otherwise buf.len is ignored.

Syntax: with-general-c-strings ((?str ?expr) ...) (string-to-bytevector ?string->bytevector) ?body0 . ?body

Syntax: with-general-c-strings ((?str ?expr) ...) ?body0 . ?body

Auxiliary Syntax: string-to-bytevector

Prepare some generalised C strings to be used by a chunk of code expecting access to raw memory holding a C language string or input buffer.

The values ?str must be identifiers, unique according to bound-identifier=?.

The values ?expr must be expressions which will always be evaluated only once.

The value ?string->bytevector must be an expression evaluating to a procedure which converts a string to a bytevector, for example string->ascii. In the second form of the syntax use: ?string->bytevector defaults to string->ascii.

For each couple ?str and ?expr do the following:

• If the result of evaluating ?expr is a bytevector, pointer object or memory-block instance bind it to ?str.
• If the result of evaluating ?expr is a string: convert it to a bytevector using the procedure result of evaluating ?string->bytevector, then bind it to ?str.

Evaluate the ?body forms in the region in which such bindings are effective. Return the return value of the last ?body form.

Syntax: with-general-c-strings/false ((?str ?expr) ...) (string-to-bytevector ?string->bytevector) ?body0 . ?body

Syntax: with-general-c-strings/false ((?str ?expr) ...) ?body0 . ?body

Auxiliary Syntax: string-to-bytevector

Like with-general-c-strings but if a ?expr evaluates to #f accept the value.

Syntax: with-general-c-pathnames ((?ptn ?expr) ...) ?body0 . ?body

Prepare some generalised C strings to be used by a chunk of code expecting access to raw memory holding a C language string representing a file system pathname.

The values ?ptn must be identifiers, unique according to bound-identifier=?.

The values ?expr must be expressions which will always be evaluated only once.

For each couple ?ptn and ?expr do the following:

• If the result of evaluating ?expr is a bytevector, pointer object or memory-block instance bind it to ?ptn.
• If the result of evaluating ?expr is a string: convert it to a bytevector using the function referenced by the parameter string->pathname-func, then bind it to ?ptn.

Evaluate the ?body forms in the region in which such bindings are effective. Return the return value of the last ?body form.

Syntax: with-general-c-pathnames/false ((?ptn ?expr) ...) ?body0 . ?body

Like with-general-c-pathnames but if a ?expr evaluates to #f accept the value.

As example, let’s say we have loaded C language code exposing a function ikptr_posix_file_size(), which given a file pathname returns its size; we can interface it as follows:

#!r6rs
(import (vicare)
  (vicare arguments validation))

(define (file-size pathname)
  (define who 'file-size)
  (with-arguments-validation (who)
      ((general-c-string pathname))
    (with-general-c-pathnames ((pathname^ pathname))
      (foreign-call "ikptr_posix_file_size" pathname^))))