open-named-pipe-stream name &key errorp allow-remote max-number wait-reason timeout wait-function direction inherit-access-p access => stream , connectedp , condition
A string identifying the pipe.
A boolean.
A boolean.
An integer in the inclusive range [1,254] or
nil
.
A string or
nil
.
A real number or
nil
.
A function of no arguments, or
nil
.
One of
:io
,
:input
,
:output
.
A boolean.
A list, keyword, integer or string.
The function
open-named-pipe-stream
creates a stream that communicates via a named pipe, and then tries to establish a connection. For a connection to be established, another process (which can be a Lisp process in the same image, or another process altogether) must connect to it. In LispWorks this is done by connect-to-named-pipe, other software does by the underlying Windows function
ConnectNamedPipe
.
open-named-pipe-stream
returns three values.
stream
is a stream on success, and
nil
if there is an error and
errorp
is
nil
. If
open-named-pipe-stream
returns a stream and
connectedp
is non-nil, the stream is connected and is ready for input/output operations like a normal stream.
condition
is an error condition if an error occurred and
errorp
is
nil
, otherwise it is
nil
.
When
open-named-pipe-stream
returns a stream and
connectedp
is
nil
(which can happen when
timeout
is non-nil or
wait-function
returns
t
), the stream is valid but is not ready for I/O and gives an error for any reading or writing calls. In this case the function wait-for-connection must be used to establish the connection, and once it returns non-nil the stream is ready for input/output operations.
Note that that if you stop using a stream before it is connected, it still must be closed (by
cl:close
) to get rid of the named pipe.
name
is the pipe name. It can contain any character except
#\\
(according to the MSDN).
open-named-pipe-stream
prepends to it the pipe prefix
\\.\pipe\
. It needs to be highly unique, because on the same machine it is visible to all processes.
direction
specifies the direction of I/O with the conventional meaning (as in Common Lisp file streams). The default value of
direction
is
:io
. All simultanous opened pipes with the same name on the same machine must be opened with the same value of
direction
. If different
direction
values are used, it causes
open-named-pipe-stream
to give an error.
max-number specifies the maximum number of simultanously existing pipes with the same name on the local machine. By default it is unlimited. All simultanous pipes with the same name on the same machine must have the same max-number , though currently this is not enforced.
access
specifies access permission, which controls who can connect to the pipe. If it is
nil
, the permissions of the current thread are inherited and used (
inherit-access-p
is ignored in this case), and if
access
is
:world
the pipe is created with no restrictions. Otherwise
access
has to be a keyword, a list, an integer or a string, and it is passed to security-description-string-for-open-named-pipe. See the entry for security-description-string-for-open-named-pipe for details. The result of security-description-string-for-open-named-pipe, potentially with the inherited access appended, is passed to the Windows function
ConvertStringSecurityDescriptorToSecurityDescriptor
to generate the descriptor that is used when creating the pipe.
inherit-access-p
controls whether the permissions of the current thread are inherited when
access
is not
nil
or
:world
or a string. When it is not
nil
, the permissions of the current thread are appended to what is specified by
access
(which means that the specification in
access
takes precedence). The default value of
inherit-access-p
is
t
.
allow-remote
controls whether the pipe can be connected from another machine. The default value of
allow-remote
is
nil
.
errorp controls what happens when there is a failure because of one of these possibilities:
nil
because
access
contains unknown entities (for example a user name that does not exist on the local machine)
open-named-pipe-stream
failed for some other reason, for example it reached the limit on the number of the pipes with this name, or tried to open it with a different
direction
from the previous call.
When there has been a failure, if
errorp
is non-nil an error is signalled, and if
errorp
is
nil
then
open-named-pipe-stream
returns
stream
nil
and
connectedp
nil
with the error condition returned as the third value
condition
. The default value of
errorp
is
t
.
Once the pipe has been successfully created,
open-named-pipe-stream
uses wait-for-connection to establish the connection, passing
timeout
,
wait-reason
and
wait-function
, and returns the stream as first value, the result of wait-for-connection as the second value, and
nil
as the third value. See the description of wait-for-connection for details.
To connect to the other side of the pipe from Lisp, use connect-to-named-pipe. The Microsoft Windows function is
ConnectNamedPipe
.
wait-for-connection
security-description-string-for-open-named-pipe
named-pipe-stream-name
connect-to-named-pipe
impersonating-named-pipe-client
LispWorks User Guide and Reference Manual - 21 Dec 2011