From 29637137d96e1eb6f952c8cf679402736aec3d66 Mon Sep 17 00:00:00 2001 From: ram <ram> Date: Wed, 4 Mar 1992 18:52:26 +0000 Subject: [PATCH] Added NULL-ALIEN and many doc-strings. --- code/alieneval.lisp | 62 ++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 59 insertions(+), 3 deletions(-) diff --git a/code/alieneval.lisp b/code/alieneval.lisp index e613d6edc..128290ae2 100644 --- a/code/alieneval.lisp +++ b/code/alieneval.lisp @@ -7,7 +7,7 @@ ;;; Scott Fahlman or slisp-group@cs.cmu.edu. ;;; (ext:file-comment - "$Header: /Volumes/share2/src/cmucl/cvs2git/cvsroot/src/code/alieneval.lisp,v 1.21 1992/03/04 17:50:58 ram Exp $") + "$Header: /Volumes/share2/src/cmucl/cvs2git/cvsroot/src/code/alieneval.lisp,v 1.22 1992/03/04 18:52:26 ram Exp $") ;;; ;;; ********************************************************************** ;;; @@ -22,7 +22,8 @@ boolean values single-float double-float system-area-pointer def-alien-type def-alien-variable sap-alien extern-alien with-alien slot deref addr cast alien-sap alien-size - alien-funcall def-alien-routine make-alien free-alien)) + alien-funcall def-alien-routine make-alien free-alien + null-alien)) (in-package "ALIEN-INTERNALS") (in-package "ALIEN") @@ -363,7 +364,9 @@ (defmacro def-alien-type (name type) - "Define the alien type NAME to be equivalent to TYPE." + "Define the alien type NAME to be equivalent to TYPE. Name may be NIL for + STRUCT and UNION types, in which case the name is taken from the type + specifier." (with-auxiliary-alien-types (let ((alien-type (parse-alien-type type))) `(eval-when (compile load eval) @@ -1327,7 +1330,15 @@ (sap-int (alien-value-sap value))))) +(declaim (inline null-alien)) +(defun null-alien (x) + "Return true if X (which must be an Alien pointer) is null, false otherwise." + (zerop (sap-int (alien-sap x)))) + + (defmacro sap-alien (sap type) + "Convert the System-Area-Pointer SAP to an Alien of the specified Type (not + evaluated.) Type must be pointer-like." (let ((alien-type (parse-alien-type type))) (if (eq (compute-alien-rep-type alien-type) 'system-area-pointer) `(%sap-alien ,sap ',alien-type) @@ -1339,6 +1350,7 @@ (make-alien-value :sap sap :type type)) (defun alien-sap (alien) + "Return a System-Area-Pointer pointing to Alien's data." (declare (type alien-value alien)) (alien-value-sap alien)) @@ -1425,6 +1437,7 @@ ;;; alien is actually a pointer, then deref it first. ;;; (defun slot (alien slot) + "Extract SLOT from the Alien STRUCT or UNION ALIEN. May be set with SETF." (declare (type alien-value alien) (type symbol slot) (optimize (inhibit-warnings 3))) @@ -1530,6 +1543,9 @@ ;;; Dereference the alien and return the results. ;;; (defun deref (alien &rest indices) + "De-reference an Alien pointer or array. If an array, the indices are used + as the indices of the array element to access. If a pointer, one index can + optionally be specified, giving the equivalent of C pointer arithmetic." (declare (type alien-value alien) (type list indices) (optimize (inhibit-warnings 3))) @@ -1653,6 +1669,8 @@ ;;;; The ADDR macro. (defmacro addr (expr &environment env) + "Return an Alien pointer to the data addressed by Expr, which must be a call + to SLOT or DEREF, or a reference to an Alien variable." (let ((form (macroexpand expr env))) (or (typecase form (cons @@ -1684,6 +1702,8 @@ ;;;; The CAST macro. (defmacro cast (alien type) + "Convert ALIEN to an Alien of the specified TYPE (not evaluated.) Both types + must be Alien array, pointer or function types." `(%cast ,alien ',(parse-alien-type type))) (defun %cast (alien target-type) @@ -1753,6 +1773,8 @@ ;;;; alien-funcall, def-alien-function (defun alien-funcall (alien &rest args) + "Call the foreign function ALIEN with the specified arguments. ALIEN's + type specifies the argument and result types." (declare (type alien-value alien)) (let ((type (alien-value-type alien))) (typecase type @@ -1780,6 +1802,40 @@ (error "~S is not an alien function." alien))))) (defmacro def-alien-routine (name result-type &rest args) + "Def-C-Routine Name Result-Type + {(Arg-Name Arg-Type [Style])}* + + Define a foreign interface function for the routine with the specified Name, + which may be either a string, symbol or list of the form (symbol string). + Return-Type is the Alien fypte for the function return value. VOID may be + used to specify a function with no result. + + The remaining forms specifiy individual arguments that are passed to the + routine. Arg-Name is a symbol that names the argument, primarily for + documentation. Arg-Type is the C-Type of the argument. Style specifies the + say that the argument is passed. + + :IN + An :In argument is simply passed by value. The value to be passed is + obtained from argument(s) to the interface function. No values are + returned for :In arguments. This is the default mode. + + :OUT + The specified argument type must be a pointer to a fixed sized object. + A pointer to a preallocated object is passed to the routine, and the + the object is accessed on return, with the value being returned from + the interface function. :OUT and :IN-OUT cannot be used with pointers + to arrays, records or functions. + + :COPY + Similar to :IN, except that the argument values are stored in on + the stack, and a pointer to the object is passed instead of + the values themselves. + + :IN-OUT + A combination of :OUT and :COPY. A pointer to the argument is passed, + with the object being initialized from the supplied argument and + the return value being determined by accessing the object on return." (multiple-value-bind (lisp-name alien-name) (pick-lisp-and-alien-names name) -- GitLab