The people on #lisp have been very helpful to me over the past couple of
weeks, helping me find my way through use of sb-bsd-sockets. I was
hoping to give something back by improving some of the documentation,
and as a first step was going to try to provide a more substantial
docstring for socket-make-stream. The current docstring says only:
Find or create a STREAM that can be used for IO on SOCKET (which must be
connected). ARGS are passed onto SB-SYS:MAKE-FD-STREAM.
I was going to provide more extensive documentation of make-fd-stream,
but RMK discouraged me from doing so, pointing out that make-fd-stream
is an SBCL internal and really should not be documented with a docstring
(there are extensive and helpful comments, though), since that might
tend to encourage people to call it.
Examining socket-make-stream, I see that its arguments are
(socket &rest args)
The use of &rest is convenient here, since the arguments are simply
delegated to make-fd-stream with apply. However, it makes the arglist
prompting from the environment much less useful, and it sends the
programmer back to make-fd-stream, which is an internal function.
Accordingly, I was wondering if it would be appropriate to change the
signature of socket-make-stream to
(socket &key input output element-type buffering external-format timeout)
I believe those are the right arguments, but there might be others that
should be "exported" from make-fd-stream.
There would no longer be the nice, elegant call to apply in
socket-make-stream; one could just make a normal function call with the
keyword arguments, but that seems like a small price to pay. But I am
not a real SBCL developer, only a user, so I bow to the list's feelings
A second question was raised by RMK --- some users have apparently
expressed puzzlement at the fact that a second call to
socket-make-stream on the same socket will return the same stream as the
first call. One could certainly stress this more in the docstring, and
I would be happy to do so. However, it's not clear that this is really
The Right Thing, is it? What if the first call to socket-make-stream is
(socket-make-stream sock :input t) and the second is (socket-make-stream
sock :output t). This second call requests an output stream, but will
get an input stream in response. Should socket-make-stream remember the
arguments to the first call and raise an error if the second call is
At any rate, I will propose a docstring soon, and provide a tentative
patch for the group's review.