From c5115898210dbfa357c208c1bfe58049f7d6ff6d Mon Sep 17 00:00:00 2001 From: "Kevin M. Rosenberg" Date: Tue, 11 Nov 2003 05:12:43 +0000 Subject: [PATCH] r8112: convert from entities chapters to xinclude --- doc/Makefile.sgml | 114 -- doc/appendix.sgml | 30 - doc/appendix.xml | 5 + doc/bookinfo.sgml | 71 - doc/bookinfo.xml | 5 + doc/{uffi.sgml => entities.xml} | 21 +- doc/glossary.sgml | 16 - doc/glossary.xml | 5 + doc/intro.sgml | 108 -- doc/intro.xml | 5 + doc/notes.sgml | 89 -- doc/notes.xml | 5 + doc/preface.sgml | 12 - doc/preface.xml | 5 + doc/ref.sgml | 2462 ------------------------------- doc/ref.xml | 5 + doc/ref_aggregate.xml | 522 +++++++ doc/ref_declare.xml | 82 + doc/ref_func_libr.xml | 262 ++++ doc/ref_object.xml | 855 +++++++++++ doc/ref_primitive.xml | 272 ++++ doc/ref_string.xml | 503 +++++++ doc/uffi.xml | 46 +- 23 files changed, 2547 insertions(+), 2953 deletions(-) delete mode 100644 doc/Makefile.sgml delete mode 100644 doc/appendix.sgml delete mode 100644 doc/bookinfo.sgml rename doc/{uffi.sgml => entities.xml} (64%) delete mode 100644 doc/glossary.sgml delete mode 100644 doc/intro.sgml delete mode 100644 doc/notes.sgml delete mode 100644 doc/preface.sgml delete mode 100644 doc/ref.sgml create mode 100644 doc/ref_aggregate.xml create mode 100644 doc/ref_declare.xml create mode 100644 doc/ref_func_libr.xml create mode 100644 doc/ref_object.xml create mode 100644 doc/ref_primitive.xml create mode 100644 doc/ref_string.xml diff --git a/doc/Makefile.sgml b/doc/Makefile.sgml deleted file mode 100644 index a87f333..0000000 --- a/doc/Makefile.sgml +++ /dev/null @@ -1,114 +0,0 @@ -############################################################################## -# FILE IDENTIFICATION -# -# Name: Makefile -# Purpose: Makefile for the uffi documentation -# Programer: Kevin M. Rosenberg -# Date Started: Mar 2002 -# -# CVS Id: $Id$ -# -# This file, part of UFFI, is Copyright (c) 2002-2003 by Kevin M. Rosenberg -# -# UFFI users are granted the rights to distribute and use this software -# as governed by the terms of the Lisp Lesser GNU Public License -# (http://opensource.franz.com/preamble.html), also known as the LLGPL. -############################################################################## - - -# System variable to select catalog file -SYSTEM=debian -# SYSTEM=redhat - -# Nothing to configure beyond this point - -CATALOG=catalog.$(SYSTEM) - -# Custom DSSSL's -DSSSL_HTML=../dsssl/html/docbook.dsl -DSSSL_PRINT=dsssl/print/docbook.dsl - -DOCFILE_BASE_DEFAULT=uffi -DOCFILE_EXT_DEFAULT=sgml - -# Standard docfile processing - -ifndef DOCFILE_BASE -DOCFILE_BASE=${DOCFILE_BASE_DEFAULT} -endif - -ifndef DOCFILE_EXT -DOCFILE_EXT=${DOCFILE_EXT_DEFAULT} -endif - -DOCFILE=${DOCFILE_BASE}.${DOCFILE_EXT} -TEXFILE=${DOCFILE_BASE}.tex -PDFFILE=${DOCFILE_BASE}.pdf -PSFILE=${DOCFILE_BASE}.ps -DVIFILE=${DOCFILE_BASE}.dvi -TMPFILES=${DOCFILE_BASE}.aux ${DOCFILE_BASE}.out ${DOCFILE_BASE}.log -DOCFILES=$(shell echo *.sgml) - -.PHONY: all -all: html pdf - -.PHONY: dist -dist: html pdf - -.PHONY: doc -doc: html pdf - -CHECK=nsgmls -s -C ${CATALOG} || exit 1 - -.PHONY: check -check: - @$(CHECK) - -.PHONY: html -html: html.tar.gz - -html.tar.gz: $(DOCFILES) Makefile - @$(CHECK) - @( rm -rf html ; mkdir html; cd html ; jade -t sgml -c ../${CATALOG} -d ${DSSSL_HTML} ../${DOCFILE} > /dev/null; cp book1.html index.html; cd ..; GZIP='-9' tar czf html.tar.gz html) - -.PHONY: tex -tex: ${TEXFILE} - -${TEXFILE}: ${DOCFILES} - @$(CHECK) - @jade -t tex -c ${CATALOG} -d ${DSSSL_PRINT} ${DOCFILE} > /dev/null - -.PHONY: pdf -pdf: ${PDFFILE} - -${PDFFILE}: ${DOCFILES} - @jade -t tex -c ${CATALOG} -d ${DSSSL_PRINT} ${DOCFILE} > /dev/null - @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null - @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null - @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null - @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null - -.PHONY: dvi -dvi: ${DVIFILE} - -${DVIFILE}: ${TEXFILE} - @jadetex ${TEXFILE} > /dev/null - @jadetex ${TEXFILE} > /dev/null - @jadetex ${TEXFILE} > /dev/null - @jadetex ${TEXFILE} > /dev/null - -.PHONY: ps -ps: ${PSFILE} - -${PSFILE}: ${DVIFILE} - @dvips -o ${PSFILE} ${DVIFILE} > /dev/null - -.PHONY: clean -clean: - @rm -f *~ *.bak *.orig \#*\# .\#* texput.log - @rm -rf html ${PSFILE} - @rm -f ${TMPFILES} - @rm -f ${DVIFILE} ${TEXFILE} - -.PHONY: distclean -distclean: clean diff --git a/doc/appendix.sgml b/doc/appendix.sgml deleted file mode 100644 index 2c89396..0000000 --- a/doc/appendix.sgml +++ /dev/null @@ -1,30 +0,0 @@ - - - - Installation - - Download &uffi; - -You need to download the &uffi; package from its web -home. -You also need to have a copy of &asdf;. If you need a copy of -&asdf;, it is included in the - - CCLAN package. You can download -the file defsystem.lisp from the CVS -tree. - - - - Installation - - After downloading and installing &asdf;, simply - push the - directory containing &uffi; into - asdf:*central-registry* variable. Whenever you -want to load the &uffi; package, use the function - (asdf:oos 'asdf:load-op :uffi). - - - diff --git a/doc/appendix.xml b/doc/appendix.xml index 0ae9b8e..5e5c495 100644 --- a/doc/appendix.xml +++ b/doc/appendix.xml @@ -1,4 +1,9 @@ + +%myents; +]> Installation diff --git a/doc/bookinfo.sgml b/doc/bookinfo.sgml deleted file mode 100644 index 0982dff..0000000 --- a/doc/bookinfo.sgml +++ /dev/null @@ -1,71 +0,0 @@ - - - - - &uffi; Reference Guide - - Kevin - M. - Rosenberg - - Heart Hospital of New Mexico -
- kevin@rosenberg.net - 504 Elm Street N.E. - Albuquerque - New Mexico - 87102 -
- - - - - $Id$ - File $Date$ - - - 2002-2003 - Kevin M. Rosenberg - - - - - The &uffi; package was designed and - written by Kevin M. Rosenberg. - - - - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with no Invariant Sections, with the no - Front-Cover Texts, and with no Back-Cover Texts. - A copy of the license is included in the &uffi; distribution. - - - - Allegro CL® is a registered - trademark of Franz Inc. - - - - Lispworks® is a registered - trademark of Xanalys Inc. - - - - Microsoft - Windows® is a registered trademark of - Microsoft Inc. - - - - Other brand or - product names are the registered trademarks or trademarks of - their respective holders. - - - - - diff --git a/doc/bookinfo.xml b/doc/bookinfo.xml index 3672d5f..fbad7ee 100644 --- a/doc/bookinfo.xml +++ b/doc/bookinfo.xml @@ -1,4 +1,9 @@ + +%myents; +]> &uffi; Reference Guide diff --git a/doc/uffi.sgml b/doc/entities.xml similarity index 64% rename from doc/uffi.sgml rename to doc/entities.xml index 58693d7..da6dc7e 100644 --- a/doc/uffi.sgml +++ b/doc/entities.xml @@ -1,6 +1,5 @@ - + -UFFI"> FFI"> CMUCL"> @@ -17,21 +16,3 @@ C"> defsystem"> ASDF"> - - - - - - - -]> - - -&bookinfo; -&preface; -&intro; -¬es; -&ref; -&appendix; -&glossary; - diff --git a/doc/glossary.sgml b/doc/glossary.sgml deleted file mode 100644 index 008ada1..0000000 --- a/doc/glossary.sgml +++ /dev/null @@ -1,16 +0,0 @@ - - - - - Foreign Function Interface - FFI) - - - - An interface to a C-compatible library. - - - - - - diff --git a/doc/glossary.xml b/doc/glossary.xml index 4044eab..f539c33 100644 --- a/doc/glossary.xml +++ b/doc/glossary.xml @@ -1,4 +1,9 @@ + +%myents; +]> diff --git a/doc/intro.sgml b/doc/intro.sgml deleted file mode 100644 index d71f92a..0000000 --- a/doc/intro.sgml +++ /dev/null @@ -1,108 +0,0 @@ - - - - Introduction - - Purpose - This reference guide describes - &uffi;, a package that provides a cross-implementation - interface from Common Lisp to C-language compatible libraries. - - - - - Background - - - Every Common Lisp implementation has - a method for interfacing to C-language compatible - libraries. These methods are often termed a - Foreign Function Library Interface - (&ffi;). Unfortunately, these methods vary widely - amongst - implementations, thus preventing the writing of a portable FFI to a -particular C-library. - - - &uffi; gathers a common subset of functionality between Common Lisp - implementations. &uffi; wraps this common subset of functionality with - it's own syntax and provides macro translation of uffi functions into - the specific syntax of supported Common Lisp implementations. - - - Developers who use &uffi; to interface with C libraries will - automatically have their code function in each of uffi's supported - implementations. - - - - - Supported Implementations - The primary tested and supported platforms for &uffi; are: - - - &acl; v6.2 on Debian GNU/Linux -FreeBSD 4.5, Solaris v2.8, and Microsoft Windows XP. - &lw; v4.2 on Debian GNU/Linux and Microsoft Windows XP. - &cmucl; 18d on Debian GNU/Linux, FreeBSD 4.5, and Solaris 2.8 - &sbcl; 0.7.8 on Debian GNU/Linux - &scl; 1.1.1 on Debian GNU/Linux - &openmcl; 0.13 on Debian GNU/Linux for PowerPC - - Beta code is included with &uffi; for - - - &openmcl; and &mcl; with MacOSX - - - - - Design - - Overview - - &uffi; was designed as a cross-implementation - compatible Foreign Function Interface. - Necessarily, - only a common subset of functionality can be - provided. Likewise, not every optimization for that a specific - implementation provides can be supported. Wherever possible, - though, implementation-specific optimizations are invoked. - - - - - Priorities - - The design of &uffi; is dictated by the order of these priorities: - - - - - Code using &uffi; must operate correctly on all - supported implementations. - - - - - Take advantage of implementation-specific optimizations. Ideally, - there will not a situation where an implementation-specific - &ffi; will be chosen due to lack of optimizations in &uffi;. - - - - Provide a simple interface to developers using -&uffi;. This priority is quite a bit lower than the above priorities. -This lower priority is manifest by programmers having to pass types in -pointer and array dereferencing, needing to use -cstring wrapper functions, and the use of -ensure-char-character and ensure-char-integer functions. My hope is -that the developer inconvenience will be outweighed by the generation -of optimized code that is cross-implementation compatible. - - - - - - - diff --git a/doc/intro.xml b/doc/intro.xml index 43ea251..cdabd65 100644 --- a/doc/intro.xml +++ b/doc/intro.xml @@ -1,4 +1,9 @@ + +%myents; +]> Introduction diff --git a/doc/notes.sgml b/doc/notes.sgml deleted file mode 100644 index c4e8603..0000000 --- a/doc/notes.sgml +++ /dev/null @@ -1,89 +0,0 @@ - - - - Programming Notes - - - Implementation Specific Notes - - - - &acl; - - - - - &lw; - - - - - &cmucl; - - - - - - - Foreign Object Representation and Access - There are two main approaches used to represent foreign - objects: an integer that represents an address in memory, and a - object that also includes run-time typing. The advantage of - run-time typing is the system can dereference pointers and perform - array access without those functions requiring a type at the cost - of additional overhead to generate and store the run-time - typing. The advantage of integer representation, at least for - &acl;, is that the compiler can generate inline code to - dereference pointers. Further, the overhead of the run-time type - information is eliminated. The disadvantage is the program must - then supply - the type to the functions to dereference objects and array. - - - - - Optimizing Code Using UFFI - - Background - - Two implementions have different techniques to optimize - (open-code) foreign objects. &acl; can open-code foreign - object - access if pointers are integers and the type of object is - specified in the access function. Thus, &uffi; represents objects - in &acl; as integers which don't have type information. - - &cmucl; works best when keeping objects as typed - objects. However, it's compiler can open-code object access when - the object type is specified in declare - commands and in :type specifiers in - defstruct and defclass. - &lw;, in converse to &acl; and &cmucl; does not do - any open coding of object access. &lw;, by default, maintains - objects with run-time typing. - - - Cross-Implementation Optimization - - To fully optimize across platforms, both explicit type - information must be passed to dereferencing of pointers and - arrays. Though this optimization only helps with &acl;, &uffi; - is designed to require this type information be passed the - dereference functions. Second, declarations of type should be - made in functions, structures, and classes where foreign - objects will be help. This will optimize access for &lw; - - - Here is an example that should both methods being used for - maximum cross-implementation optimization: - -(uffi:def-type the-struct-type-def the-struct-type) -(let ((a-foreign-struct (allocate-foreign-object 'the-struct-type))) - (declare 'the-struct-type-def a-foreign-struct) - (get-slot-value a-foreign-struct 'the-struct-type 'field-name)) - - - - - - diff --git a/doc/notes.xml b/doc/notes.xml index a492c2d..1ebbb1a 100644 --- a/doc/notes.xml +++ b/doc/notes.xml @@ -1,4 +1,9 @@ + +%myents; +]> Programming Notes diff --git a/doc/preface.sgml b/doc/preface.sgml deleted file mode 100644 index d9ec7df..0000000 --- a/doc/preface.sgml +++ /dev/null @@ -1,12 +0,0 @@ - - - - Preface - This reference guide describes the usage and features - of &uffi;. The first - chapter provides an overview to the design of &uffi;. - Following that chapter is the reference section for all user - accessible functions of &uffi;. The appendix covers the - installation and implementation-specifc features of &uffi;. - - diff --git a/doc/preface.xml b/doc/preface.xml index fb49525..373e119 100644 --- a/doc/preface.xml +++ b/doc/preface.xml @@ -1,4 +1,9 @@ + +%myents; +]> Preface diff --git a/doc/ref.sgml b/doc/ref.sgml deleted file mode 100644 index d19c7a6..0000000 --- a/doc/ref.sgml +++ /dev/null @@ -1,2462 +0,0 @@ - - - - - Declarations - - - - Overview - Declarations are used to give the compiler optimizing - information about foreign types. Currently, only &cmucl; - supports declarations. On &acl; and &lw;, these expressions - declare the type generically as &t; - - - - - - - def-type - Defines a Common Lisp type. - - Macro - - - Syntax - - def-type name type - - - - Arguments and Values - - - name - - A symbol naming the type - - - - type - - A form that is evaluated that specifies the &uffi; type. - - - - - - - Description - Defines a Common Lisp type based on a &uffi; type. - - - - Examples - -(def-type char-ptr '(* :char)) -... -(defun foo (ptr) - (declare (type char-ptr ptr)) - ... - - - - Side Effects - Defines a new &cl; type. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - Primitive Types - - Overview - - Primitive types have a single value, these include - characters, numbers, and pointers. They are all symbols in - the keyword package. - - - - :char - Signed 8-bits. A -dereferenced :char pointer returns an character. - - - :unsigned-char - Unsigned 8-bits. A dereferenced :unsigned-char -pointer returns an character. - - - :byte - Signed 8-bits. A -dereferenced :byte pointer returns an integer. - - - :unsigned-byte - Unsigned 8-bits. A -dereferenced :unsigned-byte pointer returns an integer. - - - :short - Signed 16-bits. - - - :unsigned-short - Unsigned 16-bits. - - - :int - Signed 32-bits. - - - :unsigned-int - Unsigned 32-bits. - - - :long - Signed 32 or 64 bits, depending upon the platform. - - - :unsigned-long - Unsigned 32 or 64 bits, depending upon the platform. - - - :float - 32-bit floating point. - - - :double - 64-bit floating point. - - - :cstring - -A &null; terminated string used for passing and returning characters strings with a &c; function. - - - - :void - -The absence of a value. Used to indicate that a function does not return a value. - - - :pointer-void - -Points to a generic object. - - - * - Used to declare a pointer to an object - - - - - - - def-constant - Binds a symbol to a constant. - - Macro - - - Syntax - - def-constant name value &key export - - - - Arguments and Values - - - name - - A symbol that will be bound to the value. - - - - - value - - An evaluated form that is bound the the name. - - - - - export - - When &t;, the name is exported from the current package. The default is &nil; - - - - - - Description - - This is a thin wrapper around - defconstant. It evaluates at - compile-time and optionally exports the symbol from the package. - - - - Examples - -(def-constant pi2 (* 2 pi)) -(def-constant exported-pi2 (* 2 pi) :export t) - - - - Side Effects - Creates a new special variable.. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - def-foreign-type - Defines a new foreign type. - - Macro - - - Syntax - - def-foreign-type name type - - - - Arguments and Values - - - name - - A symbol naming the new foreign type. - - - - - value - - A form that is not evaluated that defines the new -foreign type. - - - - - - - Description - Defines a new foreign type. - - - - Examples - -(def-foreign-type my-generic-pointer :pointer-void) -(def-foreign-type a-double-float :double-float) -(def-foreign-type char-ptr (* :char)) - - - - Side Effects - Defines a new foreign type. - - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - null-char-p - Tests a character for &null; value. - - Macro - - - Syntax - - null-char-p char => is-null - - - - Arguments and Values - - - char - - A character or integer. - - - - - is-null - - A boolean flag indicating if char is a &null; value. - - - - - - - Description - - A predicate testing if a character or integer is &null;. This -abstracts the difference in implementations where some return a -character and some return a -integer whence dereferencing a -C character pointer. - - - - Examples - -(def-array-pointer ca :unsigned-char) -(let ((fs (convert-to-foreign-string "ab"))) - (values (null-char-p (deref-array fs 'ca 0)) - (null-char-p (deref-array fs 'ca 2)))) -=> &nil; - &t; - - - - Side Effects - None. - - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - Aggregate Types - - Overview - - Aggregate types are comprised of one or more primitive types. - - - - - - def-enum - Defines a &c; enumeration. - - Macro - - - Syntax - - def-enum name fields &key separator-string - - - - Arguments and Values - - - name - - A symbol that names the enumeration. - - - - - fields - - A list of field defintions. Each definition can be -a symbol or a list of two elements. Symbols get assigned a value of the -current counter which starts at 0 and -increments by 1 for each subsequent symbol. It the field definition is a list, the first position is the symbol and the second -position is the value to assign the the symbol. The current counter gets set -to 1+ this value. - - - - - separator-string - - A string that governs the creation of constants. The -default is "#". - - - - - - Description - - Declares a &c; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant -values are created by the concatenation of the -enumeration name, separator-string, and field symbol. Also creates -a foreign type with the name name of type -:int. - - - - Examples - -(def-enum abc (:a :b :c)) -;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines -;; the foreign type "abc" to be :int - -(def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-") -;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines -;; the foreign type efoo to be :int - - - - Side Effects - Creates a :int foreign type, defines constants. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - def-struct - Defines a &c; structure. - - Macro - - - Syntax - - def-struct name &rest fields - - - - Arguments and Values - - - name - - A symbol that names the structure. - - - - - fields - - A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type. - - - - - - - Description - - Declares a structure. A special type is available as a slot -in the field. It is a pointer that points to an instance of the parent -structure. It's type is :pointer-self. - - - - - Examples - -(def-struct foo (a :unsigned-int) - (b (* :char)) - (c (:array :int 10)) - (next :pointer-self)) - - - - Side Effects - Creates a foreign type. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - get-slot-value - Retrieves a value from a slot of a structure. - - Macro - - - Syntax - - get-slot-value obj type field => value - - - - Arguments and Values - - - obj - - A pointer to foreign structure. - - - - - type - - A name of the foreign structure. - - - - - field - - A name of the desired field in foreign structure. - - - - - value - - The value of the field in the structure. - - - - - - - Description - - Accesses a slot value from a structure. - - - - Examples - -(get-slot-value foo-ptr 'foo-structure 'field-name) - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - get-slot-pointer - Retrieves a pointer from a slot of a structure. - - Macro - - - Syntax - - get-slot-pointer obj type field => pointer - - - - Arguments and Values - - - obj - - A pointer to foreign structure. - - - - - type - - A name of the foreign structure. - - - - - field - - A name of the desired field in foreign structure. - - - - - pointer - - The value of the field in the structure. - - - - - - - Description - - This is similar to get-slot-value. It - is used when the value of a slot is a pointer type. - - - - Examples - -(get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr) - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - def-array-pointer - Defines a pointer to a array of type. - - Macro - - - Syntax - - def-array-pointer name type - - - - Arguments and Values - - - name - - A name of the new foreign type. - - - - - type - - The foreign type of the array elements. - - - - - - - Description - - Defines a type tat is a pointer to an array of type. - - - - Examples - -(def-array-pointer byte-array-pointer :unsigned-char) - - - - Side Effects - Defines a new foreign type. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - deref-array - Deference an array. - - Macro - - - Syntax - - deref-array array type positon => value - - - - Arguments and Values - - - array - - A foreign array. - - - - - type - - The foreign type of the array. - - - - - position - - An integer specifying the position to retrieve from -the array. - - - - - value - - The value stored in the position of the array. - - - - - - - Description - - Dereferences (retrieves) the value of an array element. - - - - Examples - -(def-array-pointer ca :char) -(let ((fs (convert-to-foreign-string "ab"))) - (values (null-char-p (deref-array fs 'ca 0)) - (null-char-p (deref-array fs 'ca 2)))) -=> &nil; - &t; - - - - 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. - - - - - - def-union - Defines a foreign union type. - - Macro - - - Syntax - - def-union name &rest fields - - - - Arguments and Values - - - name - - A name of the new union type. - - - - - fields - - A list of fields of the union. - - - - - - - Description - - Defines a foreign union type. - - - - Examples - -(def-union test-union - (a-char :char) - (an-int :int)) - -(let ((u (allocate-foreign-object 'test-union)) - (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256))) - (prog1 - (ensure-char-character (get-slot-value u 'test-union 'a-char)) - (free-foreign-object u))) -=> #\A - - - - Side Effects - Defines a new foreign type. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - - 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 - - - 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. If - BINDING-NAME is provided the cast pointer will be bound to this - name during the execution of BODY. If BINDING-NAME is not provided - POINTER must be a name bound to the pointer which should be - cast. This name will be bound to the cast pointer 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. - - - - - - - Strings - -Overview - - - &uffi; has functions to two types of -C-compatible - strings: cstring and -foreign strings. - -cstrings are used only as parameters to and from -functions. In some implementations a cstring is not a foreign type but -rather the Lisp string itself. On other platforms a cstring is a newly -allocated foreign vector for storing characters. The following is an -example of using cstrings to both send and return a value. - - - -(uffi:def-function ("getenv" c-getenv) - ((name :cstring)) - :returning :cstring) - -(defun my-getenv (key) - "Returns an environment variable, or NIL if it does not exist" - (check-type key string) - (uffi:with-cstring (key-native key) - (uffi:convert-from-cstring (c-getenv key-native)))) - - - In contrast, foreign strings are always a foreign vector of -characters which have memory allocated. Thus, if you need to allocate -memory to hold the return value of a string, you must use a foreign -string and not a cstring. The following is an example of using a foreign -string for a return value. - - -(uffi:def-function ("gethostname" c-gethostname) - ((name (* :unsigned-char)) - (len :int)) - :returning :int) - -(defun gethostname () - "Returns the hostname" - (let* ((name (uffi:allocate-foreign-string 256)) - (result-code (c-gethostname name 256)) - (hostname (when (zerop result-code) - (uffi:convert-from-foreign-string name)))) - (uffi:free-foreign-object name) - (unless (zerop result-code) - (error "gethostname() failed.")))) - - - Foreign functions that return pointers to freshly allocated -strings should in general not return cstrings, but foreign strings. -(There is no portable way to release such cstrings from Lisp.) The -following is an example of handling such a function. - - -(uffi:def-function ("readline" c-readline) - ((prompt :cstring)) - :returning (* :char)) - -(defun readline (prompt) - "Reads a string from console with line-editing." - (with-cstring (c-prompt prompt) - (let* ((c-str (c-readline c-prompt)) - (str (convert-from-foreign-string c-str))) - (uffi:free-foreign-object c-str) - str))) - - - - - - - convert-from-cstring - Converts a cstring to a Lisp string. - - Macro - - - Syntax - - convert-from-cstring cstring => string - - - - Arguments and Values - - - cstring - - A cstring. - - - - - string - - A Lisp string. - - - - - - - Description - - Converts a Lisp string to a cstring. This is -most often used when processing the results of a foreign function -that returns a cstring. - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - convert-to-cstring - Converts a Lisp string to a cstring. - - Macro - - - Syntax - - convert-to-cstring string => cstring - - - - Arguments and Values - - - string - - A Lisp string. - - - - - cstring - - A cstring. - - - - - - - Description - - Converts a Lisp string to a - cstring. The - cstring should be freed with - free-cstring. - - - - Side Effects - On some implementations, this function allocates memory. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - free-cstring - Free memory used by cstring. - - Macro - - - Syntax - - free-cstring cstring - - - - Arguments and Values - - - cstring - - A cstring. - - - - - - - Description - - Frees any memory possibly allocated by - convert-to-cstring. On some implementions, a cstring is just the Lisp string itself. - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - with-cstring - Binds a newly created cstring. - - Macro - - - Syntax - - with-cstring (cstring string) {body} - - - - Arguments and Values - - - cstring - - A symbol naming the cstring to be created. - - - - - string - - A Lisp string that will be translated to a cstring. - - - - - body - - The body of where the cstring will be bound. - - - - - - - Description - - Binds a symbol to a cstring created from conversion of a string. Automatically frees the cstring. - - - - Examples - - -(def-function ("getenv" c-getenv) - ((name :cstring)) - :returning :cstring) - -(defun getenv (key) - "Returns an environment variable, or NIL if it does not exist" - (check-type key string) - (with-cstring (key-cstring key) - (convert-from-cstring (c-getenv key-cstring)))) - - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - convert-from-foreign-string - Converts a foreign string into a Lisp string. - - Macro - - - Syntax - - convert-from-foreign-string foreign-string &key length null-terminated-p => string - - - - Arguments and Values - - - foreign-string - - A foreign string. - - - - - length - - The length of the foreign string to -convert. The default is the length of the string until a &null; -character is reached. - - - - - null-terminated-p - - A boolean flag with a default value of &t; When true, -the string is converted until the first &null; character is reached. - - - - - string - - A Lisp string. - - - - - - - Description - - Returns a Lisp string from a foreign string. -Can translated ASCII and binary strings. - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - convert-to-foreign-string - Converts a Lisp string to a foreign string. - - Macro - - - Syntax - - convert-to-foreign-string string => foreign-string - - - - Arguments and Values - - - string - - A Lisp string. - - - - - foreign-string - - A foreign string. - - - - - - - Description - - Converts a Lisp string to a foreign string. Memory should be - freed with free-foreign-object. - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - - allocate-foreign-string - Allocates space for a foreign string. - - Macro - - - Syntax - - allocate-foreign-string size &key unsigned => foreign-string - - - - Arguments and Values - - - size - - The size of the space to be allocated in bytes. - - - - - unsigned - - A boolean flag with a default value of &t;. When true, -marks the pointer as an :unsigned-char. - - - - - foreign-string - - A foreign string which has undefined contents. - - - - - - - Description - - Allocates space for a foreign string. Memory should - be freed with free-foreign-object. - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - Functions & Libraries - - - - def-function - Declares a function. - - Macro - - - Syntax - - def-function name args &key module returning - - - - Arguments and Values - - - name - - A string or list specificying the function name. If it is a string, that names the foreign function. 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 function name and the second it is a symbol stating the Lisp name. - - - - - args - - A list of argument declarations. If &nil;, indicates that the function does not take any arguments. - - - - - module - - A string specifying which module (or library) that the foreign function resides. (Required by Lispworks) - - - - returning - - A declaration specifying the result type of the -foreign function. If :void indicates module does not return any value. - - - - - - - Description - Declares a foreign function. - - - - Examples - -(def-function "gethostname" - ((name (* :unsigned-char)) - (len :int)) - :returning :int) - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - load-foreign-library - Loads a foreign library. - - Function - - - Syntax - - load-foreign-library filename &key module supporting-libraries force-load => success - - - - Arguments and Values - - - filename - - A string or pathname specifying the library location -in the filesystem. At least one implementation (&lw;) can not -accept a logical pathname. - - - - - module - - A string designating the name of the module to apply -to functions in this library. (Required for Lispworks) - - - - - supporting-libraries - - A list of strings naming the libraries required to -link the foreign library. (Required by CMUCL) - - - - - force-load - - Forces the loading of the library if it has been previously loaded. - - - - - success - - A boolean flag, &t; if the library was able to be -loaded successfully or if the library has been previously loaded, -otherwise &nil;. - - - - - - - Description - Loads a foreign library. Applies a module name to functions -within the library. Ensures that a library is only loaded once during -a session. A library can be reloaded by using the :force-load key. - - - - Examples - - (load-foreign-library #p"/usr/lib/libmysqlclient.so" - :module "mysql" - :supporting-libraries '("c")) - => T - - - - Side Effects - Loads the foreign code into the Lisp system. - - - - Affected by - Ability to load the file. - - - Exceptional Situations - None. - - - - - - find-foreign-library - Finds a foreign library file. - - Function - - - Syntax - - find-foreign-library names directories & drive-letters types => path - - - - Arguments and Values - - - names - - A string or list of strings containing the base name of the library file. - - - - - directories - - A string or list of strings containing the directory the library file. - - - - - drive-letters - - A string or list of strings containing the drive letters for the library file. - - - - - types - - A string or list of strings containing the file type of the library file. Default -is &nil;. If &nil;, will use a default type based on the currently running implementation. - - - - - path - - A path containing the path found, or &nil; if the library file was not found. - - - - - - - Description - Finds a foreign library by searching through a number of possible locations. Returns -the path of the first found file. - - - - Examples - -(find-foreign-library '("libmysqlclient" "libmysql") - '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/") - :types '("so" "dll") - :drive-letters '("C" "D" "E")) -=> #P"D:\\mysql\\lib\\opt\\libmysql.dll" - - - - Side Effects - None. - - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - diff --git a/doc/ref.xml b/doc/ref.xml index 3196a39..885bfca 100644 --- a/doc/ref.xml +++ b/doc/ref.xml @@ -1,4 +1,9 @@ + +%myents; +]> Declarations diff --git a/doc/ref_aggregate.xml b/doc/ref_aggregate.xml new file mode 100644 index 0000000..401c281 --- /dev/null +++ b/doc/ref_aggregate.xml @@ -0,0 +1,522 @@ + + +%myents; +]> + + + Aggregate Types + + Overview + + Aggregate types are comprised of one or more primitive types. + + + + + + def-enum + Defines a &c; enumeration. + + Macro + + + Syntax + + def-enum name fields &key separator-string + + + + Arguments and Values + + + name + + A symbol that names the enumeration. + + + + + fields + + A list of field defintions. Each definition can be +a symbol or a list of two elements. Symbols get assigned a value of the +current counter which starts at 0 and +increments by 1 for each subsequent symbol. It the field definition is a list, the first position is the symbol and the second +position is the value to assign the the symbol. The current counter gets set +to 1+ this value. + + + + + separator-string + + A string that governs the creation of constants. The +default is "#". + + + + + + Description + + Declares a &c; enumeration. It generates constants with integer values for the elements of the enumeration. The symbols for the these constant +values are created by the concatenation of the +enumeration name, separator-string, and field symbol. Also creates +a foreign type with the name name of type +:int. + + + + Examples + +(def-enum abc (:a :b :c)) +;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines +;; the foreign type "abc" to be :int + +(def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-") +;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines +;; the foreign type efoo to be :int + + + + Side Effects + Creates a :int foreign type, defines constants. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + def-struct + Defines a &c; structure. + + Macro + + + Syntax + + def-struct name &rest fields + + + + Arguments and Values + + + name + + A symbol that names the structure. + + + + + fields + + A variable number of field defintions. Each definition is a list consisting of a symbol naming the field followed by its foreign type. + + + + + + + Description + + Declares a structure. A special type is available as a slot +in the field. It is a pointer that points to an instance of the parent +structure. It's type is :pointer-self. + + + + + Examples + +(def-struct foo (a :unsigned-int) + (b (* :char)) + (c (:array :int 10)) + (next :pointer-self)) + + + + Side Effects + Creates a foreign type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + get-slot-value + Retrieves a value from a slot of a structure. + + Macro + + + Syntax + + get-slot-value obj type field => value + + + + Arguments and Values + + + obj + + A pointer to foreign structure. + + + + + type + + A name of the foreign structure. + + + + + field + + A name of the desired field in foreign structure. + + + + + value + + The value of the field in the structure. + + + + + + + Description + + Accesses a slot value from a structure. + + + + Examples + +(get-slot-value foo-ptr 'foo-structure 'field-name) + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + get-slot-pointer + Retrieves a pointer from a slot of a structure. + + Macro + + + Syntax + + get-slot-pointer obj type field => pointer + + + + Arguments and Values + + + obj + + A pointer to foreign structure. + + + + + type + + A name of the foreign structure. + + + + + field + + A name of the desired field in foreign structure. + + + + + pointer + + The value of the field in the structure. + + + + + + + Description + + This is similar to get-slot-value. It + is used when the value of a slot is a pointer type. + + + + Examples + +(get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr) + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + def-array-pointer + Defines a pointer to a array of type. + + Macro + + + Syntax + + def-array-pointer name type + + + + Arguments and Values + + + name + + A name of the new foreign type. + + + + + type + + The foreign type of the array elements. + + + + + + + Description + + Defines a type tat is a pointer to an array of type. + + + + Examples + +(def-array-pointer byte-array-pointer :unsigned-char) + + + + Side Effects + Defines a new foreign type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + deref-array + Deference an array. + + Macro + + + Syntax + + deref-array array type positon => value + + + + Arguments and Values + + + array + + A foreign array. + + + + + type + + The foreign type of the array. + + + + + position + + An integer specifying the position to retrieve from +the array. + + + + + value + + The value stored in the position of the array. + + + + + + + Description + + Dereferences (retrieves) the value of an array element. + + + + Examples + +(def-array-pointer ca :char) +(let ((fs (convert-to-foreign-string "ab"))) + (values (null-char-p (deref-array fs 'ca 0)) + (null-char-p (deref-array fs 'ca 2)))) +=> &nil; + &t; + + + + 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. + + + + + + def-union + Defines a foreign union type. + + Macro + + + Syntax + + def-union name &rest fields + + + + Arguments and Values + + + name + + A name of the new union type. + + + + + fields + + A list of fields of the union. + + + + + + + Description + + Defines a foreign union type. + + + + Examples + +(def-union test-union + (a-char :char) + (an-int :int)) + +(let ((u (allocate-foreign-object 'test-union)) + (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256))) + (prog1 + (ensure-char-character (get-slot-value u 'test-union 'a-char)) + (free-foreign-object u))) +=> #\A + + + + Side Effects + Defines a new foreign type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + diff --git a/doc/ref_declare.xml b/doc/ref_declare.xml new file mode 100644 index 0000000..49b6c7b --- /dev/null +++ b/doc/ref_declare.xml @@ -0,0 +1,82 @@ + + +%myents; +]> + + + Declarations + + + + Overview + Declarations are used to give the compiler optimizing + information about foreign types. Currently, only &cmucl; + supports declarations. On &acl; and &lw;, these expressions + declare the type generically as &t; + + + + + + + def-type + Defines a Common Lisp type. + + Macro + + + Syntax + + def-type name type + + + + Arguments and Values + + + name + + A symbol naming the type + + + + type + + A form that is evaluated that specifies the &uffi; type. + + + + + + + Description + Defines a Common Lisp type based on a &uffi; type. + + + + Examples + +(def-type char-ptr '(* :char)) +... +(defun foo (ptr) + (declare (type char-ptr ptr)) + ... + + + + Side Effects + Defines a new &cl; type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + diff --git a/doc/ref_func_libr.xml b/doc/ref_func_libr.xml new file mode 100644 index 0000000..358abe6 --- /dev/null +++ b/doc/ref_func_libr.xml @@ -0,0 +1,262 @@ + + +%myents; +]> + + + Functions & Libraries + + + + def-function + Declares a function. + + Macro + + + Syntax + + def-function name args &key module returning + + + + Arguments and Values + + + name + + A string or list specificying the function name. If it is a string, that names the foreign function. 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 function name and the second it is a symbol stating the Lisp name. + + + + + args + + A list of argument declarations. If &nil;, indicates that the function does not take any arguments. + + + + + module + + A string specifying which module (or library) that the foreign function resides. (Required by Lispworks) + + + + returning + + A declaration specifying the result type of the +foreign function. If :void indicates module does not return any value. + + + + + + + Description + Declares a foreign function. + + + + Examples + +(def-function "gethostname" + ((name (* :unsigned-char)) + (len :int)) + :returning :int) + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + load-foreign-library + Loads a foreign library. + + Function + + + Syntax + + load-foreign-library filename &key module supporting-libraries force-load => success + + + + Arguments and Values + + + filename + + A string or pathname specifying the library location +in the filesystem. At least one implementation (&lw;) can not +accept a logical pathname. + + + + + module + + A string designating the name of the module to apply +to functions in this library. (Required for Lispworks) + + + + + supporting-libraries + + A list of strings naming the libraries required to +link the foreign library. (Required by CMUCL) + + + + + force-load + + Forces the loading of the library if it has been previously loaded. + + + + + success + + A boolean flag, &t; if the library was able to be +loaded successfully or if the library has been previously loaded, +otherwise &nil;. + + + + + + + Description + Loads a foreign library. Applies a module name to functions +within the library. Ensures that a library is only loaded once during +a session. A library can be reloaded by using the :force-load key. + + + + Examples + + (load-foreign-library #p"/usr/lib/libmysqlclient.so" + :module "mysql" + :supporting-libraries '("c")) + => T + + + + Side Effects + Loads the foreign code into the Lisp system. + + + + Affected by + Ability to load the file. + + + Exceptional Situations + None. + + + + + + find-foreign-library + Finds a foreign library file. + + Function + + + Syntax + + find-foreign-library names directories & drive-letters types => path + + + + Arguments and Values + + + names + + A string or list of strings containing the base name of the library file. + + + + + directories + + A string or list of strings containing the directory the library file. + + + + + drive-letters + + A string or list of strings containing the drive letters for the library file. + + + + + types + + A string or list of strings containing the file type of the library file. Default +is &nil;. If &nil;, will use a default type based on the currently running implementation. + + + + + path + + A path containing the path found, or &nil; if the library file was not found. + + + + + + + Description + Finds a foreign library by searching through a number of possible locations. Returns +the path of the first found file. + + + + Examples + +(find-foreign-library '("libmysqlclient" "libmysql") + '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/") + :types '("so" "dll") + :drive-letters '("C" "D" "E")) +=> #P"D:\\mysql\\lib\\opt\\libmysql.dll" + + + + Side Effects + None. + + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + diff --git a/doc/ref_object.xml b/doc/ref_object.xml new file mode 100644 index 0000000..d5dfdee --- /dev/null +++ b/doc/ref_object.xml @@ -0,0 +1,855 @@ + + +%myents; +]> + + + 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 + + + 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. If + BINDING-NAME is provided the cast pointer will be bound to this + name during the execution of BODY. If BINDING-NAME is not provided + POINTER must be a name bound to the pointer which should be + cast. This name will be bound to the cast pointer 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. + + + + diff --git a/doc/ref_primitive.xml b/doc/ref_primitive.xml new file mode 100644 index 0000000..106c018 --- /dev/null +++ b/doc/ref_primitive.xml @@ -0,0 +1,272 @@ + + +%myents; +]> + + + Primitive Types + + Overview + + Primitive types have a single value, these include + characters, numbers, and pointers. They are all symbols in + the keyword package. + + + + :char - Signed 8-bits. A +dereferenced :char pointer returns an character. + + + :unsigned-char - Unsigned 8-bits. A dereferenced :unsigned-char +pointer returns an character. + + + :byte - Signed 8-bits. A +dereferenced :byte pointer returns an integer. + + + :unsigned-byte - Unsigned 8-bits. A +dereferenced :unsigned-byte pointer returns an integer. + + + :short - Signed 16-bits. + + + :unsigned-short - Unsigned 16-bits. + + + :int - Signed 32-bits. + + + :unsigned-int - Unsigned 32-bits. + + + :long - Signed 32 or 64 bits, depending upon the platform. + + + :unsigned-long - Unsigned 32 or 64 bits, depending upon the platform. + + + :float - 32-bit floating point. + + + :double - 64-bit floating point. + + + :cstring - +A &null; terminated string used for passing and returning characters strings with a &c; function. + + + + :void - +The absence of a value. Used to indicate that a function does not return a value. + + + :pointer-void - +Points to a generic object. + + + * - Used to declare a pointer to an object + + + + + + + def-constant + Binds a symbol to a constant. + + Macro + + + Syntax + + def-constant name value &key export + + + + Arguments and Values + + + name + + A symbol that will be bound to the value. + + + + + value + + An evaluated form that is bound the the name. + + + + + export + + When &t;, the name is exported from the current package. The default is &nil; + + + + + + Description + + This is a thin wrapper around + defconstant. It evaluates at + compile-time and optionally exports the symbol from the package. + + + + Examples + +(def-constant pi2 (* 2 pi)) +(def-constant exported-pi2 (* 2 pi) :export t) + + + + Side Effects + Creates a new special variable.. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + def-foreign-type + Defines a new foreign type. + + Macro + + + Syntax + + def-foreign-type name type + + + + Arguments and Values + + + name + + A symbol naming the new foreign type. + + + + + value + + A form that is not evaluated that defines the new +foreign type. + + + + + + + Description + Defines a new foreign type. + + + + Examples + +(def-foreign-type my-generic-pointer :pointer-void) +(def-foreign-type a-double-float :double-float) +(def-foreign-type char-ptr (* :char)) + + + + Side Effects + Defines a new foreign type. + + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + null-char-p + Tests a character for &null; value. + + Macro + + + Syntax + + null-char-p char => is-null + + + + Arguments and Values + + + char + + A character or integer. + + + + + is-null + + A boolean flag indicating if char is a &null; value. + + + + + + + Description + + A predicate testing if a character or integer is &null;. This +abstracts the difference in implementations where some return a +character and some return a +integer whence dereferencing a +C character pointer. + + + + Examples + +(def-array-pointer ca :unsigned-char) +(let ((fs (convert-to-foreign-string "ab"))) + (values (null-char-p (deref-array fs 'ca 0)) + (null-char-p (deref-array fs 'ca 2)))) +=> &nil; + &t; + + + + Side Effects + None. + + + + Affected by + None. + + + Exceptional Situations + None. + + + diff --git a/doc/ref_string.xml b/doc/ref_string.xml new file mode 100644 index 0000000..cad60e2 --- /dev/null +++ b/doc/ref_string.xml @@ -0,0 +1,503 @@ + + +%myents; +]> + + + Strings + +Overview + + + &uffi; has functions to two types of +C-compatible + strings: cstring and +foreign strings. + +cstrings are used only as parameters to and from +functions. In some implementations a cstring is not a foreign type but +rather the Lisp string itself. On other platforms a cstring is a newly +allocated foreign vector for storing characters. The following is an +example of using cstrings to both send and return a value. + + + +(uffi:def-function ("getenv" c-getenv) + ((name :cstring)) + :returning :cstring) + +(defun my-getenv (key) + "Returns an environment variable, or NIL if it does not exist" + (check-type key string) + (uffi:with-cstring (key-native key) + (uffi:convert-from-cstring (c-getenv key-native)))) + + + In contrast, foreign strings are always a foreign vector of +characters which have memory allocated. Thus, if you need to allocate +memory to hold the return value of a string, you must use a foreign +string and not a cstring. The following is an example of using a foreign +string for a return value. + + +(uffi:def-function ("gethostname" c-gethostname) + ((name (* :unsigned-char)) + (len :int)) + :returning :int) + +(defun gethostname () + "Returns the hostname" + (let* ((name (uffi:allocate-foreign-string 256)) + (result-code (c-gethostname name 256)) + (hostname (when (zerop result-code) + (uffi:convert-from-foreign-string name)))) + (uffi:free-foreign-object name) + (unless (zerop result-code) + (error "gethostname() failed.")))) + + + Foreign functions that return pointers to freshly allocated +strings should in general not return cstrings, but foreign strings. +(There is no portable way to release such cstrings from Lisp.) The +following is an example of handling such a function. + + +(uffi:def-function ("readline" c-readline) + ((prompt :cstring)) + :returning (* :char)) + +(defun readline (prompt) + "Reads a string from console with line-editing." + (with-cstring (c-prompt prompt) + (let* ((c-str (c-readline c-prompt)) + (str (convert-from-foreign-string c-str))) + (uffi:free-foreign-object c-str) + str))) + + + + + + + convert-from-cstring + Converts a cstring to a Lisp string. + + Macro + + + Syntax + + convert-from-cstring cstring => string + + + + Arguments and Values + + + cstring + + A cstring. + + + + + string + + A Lisp string. + + + + + + + Description + + Converts a Lisp string to a cstring. This is +most often used when processing the results of a foreign function +that returns a cstring. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-to-cstring + Converts a Lisp string to a cstring. + + Macro + + + Syntax + + convert-to-cstring string => cstring + + + + Arguments and Values + + + string + + A Lisp string. + + + + + cstring + + A cstring. + + + + + + + Description + + Converts a Lisp string to a + cstring. The + cstring should be freed with + free-cstring. + + + + Side Effects + On some implementations, this function allocates memory. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + free-cstring + Free memory used by cstring. + + Macro + + + Syntax + + free-cstring cstring + + + + Arguments and Values + + + cstring + + A cstring. + + + + + + + Description + + Frees any memory possibly allocated by + convert-to-cstring. On some implementions, a cstring is just the Lisp string itself. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + with-cstring + Binds a newly created cstring. + + Macro + + + Syntax + + with-cstring (cstring string) {body} + + + + Arguments and Values + + + cstring + + A symbol naming the cstring to be created. + + + + + string + + A Lisp string that will be translated to a cstring. + + + + + body + + The body of where the cstring will be bound. + + + + + + + Description + + Binds a symbol to a cstring created from conversion of a string. Automatically frees the cstring. + + + + Examples + + +(def-function ("getenv" c-getenv) + ((name :cstring)) + :returning :cstring) + +(defun getenv (key) + "Returns an environment variable, or NIL if it does not exist" + (check-type key string) + (with-cstring (key-cstring key) + (convert-from-cstring (c-getenv key-cstring)))) + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-from-foreign-string + Converts a foreign string into a Lisp string. + + Macro + + + Syntax + + convert-from-foreign-string foreign-string &key length null-terminated-p => string + + + + Arguments and Values + + + foreign-string + + A foreign string. + + + + + length + + The length of the foreign string to +convert. The default is the length of the string until a &null; +character is reached. + + + + + null-terminated-p + + A boolean flag with a default value of &t; When true, +the string is converted until the first &null; character is reached. + + + + + string + + A Lisp string. + + + + + + + Description + + Returns a Lisp string from a foreign string. +Can translated ASCII and binary strings. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-to-foreign-string + Converts a Lisp string to a foreign string. + + Macro + + + Syntax + + convert-to-foreign-string string => foreign-string + + + + Arguments and Values + + + string + + A Lisp string. + + + + + foreign-string + + A foreign string. + + + + + + + Description + + Converts a Lisp string to a foreign string. Memory should be + freed with free-foreign-object. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + + allocate-foreign-string + Allocates space for a foreign string. + + Macro + + + Syntax + + allocate-foreign-string size &key unsigned => foreign-string + + + + Arguments and Values + + + size + + The size of the space to be allocated in bytes. + + + + + unsigned + + A boolean flag with a default value of &t;. When true, +marks the pointer as an :unsigned-char. + + + + + foreign-string + + A foreign string which has undefined contents. + + + + + + + Description + + Allocates space for a foreign string. Memory should + be freed with free-foreign-object. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + diff --git a/doc/uffi.xml b/doc/uffi.xml index be358db..0ab0a91 100644 --- a/doc/uffi.xml +++ b/doc/uffi.xml @@ -1,38 +1,22 @@ UFFI"> -FFI"> -CMUCL"> -SCL"> -Lispworks"> -SBCL"> -OpenMCL"> -MCL"> -AllegroCL"> -ANSI Common Lisp"> -T"> -NIL"> -NULL"> -C"> -defsystem"> -ASDF"> - - - - - - - + +%myents; ]> - - &bookinfo; - &preface; - &intro; - ¬es; - &ref; - &appendix; - &glossary; + + + + + + + + + + + + + -- 2.34.1