Function

Summary

Creates a stream that writes and read through a named pipe.

Package

win32

Signature

open-named-pipe-stream name &key errorp allow-remote max-number wait-reason timeout wait-function direction inherit-access-p access => stream, connectedp, condition

Arguments

name

A string identifying the pipe.

errorp

A boolean.

allow-remote

A boolean.

max-number

An integer in the inclusive range [1,254] or nil.

wait-reason

A string or nil.

timeout

A real number or nil.

wait-function

A function of no arguments, or nil.

direction

One of :io, :input, :output.

inherit-access-p

A boolean.

access

A list, keyword, integer or string.

Values

stream

A stream or nil.

connectedp

A boolean.

condition

An error condition or nil.

Description

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.

The creation has two steps:

1. Creating the named pipe. This is controlled by name, max-number, direction, access, inherit-access-p, allow-remote and errorp.
2. Waiting for connection. This is controlled by timeout, wait-reason, and wait-function.

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 simultaneous 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 simultaneously existing pipes with the same name on the local machine. By default it is unlimited. All simultaneous 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:

1. security-description-string-for-open-named-pipe returns nil because access contains unknown entities (for example a user name that does not exist on the local machine)
2. Converting the string that security-description-string-for-open-named-pipe returned to a security descriptor failed. That can happen if access is a string in bad format or a list containing strings in bad format.
3. 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 signaled, 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.

See also

wait-for-connection
security-description-string-for-open-named-pipe
named-pipe-stream-name
connect-to-named-pipe
impersonating-named-pipe-client