http://csserver.evansville.edu/~sc87/cffi/cffi-sys-spec.texinfo.1s11.patch is
the patch, also attached.
http://csserver.evansville.edu/~sc87/cffi/ChangeLog.cffi-sys-spec.texinfo.1s11
is a changelog, formatted as ChangeLog-luis is in the tarballs directory. Its
contents also follow.
Please let me know if there is a better/preferred way to do this,
particularly as I am unfamiliar with darcs.
Mon Dec 19 13:34:00 CST 2005 Stephen Compall <[EMAIL PROTECTED]>
* CFFI-SYS-SPEC manual updates & Texinfo idioms
- Use @var for arguments, rather than @code.
- Use @deftpx for a chain of type defns, rather than repeated @deftp
blocks.
- Use @result{} instead of explicit =>.
- Use @r with appropriate formatting for comments in
@examples/@lisps.
- Introduction: Convert naming convention to a list of general
conventions, and define "foreign type".
- Rename the pointer functions.
- Document new functions.
- Use new @impnote macro to add notes, so they can be conditionally
removed from the manual.
--
Stephen Compall
http://scompall.nocandysw.com/blog
--- cffi-sys-spec.texinfo~ 2005-11-09 09:23:07.000000000 -0600
+++ cffi-sys-spec.texinfo 2005-12-19 12:55:21.000000000 -0600
@@ -2,7 +2,6 @@
@c %**start of header£
@setfilename cffi-sys.info
@settitle CFFI-SYS Interface Specification
[EMAIL PROTECTED] %**end of header
@c Show types in the same index as the functions.
@synindex tp fn
@@ -22,17 +21,22 @@
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-DEALINGS IN THE SOFTWARE.
[EMAIL PROTECTED] software is provided ``as is'', without warranty of any kind,
+express or implied, including but not limited to the warranties of
+merchantability, fitness for a particular purpose and
+noninfringement. In no event shall the authors or copyright
+holders be liable for any claim, damages or other liability,
+whether in an action of contract, tort or otherwise, arising from,
+out of or in connection with the software or the use or other
+dealings in the software.}
@end quotation
@end copying
[EMAIL PROTECTED] impnote {text}
[EMAIL PROTECTED]'s note: \text\}
[EMAIL PROTECTED] macro
[EMAIL PROTECTED] %**end of header
+
@titlepage
@title CFFI-SYS Interface Specification
@c @subtitle Version X.X
@@ -60,17 +64,18 @@
* Memory Access::
* Foreign Function Calling::
* Loading Foreign Libraries::
+* Foreign Globals::
* Symbol Index::
@end menu
@node Introduction
@chapter Introduction
-CFFI, the Common Foreign Function Interface, purports to be a portable
-foreign function interface for Common Lisp.
[EMAIL PROTECTED], the Common Foreign Function Interface, purports to be
+a portable foreign function interface for Common Lisp.
-This specification defines a set of low-level primitives that
-must be defined for each Lisp implementation supported by CFFI.
+This specification defines a set of low-level primitives that must be
+defined for each Lisp implementation supported by @acronym{CFFI}.
These operators are defined in the @code{CFFI-SYS} package.
The @code{CFFI} package uses the @code{CFFI-SYS} interface
@@ -79,76 +84,67 @@
defining foreign function calls, and automatic conversion of
foreign function arguments to/from Lisp types.
[EMAIL PROTECTED] Naming Convention
+Please note the following conventions that apply to everything in
[EMAIL PROTECTED]:
+
[EMAIL PROTECTED] @bullet
[EMAIL PROTECTED]
+Functions in @code{CFFI-SYS} that are low-level versions of functions
+exported from the @code{CFFI} package begin with a leading
+percent-sign (eg. @code{%mem-ref}).
+
[EMAIL PROTECTED]
+Where ``foreign type'' is mentioned as the kind of an argument, the
+meaning is restricted to that subset of all foreign types defined in
[EMAIL PROTECTED] Foreign Types}. Support for higher-level types is
+always defined in terms of those lower-level types in @code{CFFI}
+proper.
[EMAIL PROTECTED] itemize
[EMAIL PROTECTED]
-Functions in @code{CFFI-SYS} that are low-level versions of
-functions exported from the @code{CFFI} package begin with a
-leading percent-sign (eg. @code{%mem-ref}).
@node Built-In Foreign Types
@chapter Built-In Foreign Types
@deftp {Foreign Type} :char
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :unsigned-char
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :short
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :unsigned-short
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :int
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :unsigned-int
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :long
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :unsigned-long
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :long-long
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :unsigned-long-long
[EMAIL PROTECTED] {Foreign Type} :unsigned-char
[EMAIL PROTECTED] {Foreign Type} :short
[EMAIL PROTECTED] {Foreign Type} :unsigned-short
[EMAIL PROTECTED] {Foreign Type} :int
[EMAIL PROTECTED] {Foreign Type} :unsigned-int
[EMAIL PROTECTED] {Foreign Type} :long
[EMAIL PROTECTED] {Foreign Type} :unsigned-long
[EMAIL PROTECTED] {Foreign Type} :long-long
[EMAIL PROTECTED] {Foreign Type} :unsigned-long-long
These types correspond to the native C integer types according to the
ABI of the system the Lisp implementation is compiled against.
@end deftp
@deftp {Foreign Type} :int8
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :uint8
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :int16
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :uint16
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :int32
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :uint32
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :int64
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :uint64
[EMAIL PROTECTED] {Foreign Type} :uint8
[EMAIL PROTECTED] {Foreign Type} :int16
[EMAIL PROTECTED] {Foreign Type} :uint16
[EMAIL PROTECTED] {Foreign Type} :int32
[EMAIL PROTECTED] {Foreign Type} :uint32
[EMAIL PROTECTED] {Foreign Type} :int64
[EMAIL PROTECTED] {Foreign Type} :uint64
Foreign integer types of specific sizes, corresponding to the C types
defined in @code{stdint.h}.
@end deftp
@deftp {Foreign Type} :size
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :ssize
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :ptrdiff
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :time
[EMAIL PROTECTED] {Foreign Type} :ssize
[EMAIL PROTECTED] {Foreign Type} :ptrdiff
[EMAIL PROTECTED] {Foreign Type} :time
Foreign integer types corresponding to the standard C types (without
the @code{_t} suffix).
@end deftp
[EMAIL PROTECTED]'m sure there are more of these that could be useful, let's
[EMAIL PROTECTED]'m sure there are more of these that could be useful, let's
add any types that can't be defined portably to this list as
necessary.}
@deftp {Foreign Type} :float
[EMAIL PROTECTED] deftp
[EMAIL PROTECTED] {Foreign Type} :double
[EMAIL PROTECTED] {Foreign Type} :double
The @code{:float} type represents a C @code{float} and a Lisp
@code{single-float}. @code{:double} represents a C @code{double} and a
Lisp @code{double-float}.
@@ -167,18 +163,18 @@
@node Operations on Foreign Types
@chapter Operations on Built-in Foreign Types
[EMAIL PROTECTED] %foreign-type-size type => size
-Return the @code{size}, in bytes, of objects having foreign type
[EMAIL PROTECTED] An error is signalled if @code{type} is not a known
[EMAIL PROTECTED] %foreign-type-size type @result{} size
+Return the @var{size}, in bytes, of objects having foreign type
[EMAIL PROTECTED] An error is signalled if @var{type} is not a known
built-in foreign type.
@end defun
[EMAIL PROTECTED] %foreign-type-alignment type => alignment
[EMAIL PROTECTED] %foreign-type-alignment type @result{} alignment
Return the default alignment in bytes for structure members of foreign
-type @code{type}. An error is signalled if @code{type} is not a known
+type @var{type}. An error is signalled if @var{type} is not a known
built-in foreign type.
[EMAIL PROTECTED] this should take an optional keyword argument specifying an
[EMAIL PROTECTED] this should take an optional keyword argument specifying an
alternate alignment system, eg. :mac68k for 68000-compatible alignment
on Darwin.}
@end defun
@@ -187,39 +183,47 @@
@node Basic Pointer Operations
@chapter Basic Pointer Operations
[EMAIL PROTECTED] pointerp ptr => boolean
-Return true if @code{ptr} is a foreign pointer.
[EMAIL PROTECTED] pointerp ptr @result{} boolean
+Return true if @var{ptr} is a foreign pointer.
@end defun
[EMAIL PROTECTED] null-ptr => pointer
[EMAIL PROTECTED] null-pointer @result{} pointer
Return a null foreign pointer.
@end defun
[EMAIL PROTECTED] null-ptr-p ptr => boolean
-Return true if @code{ptr} is a null foreign pointer.
[EMAIL PROTECTED] null-pointer-p ptr @result{} boolean
+Return true if @var{ptr} is a null foreign pointer.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] make-pointer address @result{} pointer
+Return a pointer corresponding to the numeric integer @var{address}.
[EMAIL PROTECTED] defun
+
[EMAIL PROTECTED] inc-pointer ptr offset @result{} pointer
+Return the result of numerically incrementing @var{ptr} by @var{offset}.
@end defun
@node Foreign Memory Allocation
@chapter Foreign Memory Allocation
[EMAIL PROTECTED] foreign-alloc size => pointer
-Allocate @code{size} bytes of foreign-addressable memory and return
-a @code{pointer} to the allocated block. An implementation-specific
[EMAIL PROTECTED] foreign-alloc size @result{} pointer
+Allocate @var{size} bytes of foreign-addressable memory and return
+a @var{pointer} to the allocated block. An implementation-specific
error is signalled if the memory cannot be allocated.
@end defun
[EMAIL PROTECTED] foreign-free ptr => unspecified
-Free a pointer @code{ptr} allocated by @code{foreign-alloc}. The
-results are undefined if @code{ptr} is used after being freed.
[EMAIL PROTECTED] foreign-free ptr @result{} unspecified
+Free a pointer @var{ptr} allocated by @code{foreign-alloc}. The
+results are undefined if @var{ptr} is used after being freed.
@end defun
[EMAIL PROTECTED] with-foreign-ptr (var size &optional size-var) &body body
-Bind @code{var} to a pointer to @code{size} bytes of
-foreign-accessible memory during @code{body}. Both @code{ptr} and the
[EMAIL PROTECTED] with-foreign-pointer (var size &optional size-var) &body body
+Bind @var{var} to a pointer to @var{size} bytes of
+foreign-accessible memory during @var{body}. Both @var{ptr} and the
memory block it points to have dynamic extent and may be stack
-allocated if supported by the implementation. If @code{size-var} is
-supplied, it will be bound to @code{size} during @code{body}.
+allocated if supported by the implementation. If @var{size-var} is
+supplied, it will be bound to @var{size} during @var{body}.
@end defmac
@@ -227,17 +231,17 @@
@chapter Memory Access
@deffn {Accessor} %mem-ref ptr type &optional offset
-Dereference a pointer @code{offset} bytes from @code{ptr} to an object
+Dereference a pointer @var{offset} bytes from @var{ptr} to an object
for reading (or writing when used with @code{setf}) of built-in type
[EMAIL PROTECTED]
[EMAIL PROTECTED]
@end deffn
[EMAIL PROTECTED] Example:
[EMAIL PROTECTED] Example
@lisp
-;; An impratical example, since 'time' returns the time as well,
-;; but it demonstrates %MEM-REF. Better (simple) examples wanted!
-(with-foreign-ptr (p (foreign-type-size :time))
+;; @r{An impractical example, since @code{time} returns the time as well,}
+;; @r{but it demonstrates @code{%mem-ref}. Better (simple) examples wanted!}
+(with-foreign-pointer (p (foreign-type-size :time))
(foreign-funcall "time" :pointer p :time)
(%mem-ref p :time))
@end lisp
@@ -246,31 +250,34 @@
@node Foreign Function Calling
@chapter Foreign Function Calling
[EMAIL PROTECTED] %foreign-funcall name @{arg-type [EMAIL PROTECTED] &optional result-type => object
-Invoke a foreign function called @code{name}, which may be mangled
-depending on the ABI of the system (eg. adding leading underscore for
-Darwin).
-
-The remaining arguments are pairs of foreign types and their values,
-followed by the return type of the function, assumed to be
[EMAIL PROTECTED]:void} if not supplied.
-
[EMAIL PROTECTED] wording is pretty awkward, rewrite this description.}
[EMAIL PROTECTED] %foreign-funcall name @{arg-type [EMAIL PROTECTED] &optional result-type @result{} object
[EMAIL PROTECTED] %foreign-funcall-pointer ptr @{arg-type [EMAIL PROTECTED] &optional result-type @result{} object
+Invoke a foreign function called @var{name} in the foreign source code.
+
+Each @var{arg-type} is a foreign type specifier, followed by
[EMAIL PROTECTED], Lisp data to be converted to foreign data of type
[EMAIL PROTECTED] @var{result-type} is the foreign type of the
+function's return value, and is assumed to be @code{:void} if not
+supplied.
+
[EMAIL PROTECTED] takes a pointer @var{ptr} to the
+function, as returned by @code{foreign-symbol-pointer}, rather than a
+string @var{name}.
@end defmac
[EMAIL PROTECTED] Examples:
[EMAIL PROTECTED] Examples
@lisp
-;; Calling a standard C library function:
-(%foreign-funcall "sqrtf" :float 16.0 :float) => 4.0
+;; @r{Calling a standard C library function:}
+(%foreign-funcall "sqrtf" :float 16.0 :float) @result{} 4.0
@end lisp
@lisp
-;; Dynamic allocation of a buffer and passing to a function:
+;; @r{Dynamic allocation of a buffer and passing to a function:}
(with-foreign-ptr (buf 255 buf-size)
(%foreign-funcall "gethostname" :pointer buf :size buf-size :int)
- ;; Convert BUF to a Lisp string using MAKE-STRING and %MEM-REF or
- ;; a portable CFFI function such as CFFI:LISP-STRING-FROM-FOREIGN.
+ ;; @r{Convert @var{buf} to a Lisp string using @code{make-string} and @code{%mem-ref} or}
+ ;; @r{a portable CFFI function such as @code{cffi:lisp-string-from-foreign}.}
)
@end lisp
@@ -278,15 +285,25 @@
@node Loading Foreign Libraries
@chapter Loading Foreign Libraries
[EMAIL PROTECTED] %load-foreign-library name => unspecified
-Loads the foreign shared library @code{name}.
[EMAIL PROTECTED] %load-foreign-library name @result{} unspecified
+Load the foreign shared library @var{name}.
[EMAIL PROTECTED] is a lot of behavior to decide here. Currently I lean
[EMAIL PROTECTED] is a lot of behavior to decide here. Currently I lean
toward not requiring NAME to be a full path to the library so
we can search the system library directories (maybe even get
LD_LIBRARY_PATH from the environment) as necessary.}
@end defun
+
[EMAIL PROTECTED] Foreign Globals
[EMAIL PROTECTED] Foreign Globals
+
[EMAIL PROTECTED] foreign-symbol-pointer name kind @result{} pointer
+Return a pointer to a foreign symbol @var{name}. @var{kind} is one of
[EMAIL PROTECTED]:code} or @code{:data}, and is ignored on some platforms.
[EMAIL PROTECTED] defun
+
+
@node Symbol Index
@unnumbered Symbol Index
@printindex fn
_______________________________________________
cffi-devel mailing list
cffi-devel@common-lisp.net
http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
