From: Kevin M. Rosenberg Date: Sun, 16 Nov 2003 02:57:06 +0000 (+0000) Subject: r8215: fix documentation X-Git-Tag: debian-2.11.0-2~34 X-Git-Url: http://git.kpe.io/?p=hyperobject.git;a=commitdiff_plain;h=a804e41a05a34dd7b6435757d825d52487665f13 r8215: fix documentation --- diff --git a/doc/Makefile b/doc/Makefile index b496472..b7200ea 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,33 +1,43 @@ +############################################################################## # FILE IDENTIFICATION # # Name: Makefile -# Purpose: Makefile for the hyperobject hyperobject documentation +# Purpose: Makefile for the hyperobject documentation # Programer: Kevin M. Rosenberg # Date Started: Mar 2002 # # CVS Id: $Id$ # -# This file, part of Hyperobject, is Copyright (c) 2002 by Kevin M. Rosenberg +# This file, part of HYPEROBJECT, is Copyright (c) 2002-2003 by Kevin M. Rosenberg # -# System variable to select catalog file -SYSTEM=fink -#SYSTEM=debian -# SYSTEM=redhat +# HYPEROBJECT 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. +############################################################################## -# Nothing to configure beyond this point +DOCFILE_BASE_DEFAULT:=hyperobject +DOCFILE_EXT_DEFAULT:=xml -CATALOG=catalog.$(SYSTEM) -# Custom DSSSL's -DSSSL_HTML=../dsssl/html/docbook.dsl -DSSSL_PRINT=dsssl/print/docbook.dsl - -DOCFILE_BASE_DEFAULT=hyperobject -DOCFILE_EXT_DEFAULT=sgml +# Standard docfile processing -JADE=openjade +DEBIAN=$(shell expr "`cat /etc/issue`" : '.*Debian.*') +SUSE=$(shell expr "`cat /etc/issue`" : '.*SuSE.*') +REDHAT=$(shell expr "`cat /etc/issue`" : '.*RedHat.*') + + +ifneq (${DEBIAN},0) +OS:=debian +else + ifneq (${SUSE},0) + OS=suse + else + ifneq (${REDHAT},0) + OS=redhat + endif + endif +endif -# Standard docfile processing ifndef DOCFILE_BASE DOCFILE_BASE=${DOCFILE_BASE_DEFAULT} @@ -37,13 +47,18 @@ 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) +DOCFILE:=${DOCFILE_BASE}.${DOCFILE_EXT} +FOFILE:=${DOCFILE_BASE}.fo +PDFFILE:=${DOCFILE_BASE}.pdf +PSFILE:=${DOCFILE_BASE}.ps +DVIFILE:=${DOCFILE_BASE}.dvi +TXTFILE:=${DOCFILE_BASE}.txt +HTMLFILE:=${DOCFILE_BASE}.html +TMPFILES:=${DOCFILE_BASE}.aux ${DOCFILE_BASE}.out ${DOCFILE_BASE}.log +DOCFILES:=$(shell echo *.xml *.xsl) + +CATALOG:=`pwd`/catalog-${OS}.xml +CHECK:=XML_CATALOG_FILES="$(CATALOG)" xmllint --noout --xinclude --postvalid $(DOCFILE) || exit 1 .PHONY: all all: html pdf @@ -54,57 +69,57 @@ dist: html pdf .PHONY: doc doc: html pdf -CHECK=onsgmls -s -C ${CATALOG} || exit 1 - .PHONY: check check: + @echo "Operating System Detected: ${OS}" @$(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) +html.tar.gz: $(DOCFILES) Makefile + @rm -rf html + @mkdir html + @XML_CATALOG_FILES="$(CATALOG)" xsltproc --xinclude --output html/ html_chunk.xsl $(DOCFILE) + @GZIP='-9' tar czf html.tar.gz html -.PHONY: tex -tex: ${TEXFILE} +.PHONY: fo +fo: ${FOFILE} -${TEXFILE}: ${DOCFILES} - @$(CHECK) - @$(JADE) -t tex -c ${CATALOG} -d ${DSSSL_PRINT} ${DOCFILE} > /dev/null +${FOFILE}: $(DOCFILES) Makefile + @XML_CATALOG_FILES="$(CATALOG)" xsltproc --xinclude --output $(FOFILE) fo.xsl $(DOCFILE) .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 +${PDFFILE}: ${DOCFILES} Makefile + @$(MAKE) fo + @fop $(FOFILE) -pdf $(PDFFILE) > /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 +${PSFILE}: ${DOCFILES} Makefile + @$(MAKE) fo + @fop $(FOFILE) -ps $(PSFILE) > /dev/null + + +.PHONY: txt +txt: ${TXTFILE} + +${TXTFILE}: ${FOFILE} + @XML_CATALOG_FILES="$(CATALOG)" xsltproc --xinclude --output ${HTMLFILE} html.xsl $(DOCFILE) + lynx -dump ${HTMLFILE} > ${TXTFILE} .PHONY: clean clean: @rm -f *~ *.bak *.orig \#*\# .\#* texput.log - @rm -rf html ${PSFILE} - @rm -f ${TMPFILES} - @rm -f ${DVIFILE} ${TEXFILE} + @rm -rf html ${PSFILE} ${HTMLFILE} + @rm -f ${TMPFILES} ${FOFILE} + @rm -f ${DVIFILE} ${TXTFILE} .PHONY: distclean distclean: clean diff --git a/doc/appendix.sgml b/doc/appendix.sgml deleted file mode 100644 index cf1b4cd..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/bookinfo.sgml b/doc/bookinfo.sgml deleted file mode 100644 index 587a888..0000000 --- a/doc/bookinfo.sgml +++ /dev/null @@ -1,71 +0,0 @@ - - - - - &hyperobject; Reference Guide - - Kevin - M. - Rosenberg - - Heart Hospital of New Mexico -
- kevin@rosenberg.net - 504 Elm Street N.E. - Albuquerque - New Mexico - 87102 -
- - - - - $Id: bookinfo.sgml,v 1.1 2002/12/09 09:31:27 kevin Exp $ - File $Date: 2002/12/09 09:31:27 $ - - - 2002 - Kevin M. Rosenberg - - - - - The &hyperobject; 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 new file mode 100644 index 0000000..624d59d --- /dev/null +++ b/doc/bookinfo.xml @@ -0,0 +1,75 @@ + + +%myents; +]> + + + &hyperobject; 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 &hyperobject; 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 &hyperobject; 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/catalog-debian.xml b/doc/catalog-debian.xml new file mode 100644 index 0000000..0188d9b --- /dev/null +++ b/doc/catalog-debian.xml @@ -0,0 +1,43 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/catalog-suse.xml b/doc/catalog-suse.xml new file mode 100644 index 0000000..6a03830 --- /dev/null +++ b/doc/catalog-suse.xml @@ -0,0 +1,43 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/catalog.debian b/doc/catalog.debian deleted file mode 100644 index e082e53..0000000 --- a/doc/catalog.debian +++ /dev/null @@ -1,3 +0,0 @@ -CATALOG /etc/sgml/docbook.cat -CATALOG /etc/sgml/docbook-dsssl.cat -DOCUMENT hyperobject.sgml diff --git a/doc/catalog.fink b/doc/catalog.fink deleted file mode 100644 index d791797..0000000 --- a/doc/catalog.fink +++ /dev/null @@ -1,2 +0,0 @@ -CATALOG /sw/share/sgml/catalog -DOCUMENT hyperobject.sgml diff --git a/doc/catalog.redhat b/doc/catalog.redhat deleted file mode 100644 index 1e8a521..0000000 --- a/doc/catalog.redhat +++ /dev/null @@ -1,2 +0,0 @@ -CATALOG /etc/sgml/sgml-docbook-4.1.cat -DOCUMENT hyperobject.sgml diff --git a/doc/design.sgml b/doc/design.sgml deleted file mode 100644 index f4c3dcd..0000000 --- a/doc/design.sgml +++ /dev/null @@ -1,9 +0,0 @@ - - - - Design - - Class Options - - - diff --git a/doc/entities.xml b/doc/entities.xml new file mode 100644 index 0000000..8a6b585 --- /dev/null +++ b/doc/entities.xml @@ -0,0 +1,20 @@ + + +Hyperobject"> +UFFI"> +FFI"> +CMUCL"> +SCL"> +Lispworks"> +SBCL"> +OpenMCL"> +MCL"> +AllegroCL"> +ANSI Common Lisp"> +T"> +NIL"> +NULL"> +C"> +ASDF"> +KMRCL"> +CLSQL"> diff --git a/doc/fo.xsl b/doc/fo.xsl new file mode 100644 index 0000000..50ed481 --- /dev/null +++ b/doc/fo.xsl @@ -0,0 +1,8 @@ + + + + + + + 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/html.xsl b/doc/html.xsl new file mode 100644 index 0000000..aada3f2 --- /dev/null +++ b/doc/html.xsl @@ -0,0 +1,9 @@ + + + + + + + + diff --git a/doc/html_chunk.xsl b/doc/html_chunk.xsl new file mode 100644 index 0000000..a2bb88f --- /dev/null +++ b/doc/html_chunk.xsl @@ -0,0 +1,9 @@ + + + + + + + + diff --git a/doc/hyperobject.sgml b/doc/hyperobject.sgml deleted file mode 100644 index af60c10..0000000 --- a/doc/hyperobject.sgml +++ /dev/null @@ -1,35 +0,0 @@ - - -Hyperobject"> -UFFI"> -CLSQL"> -KMRCL"> -CMUCL"> -SBCL"> -SCL"> -Lispworks"> -OpenMCL"> -MCL"> -AllegroCL"> -ANSI Common Lisp"> -T"> -NIL"> -NULL"> -C"> -defsystem"> -ASDF"> - - - - - -]> - - -&bookinfo; -&preface; -&intro; -&design; -&ref; - diff --git a/doc/hyperobject.xml b/doc/hyperobject.xml new file mode 100644 index 0000000..1c0cf26 --- /dev/null +++ b/doc/hyperobject.xml @@ -0,0 +1,12 @@ + + +%myents; +]> + + + + + + diff --git a/doc/intro.sgml b/doc/intro.sgml deleted file mode 100644 index 41642d3..0000000 --- a/doc/intro.sgml +++ /dev/null @@ -1,72 +0,0 @@ - - - - Introduction - - Purpose - This reference guide describes - &hyperobject;, which provides an object representation - library for Common Lisp programs. - - - - - Supported Implementations - The primary tested and supported platforms for &hyperobject; are: - - - &acl; v6.2 - &lw; v4.2 - &cmucl; 18d - &sbcl; 0.7.10 - &scl; 1.1.1 - - - - - Installation - - Download - -You need to download the &hyperobject; package from its web -home. -Other require packages are: - -&kmrcl; from it's home. -&uffi; from it's home. -&clsql; from it's home. -&asdf; from it's home CCLAN package. You can download -the file asdf.lisp from the CVS -tree. - - - - Loading - - After downloading and installing &asdf;, simply - push the - directories containing &hyperobject;, &kmrcl;, &uffi;, and &clsql; onto - asdf:*central-registry* variable. Whenever you -want to load the &hyperobject; package, use the function - (asdf:oos 'asdf:load-op :hyperobject). - - - - - - Design - - Overview - - &hyperobject; 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. - - - - - diff --git a/doc/intro.xml b/doc/intro.xml new file mode 100644 index 0000000..e4431f7 --- /dev/null +++ b/doc/intro.xml @@ -0,0 +1,80 @@ + + +%myents; +]> + + + Introduction + + Purpose + This reference guide describes + &hyperobject;, which provides an object representation + library for Common Lisp programs. + + + + + Supported Implementations + The primary tested and supported platforms for &hyperobject; are: + + + &acl; v6.2 + &lw; v4.3 + &cmucl; 18e + &sbcl; 0.8.5 + &scl; 1.1.1 + &openmcl; 0.14 + + + + + Installation + + Download + + You need to download the &hyperobject; package from its web + home. + Other required packages are: + + + + &kmrcl; + + + + + &uffi; + + + + + &clsql; + + + + + &asdf; from it's home CCLAN + package. You can download the file + asdf.lisp from the CVS tree. + + + + + + Loading + + After downloading and installing &asdf;, simply + push the + directories containing &hyperobject;, &kmrcl;, &uffi;, and &clsql; onto + asdf:*central-registry* variable. Whenever you + want to load the &hyperobject; package, use the function + (asdf:operate 'asdf:load-op :hyperobject). + + + + + diff --git a/doc/preface.sgml b/doc/preface.sgml deleted file mode 100644 index 16ed906..0000000 --- a/doc/preface.sgml +++ /dev/null @@ -1,8 +0,0 @@ - - - - Preface - This reference guide describes the usage and features - of &hyperobject;. - - diff --git a/doc/ref.sgml b/doc/ref.sgml deleted file mode 100644 index f299c19..0000000 --- a/doc/ref.sgml +++ /dev/null @@ -1,2218 +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-bits. - - - :unsigned-long - Unsigned 32-bits. - - - :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 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; - - - - 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 - - - - - 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 object obtained by dereferencing a -:char pointer is a 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;. - - - - - - - - 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.")))) - - - - - - - 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 => 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) - - - - - 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. - - - - 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. - - - - - -