Skip to content
This repository has been archived by the owner on Apr 22, 2023. It is now read-only.

Commit

Permalink
docs: add example to net.connect()
Browse files Browse the repository at this point in the history 
Fixes #1824.
  • Loading branch information
@koichik
koichik committed Oct 6, 2011
1 parent 87286cc commit 9797482
Showing 1 changed file with 96 additions and 57 deletions.
153 changes: 96 additions & 57 deletions doc/api/net.markdown
View file
Expand Up @@ -2,12 +2,13 @@

The `net` module provides you with an asynchronous network wrapper. It contains
methods for creating both servers and clients (called streams). You can include
this module with `require("net");`
this module with `require('net');`

### net.createServer([options], [connectionListener])

Creates a new TCP server. The `connectionListener` argument is
automatically set as a listener for the `'connection'` event.
automatically set as a listener for the ['connection'](#event_connection_)
event.

`options` is an object with the following defaults:

Expand All @@ -16,65 +17,98 @@ automatically set as a listener for the `'connection'` event.

If `allowHalfOpen` is `true`, then the socket won't automatically send FIN
packet when the other end of the socket sends a FIN packet. The socket becomes
non-readable, but still writable. You should call the end() method explicitly.
See `'end'` event for more information.
non-readable, but still writable. You should call the `end()` method explicitly.
See ['end'](#event_end_) event for more information.

### net.createConnection(arguments...)
Here is an example of a echo server which listens for connections
on port 8124:

Construct a new socket object and opens a socket to the given location. When
the socket is established the `'connect'` event will be emitted.
var net = require('net');
var server = net.createServer(function(c) { //'connection' listener
console.log('server connected');
c.on('end', function() {
console.log('server disconnected');
});
c.write('hello\r\n');
c.pipe(c);
});
server.listen(8124, function() { //'listening' listener
console.log('server bound');
});

The arguments for this method change the type of connection:
Test this by using `telnet`:

* `net.createConnection(port, [host], [callback])`
telnet localhost 8124

Creates a TCP connection to `port` on `host`. If `host` is omitted,
`localhost` will be assumed.
To listen on the socket `/tmp/echo.sock` the third line from the last would
just be changed to

* `net.createConnection(path, [callback])`
server.listen('/tmp/echo.sock', function() { //'listening' listener

Creates unix socket connection to `path`
Use `nc` to connect to a UNIX domain socket server:

The `callback` parameter will be added as an listener for the `'connect'` event.
nc -U /tmp/echo.sock

---
### net.connect(arguments...)
### net.createConnection(arguments...)

### net.Server
Construct a new socket object and opens a socket to the given location. When
the socket is established the ['connect'](#event_connect_) event will be
emitted.

This class is used to create a TCP or UNIX server.
A server is a `net.Socket` that can listen for new incoming connections.
The arguments for these methods change the type of connection:

Here is an example of a echo server which listens for connections
on port 8124:
* `net.connect(port, [host], [connectListener])`
* `net.createConnection(port, [host], [connectListener])`

var net = require('net');
var server = net.createServer(function (c) {
c.write('hello\r\n');
c.pipe(c);
});
server.listen(8124, 'localhost');
Creates a TCP connection to `port` on `host`. If `host` is omitted,
`'localhost'` will be assumed.

Test this by using `telnet`:
* `net.connect(path, [connectListener])`
* `net.createConnection(path, [connectListener])`

telnet localhost 8124
Creates unix socket connection to `path`.

The `connectListener` parameter will be added as an listener for the
['connect'](#event_connect_) event.

Here is an example of a client of echo server as described previously:

var net = require('net');
var client = net.connect(8124, function() { //'connect' listener
console.log('client connected');
client.write('world!\r\n');
});
client.on('data', function(data) {
console.log(data.toString());
client.end();
});
client.on('end', function() {
console.log('client disconnected');
});

To listen on the socket `/tmp/echo.sock` the last line would just be
To connect on the socket `/tmp/echo.sock` the second line would just be
changed to

server.listen('/tmp/echo.sock');
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener

Use `nc` to connect to a UNIX domain socket server:
---

nc -U /tmp/echo.sock
### net.Server

#### server.listen(port, [host], [callback])
This class is used to create a TCP or UNIX server.
A server is a `net.Socket` that can listen for new incoming connections.

#### server.listen(port, [host], [listeningListener])

Begin accepting connections on the specified `port` and `host`. If the
`host` is omitted, the server will accept connections directed to any
IPv4 address (`INADDR_ANY`). A port value of zero will assign a random port.

This function is asynchronous. The last parameter `callback` will be called
when the server has been bound.
This function is asynchronous. When the server has been bound,
['listening'](#event_listening_) event will be emitted.
the last parameter `listeningListener` will be added as an listener for the
['listening'](#event_listening_) event.

One issue some users run into is getting `EADDRINUSE` errors. This means that
another server is already running on the requested port. One way of handling this
Expand All @@ -90,15 +124,16 @@ would be to wait a second and then try again. This can be done with
}
});

(Note: All sockets in Node are set SO_REUSEADDR already)
(Note: All sockets in Node set `SO_REUSEADDR` already)


#### server.listen(path, [callback])
#### server.listen(path, [listeningListener])

Start a UNIX socket server listening for connections on the given `path`.

This function is asynchronous. The last parameter `callback` will be called
when the server has been bound.
This function is asynchronous. The last parameter `listeningListener` will be
called when the server has been bound.
See also ['listening'](#event_listening_) event.

#### server.listenFD(fd)

Expand Down Expand Up @@ -142,7 +177,8 @@ Example:

#### server.maxConnections

Set this property to reject connections when the server's connection count gets high.
Set this property to reject connections when the server's connection count gets
high.

#### server.connections

Expand Down Expand Up @@ -201,8 +237,8 @@ Construct a new socket object.
specified underlying protocol. It can be `'tcp4'`, `'tcp6'`, or `'unix'`.
About `allowHalfOpen`, refer to `createServer()` and `'end'` event.

#### socket.connect(port, [host], [callback])
#### socket.connect(path, [callback])
#### socket.connect(port, [host], [connectListener])
#### socket.connect(path, [connectListener])

Opens the connection for a given socket. If `port` and `host` are given,
then the socket will be opened as a TCP socket, if `host` is omitted,
Expand All @@ -213,23 +249,23 @@ Normally this method is not needed, as `net.createConnection` opens the
socket. Use this only if you are implementing a custom Socket or if a
Socket is closed and you want to reuse it to connect to another server.

This function is asynchronous. When the `'connect'` event is emitted the
socket is established. If there is a problem connecting, the `'connect'`
event will not be emitted, the `'error'` event will be emitted with
This function is asynchronous. When the ['connect'](#event_connect_) event is
emitted the socket is established. If there is a problem connecting, the
`'connect'` event will not be emitted, the `'error'` event will be emitted with
the exception.

The `callback` parameter will be added as an listener for the 'connect'
event.
The `connectListener` parameter will be added as an listener for the
['connect'](#event_connect_) event.


#### socket.bufferSize

`net.Socket` has the property that `socket.write()` always works. This is to
help users get up and running quickly. The computer cannot always keep up
with the amount of data that is written to a socket - the network connection simply
might be too slow. Node will internally queue up the data written to a socket and
send it out over the wire when it is possible. (Internally it is polling on
the socket's file descriptor for being writable).
with the amount of data that is written to a socket - the network connection
simply might be too slow. Node will internally queue up the data written to a
socket and send it out over the wire when it is possible. (Internally it is
polling on the socket's file descriptor for being writable).

The consequence of this internal buffering is that memory may grow. This
property shows the number of characters currently buffered to be written.
Expand Down Expand Up @@ -276,8 +312,8 @@ event on the other end.
Half-closes the socket. i.e., it sends a FIN packet. It is possible the
server will still send some data.

If `data` is specified, it is equivalent to calling `socket.write(data, encoding)`
followed by `socket.end()`.
If `data` is specified, it is equivalent to calling
`socket.write(data, encoding)` followed by `socket.end()`.

#### socket.destroy()

Expand All @@ -304,7 +340,8 @@ or `destroy()` the socket.

If `timeout` is 0, then the existing idle timeout is disabled.

The optional `callback` parameter will be added as a one time listener for the `'timeout'` event.
The optional `callback` parameter will be added as a one time listener for the
`'timeout'` event.

#### socket.setNoDelay(noDelay=true)

Expand All @@ -323,8 +360,9 @@ initialDelay will leave the value unchanged from the default

#### socket.address()

Returns the bound address and port of the socket as reported by the operating system.
Returns an object with two properties, e.g. `{"address":"192.168.57.1", "port":62053}`
Returns the bound address and port of the socket as reported by the operating
system. Returns an object with two properties, e.g.
`{"address":"192.168.57.1", "port":62053}`

#### socket.remoteAddress

Expand Down Expand Up @@ -360,7 +398,8 @@ See `connect()`.

Emitted when data is received. The argument `data` will be a `Buffer` or
`String`. Encoding of data is set by `socket.setEncoding()`.
(See the [Readable Stream](streams.html#readable_Stream) section for more information.)
(See the [Readable Stream](streams.html#readable_Stream) section for more
information.)

#### Event: 'end'

Expand Down

0 comments on commit 9797482

Please sign in to comment.