X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=contrib%2Fsb-posix%2FREADME;h=832eea15d2af3740a3455cdd3eaa34f99285bb04;hb=b665ae77fc8e369b8713abf3ca9e3d8455e4c5a7;hp=075a5524067ca6fc97bdbcf78c7c5dc15c869ff2;hpb=84500b84beb8a03298beaf731d36faee5323b4d5;p=sbcl.git diff --git a/contrib/sb-posix/README b/contrib/sb-posix/README index 075a552..832eea1 100644 --- a/contrib/sb-posix/README +++ b/contrib/sb-posix/README @@ -6,7 +6,10 @@ The scope of this interface is "operating system calls on a typical Unixlike platform". This is section 2 of the Unix manual, plus section 3 calls that are (a) typically found in libc, but (b) not part of the C standard. For example, we intend to provide support for -opendir() and readdir() , but not for printf() +opendir() and readdir(), but not for printf(). Note that we do not +assert or imply any claim of conformance with the official standards +issued by POSIX groups or SVID or anyone else: we're simply using +"POSIX" in a generic sense to refer to Unix and Unix-like systems. Some facilities are omitted where they offer absolutely no additional use over some portable function, or would be actively dangerous to the @@ -21,13 +24,18 @@ disagreements about what it should look like, and the work of implementing it is easily parallelisable - and in fact, can be attempted on an as-needed basis by the various people who want it. -* Function names +* Symbol names -The package name for this interface is SB-POSIX. In this package -there is a Lisp function for each supported Unix function, and a +In SBCL this interface is in the SB-POSIX package. This package +contains a Lisp function for each supported Unix function, and a variable or constant for each supported unix constant. A symbol name is derived from the C binding's name, by (a) uppercasing, then (b) -replacing underscore (#\_) characters with the hyphen (#\-) +removing leading underscores (#\_) then replacing remaining underscore +characters with the hyphen (#\-). The requirement to uppercase is so +that in a standard upcasing reader the user may write posix:creat +instead of posix:|creat| as would otherise be required - some +extra-standard implementations may have alternative means to achieve +the same effect. No other changes to "Lispify" symbol names are made, so creat() becomes CREAT, not CREATE @@ -51,10 +59,106 @@ slightly tacky, when there's a package system available to do it more cleanly ] -* Parameters +* 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 The calling convention is modelled after that of CMUCL's UNIX package: -in particular, it's like the C interface except +in particular, it's like the C interface except that a) length arguments are omitted or optional where the sensible value is obvious. For example, @@ -62,21 +166,21 @@ is obvious. For example, (read fd buffer &optional (length (length buffer))) => bytes-read b) where C simulates "out" parameters using pointers (for instance, in -pipe() or socketpair()) we may use multiple return values instead. -This doesn't apply to data transfer functions that fill buffers. +pipe() or socketpair()) these may be optional or omitted in the Lisp +interface: if not provided, appropriate objects will be allocated and +returned (using multiple return values if necessary). c) some functions accept objects such as filenames or file -descriptors. In the C bindings these are strings and small integers -respectively. For the Lisp programmer's convenience we introduce -"filename designators" and "file descriptor designator" concepts such -that CL pathnames or open streams can be passed to these functions. +descriptors. Wherever these are specified as such in the C bindings, +the Lisp interface accepts designators for them as specified in the +'Types' section above [ Rationale: Keeping exact 1:1 correspondence with C conventions is less important here, as the function argument list can easily be accessed to find out exactly what the arguments are. Designators are primarily a convenience feature ] -* Return values +* Function return values The return value is usually the same as for the C binding, except in error cases: where the C function is defined as returning some @@ -88,7 +192,12 @@ of the error number] We do not automatically translate the returned value into "Lispy" objects - for example, SB-POSIX:OPEN returns a small integer, not a -stream. +stream. Exception: boolean-returning functions (or, more commonly, +macros) do not return a C integer, but instead a lisp boolean [ or +maybe "true"/"false" in CLtS parlance ]; the rationale behind this +exception is that there is nothing that can be meaningfully done with +the boolean except test for truth or falsity -- it cannot be passed +meaningfully to other POSIX functions. [ Rationale: This is an interface to POSIX, not a high-level interface that uses POSIX, and many people using it will actually want to mess @@ -116,3 +225,15 @@ See designator.lisp, add a define-designator form The use of DEFINE-CALL macro in interface.lisp should be obvious from the existing examples, if less so from the macroexpansion + + + + +GC issues + +buffers that refer to C stuff are probably not movable by GC anyway + +a buffer that refers to a Lisp object may have trouble if the Lisp +object is moved + +