Browse files

Doc fixes for FD related features, upgrade.

- Add docs for 'fd' events, Server.listenFD(), Stream.write(...[, fd])
  and http.Client 'upgrade' event.
  • Loading branch information...
1 parent 82ce348 commit 94cd83ef34176f4e451e91c92d3b2596032b8e96 @pgriess pgriess committed with ry Jun 22, 2010
Showing with 32 additions and 4 deletions.
  1. +29 −1 doc/api.markdown
  2. +3 −3 lib/net.js
@@ -312,6 +312,13 @@ Emitted when the underlying file descriptor has be closed. Not all streams
will emit this. (For example, an incoming HTTP request will not emit
+### Event: 'fd'
+`function (fd) { }`
+Emitted when a file descriptor is received on the stream. Only UNIX streams
+support this functionality; all others will simply never emit this event.
### stream.setEncoding(encoding)
Makes the data event emit a string instead of a `Buffer`. `encoding` can be
`'utf8'`, `'ascii'`, or `'binary'`.
@@ -353,14 +360,19 @@ Emitted on error with the exception `exception`.
Emitted when the underlying file descriptor has been closed.
-### stream.write(string, encoding)
+### stream.write(string, encoding, [fd])
Writes `string` with the given `encoding` to the stream. Returns `true` if
the string has been flushed to the kernel buffer. Returns `false` to
indicate that the kernel buffer is full, and the data will be sent out in
the future. The `'drain'` event will indicate when the kernel buffer is
empty again. The `encoding` defaults to `'utf8'`.
+If the optional `fd` parameter is specified, it is interpreted as an integral
+file descriptor to be sent over the stream. This is only supported for UNIX
+streams, and is silently ignored otherwise. When writing a file descriptor in
+this manner, closing the descriptor before the stream drains risks sending an
+invalid (closed) FD.
### stream.write(buffer)
@@ -1844,6 +1856,16 @@ Example of connecting to ``:
+### Event: 'upgrade'
+`function (request, socket, head)`
+Emitted each time a server responds to a request with an upgrade. If this event
+isn't being listened for, clients receiving an upgrade header will have their
+connections closed.
+See the description of the `upgrade` event for `http.Server` for further details.
### http.createClient(port, host, secure, credentials)
Constructs a new HTTP client. `port` and
@@ -2081,6 +2103,12 @@ This function is asynchronous. The last parameter `callback` will be called
when the server has been bound.
+### server.listenFD(fd)
+Start a server listening for connections on the given file descriptor.
+This file descriptor must have already had the `bind(2)` and `listen(2)` system
+calls invoked on it.
### server.close()
@@ -318,7 +318,9 @@ function setImplmentationMethods (self) {
// by the kernel for some reason. Otherwise, we'd just
// fast-path return here.
- return write(self.fd, buf, off, len, fd, flags);
+ // Drop 'fd' and 'flags' as these are not supported by the write(2)
+ // system call
+ return write(self.fd, buf, off, len);
self._readImpl = function(buf, off, len, calledByIOWatcher) {
@@ -652,8 +654,6 @@ Object.defineProperty(Stream.prototype, 'readyState', {
// Returns true if all the data was flushed to socket. Returns false if
// something was queued. If data was queued, then the "drain" event will
// signal when it has been finally flushed to socket.
-// XXX: Caller cannot close the given fd until the stream has drained.
Stream.prototype.write = function (data, encoding, fd) {
if (this._writeQueue && this._writeQueue.length) {
// Slow. There is already a write queue, so let's append to it.

0 comments on commit 94cd83e

Please sign in to comment.