+* Types
+
+Some functions accept objects such as filenames or file
+descriptors. In the C binding to POSIX these are represented as
+strings and small integers respectively. For the Lisp programmer's
+convenience we introduce designators such that CL pathnames or open
+streams can be passed to these functions.
+
+** file-descriptor
+
+A file-descriptor is a non-negative small integer.
+
+A file-stream is a designator for a file-descriptor: the streams file
+descriptor is extracted. Note that mixing io operations on a stream
+with operations directly on its descriptor may produce unexpected
+results if the stream is buffered.
+
+** filename
+
+A filename is a string.
+
+A pathname is a designator for a filename: the filename is computed
+using the same mechanism as the implementation would use to map
+pathnames to OS filenames internally.
+
+In an implementation that supports pathnames to files on other hosts,
+using mechanisms not available to the underlying OS (for example,
+using an FTP or HTTP client in the Lisp implementation), the effect
+of supplying this interface with a pathname to such a file is undefined.
+
+
+** buffer
+
+A buffer is an opaque object which represents an area of memory that
+system calls may access. It has accessors BUFFER-START and
+BUFFER-LENGTH, and can be created using ALLOCATE-BUFFER or GET-BUFFER.
+
+[ TODO: GET-BUFFER is a silly name. Come up with a better one ]
+
+The object NIL is a designator for a buffer, meaning a NULL pointer.
+
+A vector of (UNSIGNED-BYTE 8) is a designator for a buffer: it is
+converted to a buffer of appropriate start and length using an
+identity mapping. This may or may not involve creating a copy of the
+data.
+
+A vector of CHARACTER is a designator for a buffer: it is converted to
+a buffer of appropriate start and length using an implementation-
+defined transformation that obviously depends on the implementation's
+representation of characters. This may or may not involve creating a
+copy of the data.
+
+Implementations may optionally extend these designators to include
+other types - for example, types that already exist in the
+implementation's FFI.
+
+** Structures, unions
+
+C structures and unions are opaque to Lisp and may be implemented
+using any appropriate method. Structure names are chosen according to
+the general rules for symbols.
+
+Accessors must be provided for each documented field in the
+structure. These are named structure-name-field-name where the two
+components are chosen according to the general rules, with the
+exception that in cases where all fields in a given structure have a
+common prefix, that prefix is omitted. For example, stat.st_dev in C
+becomes STAT-DEV in Lisp.
+
+For any structure that the user may need to allocate himself, there
+must also be a MAKE-structure-name function. This takes keyword
+arguments with names deriving from each documented field name
+according to the general rules for symbols.
+
+[ TDB: GC issues for buffers/structures/unions: probably a
+WITHOUT-MOVING macro or similar that will stop them from being moved
+or collected during its extent ]
+
+
+** Type conversion functions
+
+For each of these types there is a function of the same name that
+converts any valid designator for the type into an object of said type.
+
+This example is merely an example: actual output will vary between
+systems, implementations and environments
+
+(with-open-file (o "/tmp/foo" :direction :output)
+ (sb-posix:file-descriptor o))
+=> 4
+
+[ TBD: some memorable and nicely uniform protocol for transforming
+objects of these new types into instances of the Lisp-friendly types
+that may designate them: e.g how to get a stream from a fd ]
+
+
+* Function parameters
projects / sbcl.git / blobdiff