foreign-alloc (type &key initial-element initial-contents count null-terminated-p)

type -- A foreign type.
initial-element -- A Lisp object.
initial-contents -- A sequence.
count -- An integer. Defaults to 1 or the length of initial-contents if supplied.
null-terminated-p -- A boolean, false by default.
pointer -- A foreign pointer to the newly allocated memory.

The foreign-alloc function allocates enough memory to hold count objects of type type and returns a pointer. This memory must be explicitly freed using foreign-free once it is no longer needed.

If initial-element is supplied, it is used to initialize the count objects the newly allocated memory holds.

If an initial-contents sequence is supplied, it must have a length less than or equal to count and each of its elements will be used to initialize the contents of the newly allocated memory.

If count is omitted and initial-contents is specified, it will default to (length initial-contents).

initial-element and initial-contents are mutually exclusive.

When null-terminated-p is true, (1+ (max count (length initial-contents))) elements are allocated and the last one is set to NULL. Note that in this case type must be a pointer type (i.e. a type that canonicalizes to :pointer), otherwise an error is signaled.

  CFFI> (foreign-alloc :char)
  => #<A Mac Pointer #x102D80>     ; A pointer to 1 byte of memory.


  CFFI> (foreign-alloc :char :count 20)
  => #<A Mac Pointer #x1024A0>     ; A pointer to 20 bytes of memory.


  CFFI> (foreign-alloc :int :initial-element 12)
  => #<A Mac Pointer #x1028B0>
  CFFI> (mem-ref * :int)
  => 12


  CFFI> (foreign-alloc :int :initial-contents '(1 2 3))
  => #<A Mac Pointer #x102950>
  CFFI> (loop for i from 0 below 3
              collect (mem-aref * :int i))
  => (1 2 3)


  CFFI> (foreign-alloc :int :initial-contents #(1 2 3))
  => #<A Mac Pointer #x102960>
  CFFI> (loop for i from 0 below 3
              collect (mem-aref * :int i))
  => (1 2 3)


  ;;; Allocate a char** pointer that points to newly allocated memory
  ;;; by the :string type translator for the string "foo".
  CFFI> (foreign-alloc :string :initial-element "foo")
  => #<A Mac Pointer #x102C40>


  ;;; Allocate a null-terminated array of strings.
  ;;; (Note: FOREIGN-STRING-TO-LISP returns NIL when passed a null pointer)
  CFFI> (foreign-alloc :string
                       :initial-contents '("foo" "bar" "baz")
                       :null-terminated-p t)
  => #<A Mac Pointer #x102D20>
  CFFI> (loop for i from 0 below 4
              collect (mem-aref * :string i))
  => ("foo" "bar" "baz" NIL)
  CFFI> (progn
          (dotimes (i 3)
            (foreign-free (mem-aref ** :pointer i)))
          (foreign-free **))
  => nil