# 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

## Syntax

    	  allocate-foreign-object type &optional size => ptr

### Arguments and Values

`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.

ptr

- 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

## Syntax

    	  free-foreign-object ptr

### Arguments and Values

`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

## Syntax

    	  with-foreign-object (var type) &body body => form-return

### Arguments and Values

`var`

- The variable name to bind.

`type`

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

form-return

- 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

## Syntax

    	  size-of-foreign-type ftype

### Arguments and Values

`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

## Syntax

    	  pointer-address ptr => address

### Arguments and Values

`ptr`

- A pointer to a foreign object.

`address`

- 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

## Syntax

    	  deref-pointer ptr type => value

### Arguments and Values

`ptr`

- A pointer to a foreign object.

`type`

- A foreign type of the object being pointed to.

value

- 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

## Syntax

    	  ensure-char-character object => char

### Arguments and Values

`object`

- Either a character or a integer specifying a character code.

char

- 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

## Syntax

    	  ensure-char-integer object => int

### Arguments and Values

`object`

- Either a character or a integer specifying a character code.

int

- 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

## Syntax

    	  make-null-pointer type => ptr

### Arguments and Values

`type`

- A type of object to which the pointer refers.

`ptr`

- 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

## Syntax

    	  null-pointer-p ptr => is-null

### Arguments and Values

`ptr`

- A foreign object pointer.

is-null

- 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

## Syntax

    	  with-cast-pointer (binding-name ptr type) & body body => value

### Arguments and Values

`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.

value

- 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

## Syntax

    	  def-foreign-var name type module

### Arguments and Values

`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.