## Objects

## Overview

Objects are entities that can allocated, referred to by pointers, and can be freed.

## `allocate-foreign-object`

Allocates an instance of a foreign object.

### Macro

          allocate-foreign-object
          type
          &optional;
          size

`type`

  The type of foreign object to allocate. This parameter is evaluated.

`size`

  An optional size parameter that is evaluated. If specified, allocates and returns an array of `type` that is `size` members long. This parameter is evaluated.

returns

  A pointer to the foreign object.

### Description

Allocates an instance of a foreign object. It returns a pointer to the object.

### Examples

    (def-struct ab (a :int) (b :double))
       (allocate-foreign-object 'ab)
    => #<ptr>

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `free-foreign-object`

Frees memory that was allocated for a foreign boject.

### Macro

          free-foreign-object
          ptr

`ptr`

  A pointer to the allocated foreign object to free.

### Description

Frees the memory used by the allocation of a foreign object.

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `with-foreign-object`

Wraps the allocation of a foreign object around a body of code.

### Macro

          with-foreign-object
          (var type)
          &body;
          body

### Arguments and Values

`var`

  The variable name to bind.

`type`

  The type of foreign object to allocate. This parameter is evaluated.

returns

  The result of evaluating the `body`.

### Description

This function wraps the allocation, binding, and destruction of a foreign object. On &CMUCL; and &LW; platforms the object is stack allocated for efficiency. Benchmarks show that &ACL; performs much better with static allocation.

### Examples

         (defun gethostname2 ()
         "Returns the hostname"
         (uffi:with-foreign-object (name '(:array :unsigned-char 256))
         (if (zerop (c-gethostname (uffi:char-array-to-pointer name) 256))
         (uffi:convert-from-foreign-string name)
         (error "gethostname() failed."))))

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `size-of-foreign-type`

Returns the number of data bytes used by a foreign object type.

### Macro

          size-of-foreign-type
          ftype

`ftype`

  A foreign type specifier. This parameter is evaluated.

### Description

Returns the number of data bytes used by a foreign object type. This does not include any Lisp storage overhead.

### Examples

          (size-of-foreign-object :unsigned-byte)
          => 1
          (size-of-foreign-object 'my-100-byte-vector-type)
          => 100

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `pointer-address`

Returns the address of a pointer.

### Macro

          pointer-address
          ptr

`ptr`

  A pointer to a foreign object.

returns

  An integer representing the pointer's address.

### Description

Returns the address as an integer of a pointer.

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `deref-pointer`

Deferences a pointer.

### Macro

          deref-pointer
          ptr
          type

`ptr`

  A pointer to a foreign object.

`type`

  A foreign type of the object being pointed to.

returns

  The value of the object where the pointer points.

### Description

Returns the object to which a pointer points.

### Examples

          (let ((intp (allocate-foreign-object :int)))
          (setf (deref-pointer intp :int) 10)
          (prog1
          (deref-pointer intp :int)
          (free-foreign-object intp)))
          => 10

### Notes

The TYPE argument is ignored for CL implementations other than AllegroCL. If you want to cast a pointer to another type use WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY.

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `ensure-char-character`

Ensures that a dereferenced `:char` pointer is a character.

### Macro

          ensure-char-character
          object

`object`

  Either a character or a integer specifying a character code.

returns

  A character.

### Description

Ensures that an objects obtained by dereferencing `:char` and `:unsigned-char` pointers are a lisp character.

### Examples

          (let ((fs (convert-to-foreign-string "a")))
          (prog1
          (ensure-char-character (deref-pointer fs :char))
          (free-foreign-object fs)))
          => #\a

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

Depending upon the implementation and what &UFFI; expects, this macro may signal an error if the object is not a character or integer.

## `ensure-char-integer`

Ensures that a dereferenced `:char` pointer is an integer.

### Macro

          ensure-char-integer
          object

`object`

  Either a character or a integer specifying a character code.

returns

  An integer.

### Description

Ensures that an object obtained by dereferencing a `:char` pointer is an integer.

### Examples

          (let ((fs (convert-to-foreign-string "a")))
          (prog1
          (ensure-char-integer (deref-pointer fs :char))
          (free-foreign-object fs)))
          => 96

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

Depending upon the implementation and what &UFFI; expects, this macro may signal an error if the object is not a character or integer.

## `make-null-pointer`

Create a &NULL; pointer.

### Macro

          make-null-pointer
          type

`type`

  A type of object to which the pointer refers.

returns

  The &NULL; pointer of type `type`.

### Description

Creates a &NULL; pointer of a specified type.

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `null-pointer-p`

Tests a pointer for &NULL; value.

### Macro

          null-pointer-p
          ptr

`ptr`

  A foreign object pointer.

returns

  The boolean flag.

### Description

A predicate testing if a pointer is has a &NULL; value.

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `+null-cstring-pointer+`

A constant &NULL; cstring pointer.
Constant

### Description

A &NULL; cstring pointer. This can be used for testing if a cstring returned by a function is &NULL;.

## `with-cast-pointer`

Wraps a body of code with a pointer cast to a new type.

### Macro

          with-cast-pointer
          (binding-name ptr type)
          &body;
          body

`binding-name`

  A symbol which will be bound to the casted object.

`ptr`

  A pointer to a foreign object.

`type`

  A foreign type of the object being pointed to.

returns

  The value of the object where the pointer points.

### Description

Executes BODY with POINTER cast to be a pointer to type TYPE. BINDING-NAME is will be bound to this value during the execution of BODY.

This is a no-op in AllegroCL but will wrap BODY in a LET form if BINDING-NAME is provided.

This macro is meant to be used in conjunction with DEREF-POINTER or DEREF-ARRAY. In Allegro CL the "cast" will actually take place in DEREF-POINTER or DEREF-ARRAY.

### Examples

         (with-foreign-object (size :int)
         ;; FOO is a foreign function returning a :POINTER-VOID
         (let ((memory (foo size)))
         (when (mumble)
         ;; at this point we know for some reason that MEMORY points
         ;; to an array of unsigned bytes
         (with-cast-pointer (memory :unsigned-byte)
         (dotimes (i (deref-pointer size :int))
         (do-something-with
         (deref-array memory '(:array :unsigned-byte) i)))))))

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.

## `def-foreign-var`

Defines a symbol macro to access a variable in foreign code

### Macro

          def-foreign-var
          name
          type
          module

`name`

  A string or list specificying the symbol macro's name. If it is a string, that names the foreign variable. A Lisp name is created by translating #\_ to #\- and by converting to upper-case in case-insensitive Lisp implementations. If it is a list, the first item is a string specifying the foreign variable name and the second it is a symbol stating the Lisp name.

`type`

  A foreign type of the foreign variable.

module

  A string specifying the module (or library) the foreign variable resides in. (Required by Lispworks)

### Description

Defines a symbol macro which can be used to access (get and set) the value of a variable in foreign code.

### Examples

#### C code

          int baz = 3;

          typedef struct {
          int x;
          double y;
          } foo_struct;

          foo_struct the_struct = { 42, 3.2 };

          int foo () {
          return baz;
          }

#### Lisp code

          (uffi:def-struct foo-struct
          (x :int)
          (y :double))

          (uffi:def-function ("foo" foo)
          ()
          :returning :int
          :module "foo")

          (uffi:def-foreign-var ("baz" *baz*) :int "foo")
          (uffi:def-foreign-var ("the_struct" *the-struct*) foo-struct "foo")

          *baz*
          => 3

          (incf *baz*)
          => 4

          (foo)
          => 4

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

None.