debian/0000755000000000000000000000000012054744631007174 5ustar debian/nodejs-dev.manpages0000644000000000000000000000002212004014433012722 0ustar debian/node-waf.1 debian/nodejs.install0000644000000000000000000000003012004014433012020 0ustar debian/tmp/usr/bin/node debian/nodejs.postinst0000644000000000000000000000053412004014454012251 0ustar #!/bin/sh set -e if [ "$1" = "configure" ]; then if dpkg --compare-versions "$2" le 0.6.19~dfsg1-2; then update-alternatives --remove js /usr/bin/node fi update-alternatives --install /usr/bin/js js /usr/bin/nodejs 200 \ --slave /usr/share/man/man1/js.1.gz js.1.gz /usr/share/man/man1/nodejs.1.gz fi #DEBHELPER# debian/patches/0000755000000000000000000000000012027336463010623 5ustar debian/patches/2011_enable_mipsel_build.patch0000644000000000000000000000310612004014454016251 0ustar Description: Enable mipsel build wscript needs to recognize mips arch. tools/test.py is only used to run js tests, so arch is not needed there. Forwarded: not-needed Author: Jérémy Lal Last-Update: 2012-04-01 --- a/wscript +++ b/wscript @@ -43,7 +43,7 @@ srcdir = '.' blddir = 'out' -supported_archs = ('arm', 'ia32', 'x64') # 'mips' supported by v8, but not node +supported_archs = ('arm', 'ia32', 'x64', 'mips') # 'mips' supported by v8, but not node jobs=1 if os.environ.has_key('JOBS'): @@ -53,7 +53,7 @@ return path.replace("\\", "/") def canonical_cpu_type(arch): - m = {'x86': 'ia32', 'i386':'ia32', 'x86_64':'x64', 'amd64':'x64'} + m = {'x86': 'ia32', 'i386':'ia32', 'x86_64':'x64', 'amd64':'x64', 'mipsel':'mips'} if arch in m: arch = m[arch] if not arch in supported_archs: raise Exception("supported architectures are "+', '.join(supported_archs)+\ --- a/tools/test.py +++ b/tools/test.py @@ -1203,12 +1203,12 @@ return False # Ensure that the simulator argument is handed down to scons. options.scons_flags.append("simulator=" + options.simulator) - else: + #else: # If options.arch is not set by the command line and no simulator setting # was found, set the arch to the guess. - if options.arch == 'none': - options.arch = ARCH_GUESS - options.scons_flags.append("arch=" + options.arch) + # if options.arch == 'none': + # options.arch = ARCH_GUESS + # options.scons_flags.append("arch=" + options.arch) if options.snapshot: options.scons_flags.append("snapshot=on") return True debian/patches/2008_fix_use_shared_cares.patch0000644000000000000000000001420112004014454016444 0ustar Description: Use system libc-ares Author: Jérémy Lal Forwarded: not-needed Last-Update: 2012-01-23 --- a/deps/uv/Makefile +++ b/deps/uv/Makefile @@ -26,51 +26,6 @@ CPPFLAGS += -Iinclude -Iinclude/uv-private -CARES_OBJS = -CARES_OBJS += src/ares/ares__close_sockets.o -CARES_OBJS += src/ares/ares__get_hostent.o -CARES_OBJS += src/ares/ares__read_line.o -CARES_OBJS += src/ares/ares__timeval.o -CARES_OBJS += src/ares/ares_cancel.o -CARES_OBJS += src/ares/ares_data.o -CARES_OBJS += src/ares/ares_destroy.o -CARES_OBJS += src/ares/ares_expand_name.o -CARES_OBJS += src/ares/ares_expand_string.o -CARES_OBJS += src/ares/ares_fds.o -CARES_OBJS += src/ares/ares_free_hostent.o -CARES_OBJS += src/ares/ares_free_string.o -CARES_OBJS += src/ares/ares_gethostbyaddr.o -CARES_OBJS += src/ares/ares_gethostbyname.o -CARES_OBJS += src/ares/ares_getnameinfo.o -CARES_OBJS += src/ares/ares_getopt.o -CARES_OBJS += src/ares/ares_getsock.o -CARES_OBJS += src/ares/ares_init.o -CARES_OBJS += src/ares/ares_library_init.o -CARES_OBJS += src/ares/ares_llist.o -CARES_OBJS += src/ares/ares_mkquery.o -CARES_OBJS += src/ares/ares_nowarn.o -CARES_OBJS += src/ares/ares_options.o -CARES_OBJS += src/ares/ares_parse_a_reply.o -CARES_OBJS += src/ares/ares_parse_aaaa_reply.o -CARES_OBJS += src/ares/ares_parse_mx_reply.o -CARES_OBJS += src/ares/ares_parse_ns_reply.o -CARES_OBJS += src/ares/ares_parse_ptr_reply.o -CARES_OBJS += src/ares/ares_parse_srv_reply.o -CARES_OBJS += src/ares/ares_parse_txt_reply.o -CARES_OBJS += src/ares/ares_process.o -CARES_OBJS += src/ares/ares_query.o -CARES_OBJS += src/ares/ares_search.o -CARES_OBJS += src/ares/ares_send.o -CARES_OBJS += src/ares/ares_strcasecmp.o -CARES_OBJS += src/ares/ares_strdup.o -CARES_OBJS += src/ares/ares_strerror.o -CARES_OBJS += src/ares/ares_timeout.o -CARES_OBJS += src/ares/ares_version.o -CARES_OBJS += src/ares/ares_writev.o -CARES_OBJS += src/ares/bitncmp.o -CARES_OBJS += src/ares/inet_net_pton.o -CARES_OBJS += src/ares/inet_ntop.o - ifneq (,$(findstring MINGW,$(uname_S))) include config-mingw.mk else @@ -82,9 +37,6 @@ all: uv.a -$(CARES_OBJS): %.o: %.c - $(CC) -o $*.o -c $(CFLAGS) $(CPPFLAGS) $< -DHAVE_CONFIG_H - test/run-tests$(E): test/*.h test/run-tests.c $(RUNNER_SRC) test/runner-unix.c $(TESTS) uv.a $(CC) $(CPPFLAGS) $(RUNNER_CFLAGS) -o test/run-tests test/run-tests.c \ test/runner.c $(RUNNER_SRC) $(TESTS) uv.a $(RUNNER_LIBS) $(RUNNER_LINKFLAGS) --- a/deps/uv/config-unix.mk +++ b/deps/uv/config-unix.mk @@ -60,8 +60,8 @@ EV_CONFIG=config_linux.h EIO_CONFIG=config_linux.h CSTDFLAG += -D_GNU_SOURCE -CPPFLAGS += -Isrc/ares/config_linux -LINKFLAGS+=-lrt +CPPFLAGS += -I/usr/include +LINKFLAGS+=-lrt -lc-ares OBJS += src/unix/linux.o endif @@ -124,8 +124,8 @@ RUNNER_LIBS= RUNNER_SRC=test/runner-unix.c -uv.a: $(OBJS) src/uv-common.o src/unix/ev/ev.o src/unix/uv-eio.o src/unix/eio/eio.o $(CARES_OBJS) - $(AR) rcs uv.a $(OBJS) src/uv-common.o src/unix/uv-eio.o src/unix/ev/ev.o src/unix/eio/eio.o $(CARES_OBJS) +uv.a: $(OBJS) src/uv-common.o src/unix/ev/ev.o src/unix/uv-eio.o src/unix/eio/eio.o + $(AR) rcs uv.a $(OBJS) src/uv-common.o src/unix/uv-eio.o src/unix/ev/ev.o src/unix/eio/eio.o src/unix/%.o: src/unix/%.c include/uv.h include/uv-private/uv-unix.h src/unix/internal.h $(CC) $(CSTDFLAG) $(CPPFLAGS) -Isrc $(CFLAGS) -c $< -o $@ @@ -150,14 +150,12 @@ clean-platform: - -rm -f src/ares/*.o -rm -f src/unix/ev/*.o -rm -f src/unix/eio/*.o -rm -f src/unix/*.o -rm -rf test/run-tests.dSYM run-benchmarks.dSYM distclean-platform: - -rm -f src/ares/*.o -rm -f src/unix/ev/*.o -rm -f src/unix/*.o -rm -f src/unix/eio/*.o --- a/wscript +++ b/wscript @@ -441,6 +441,18 @@ if conf.env["USE_SHARED_ZLIB"] and not sys.platform.startswith("win32"): conf.env.append_value("LINKFLAGS", "-lz") + if conf.env['USE_SHARED_CARES']: + cares_includes = []; + if o.shared_cares_includes: cares_includes.append(o.shared_cares_includes); + cares_libpath = []; + if o.shared_cares_libpath: cares_libpath.append(o.shared_cares_libpath); + if not conf.check_cxx(lib='cares', + header_name='ares.h', + uselib_store='CARES', + includes=cares_includes, + libpath=cares_libpath): + conf.fatal("Cannot find c-ares") + conf.define("HAVE_CONFIG_H", 1) if sys.platform.startswith("sunos"): @@ -678,10 +690,6 @@ bld.install_files('${PREFIX}/include/node/', 'deps/uv/include/*.h') bld.install_files('${PREFIX}/include/node/uv-private', 'deps/uv/include/uv-private/*.h') bld.install_files('${PREFIX}/include/node/ev', 'deps/uv/src/ev/*.h') - bld.install_files('${PREFIX}/include/node/c-ares', """ - deps/uv/include/ares.h - deps/uv/include/ares_version.h - """) def build(bld): @@ -938,7 +946,6 @@ deps/http_parser deps/uv/include deps/uv/src/ev - deps/uv/src/ares """ if not bld.env["USE_SHARED_V8"]: node.includes += ' deps/v8/include ' --- a/deps/uv/src/uv-common.c +++ b/deps/uv/src/uv-common.c @@ -27,9 +27,8 @@ #include /* memset */ /* use inet_pton from c-ares if necessary */ -#include "ares_config.h" -#include "ares/inet_net_pton.h" -#include "ares/inet_ntop.h" +#include +#include static uv_counters_t counters; @@ -131,20 +130,20 @@ addr.sin6_family = AF_INET6; addr.sin6_port = htons(port); - ares_inet_pton(AF_INET6, ip, &addr.sin6_addr); + inet_pton(AF_INET6, ip, &addr.sin6_addr); return addr; } int uv_ip4_name(struct sockaddr_in* src, char* dst, size_t size) { - const char* d = ares_inet_ntop(AF_INET, &src->sin_addr, dst, size); + const char* d = inet_ntop(AF_INET, &src->sin_addr, dst, size); return d != dst; } int uv_ip6_name(struct sockaddr_in6* src, char* dst, size_t size) { - const char* d = ares_inet_ntop(AF_INET6, &src->sin6_addr, dst, size); + const char* d = inet_ntop(AF_INET6, &src->sin6_addr, dst, size); return d != dst; } --- a/deps/uv/include/uv.h +++ b/deps/uv/include/uv.h @@ -54,7 +54,7 @@ #include /* int64_t */ #include /* size_t */ -#include "ares.h" +#include #ifndef _SSIZE_T_ typedef intptr_t ssize_t; debian/patches/2007_fix_use_shared_zlib.patch0000644000000000000000000000155112004014454016312 0ustar Description: Use system zlib Author: Jérémy Lal Forwarded: not-needed Last-Update: 2012-01-23 --- a/wscript +++ b/wscript @@ -296,9 +296,6 @@ conf.env["USE_GDBJIT"] = o.use_gdbjit conf.env['USE_NPM'] = not o.without_npm - if not conf.env["USE_SHARED_ZLIB"] and not sys.platform.startswith("win32"): - conf.env.append_value("LINKFLAGS", "-lz") - conf.check(lib='dl', uselib_store='DL') if not sys.platform.startswith("sunos") and not sys.platform.startswith("win32"): conf.env.append_value("CCFLAGS", "-rdynamic") @@ -441,6 +438,9 @@ libpath=v8_libpath): conf.fatal("Cannot find v8_g") + if conf.env["USE_SHARED_ZLIB"] and not sys.platform.startswith("win32"): + conf.env.append_value("LINKFLAGS", "-lz") + conf.define("HAVE_CONFIG_H", 1) if sys.platform.startswith("sunos"): debian/patches/2013_waf_linkflags.patch0000644000000000000000000000057312004014454015111 0ustar Description: node-waf LINKFLAGS support Fix taken from waf 1.5.19 Author: Jérémy Lal Forwarded: https://github.com/joyent/node/issues/3524 Last-Update: 2012-06-24 --- a/tools/wafadmin/Tools/gxx.py +++ b/tools/wafadmin/Tools/gxx.py @@ -131,4 +131,5 @@ conf.gxx_modifier_platform() conf.cxx_load_tools() conf.cxx_add_flags() + conf.link_add_flags() debian/patches/1002_upstream_forgot_to_build_doc.patch0000644000000000000000001773140112004014454020236 0ustar Description: Upstream re-released 0.6.19 with properly built docs. Author: Jérémy Lal Origin: https://groups.google.com/forum/?fromgroups#!topic/nodejs/cZBNqVamTJ8 Last-Update: 2012-06-16 --- /dev/null +++ b/doc/api/dgram.json @@ -0,0 +1,381 @@ +{ + "source": "doc/api/dgram.markdown", + "modules": [ + { + "textRaw": "UDP / Datagram Sockets", + "name": "dgram", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Datagram sockets are available through require('dgram').\n\n

\n", + "methods": [ + { + "textRaw": "dgram.createSocket(type, [callback])", + "type": "method", + "name": "createSocket", + "signatures": [ + { + "return": { + "textRaw": "Returns: Socket object ", + "name": "return", + "desc": "Socket object" + }, + "params": [ + { + "textRaw": "`type` String. Either 'udp4' or 'udp6' ", + "name": "type", + "desc": "String. Either 'udp4' or 'udp6'" + }, + { + "textRaw": "`callback` Function. Attached as a listener to `message` events. Optional ", + "name": "callback", + "optional": true, + "desc": "Function. Attached as a listener to `message` events." + } + ] + }, + { + "params": [ + { + "name": "type" + }, + { + "name": "callback", + "optional": true + } + ] + } + ], + "desc": "

Creates a datagram Socket of the specified types. Valid types are udp4\nand udp6.\n\n

\n

Takes an optional callback which is added as a listener for message events.\n\n

\n

Call socket.bind if you want to receive datagrams. socket.bind() will bind\nto the "all interfaces" address on a random port (it does the right thing for\nboth udp4 and udp6 sockets). You can then retrieve the address and port\nwith socket.address().address and socket.address().port.\n\n

\n" + } + ], + "classes": [ + { + "textRaw": "Class: Socket", + "type": "class", + "name": "Socket", + "desc": "

The dgram Socket class encapsulates the datagram functionality. It\nshould be created via dgram.createSocket(type, [callback]).\n\n

\n", + "events": [ + { + "textRaw": "Event: 'message'", + "type": "event", + "name": "message", + "params": [], + "desc": "

Emitted when a new datagram is available on a socket. msg is a Buffer and rinfo is\nan object with the sender's address information and the number of bytes in the datagram.\n\n

\n" + }, + { + "textRaw": "Event: 'listening'", + "type": "event", + "name": "listening", + "desc": "

Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets\nare created.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

Emitted when a socket is closed with close(). No new message events will be emitted\non this socket.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "params": [], + "desc": "

Emitted when an error occurs.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "dgram.send(buf, offset, length, port, address, [callback])", + "type": "method", + "name": "send", + "signatures": [ + { + "params": [ + { + "textRaw": "`buf` Buffer object. Message to be sent ", + "name": "buf", + "desc": "Buffer object. Message to be sent" + }, + { + "textRaw": "`offset` Integer. Offset in the buffer where the message starts. ", + "name": "offset", + "desc": "Integer. Offset in the buffer where the message starts." + }, + { + "textRaw": "`length` Integer. Number of bytes in the message. ", + "name": "length", + "desc": "Integer. Number of bytes in the message." + }, + { + "textRaw": "`port` Integer. destination port ", + "name": "port", + "desc": "Integer. destination port" + }, + { + "textRaw": "`address` String. destination IP ", + "name": "address", + "desc": "String. destination IP" + }, + { + "textRaw": "`callback` Function. Callback when message is done being delivered. Optional. ", + "name": "callback", + "desc": "Function. Callback when message is done being delivered. Optional.", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "buf" + }, + { + "name": "offset" + }, + { + "name": "length" + }, + { + "name": "port" + }, + { + "name": "address" + }, + { + "name": "callback", + "optional": true + } + ] + } + ], + "desc": "

For UDP sockets, the destination port and IP address must be specified. A string\nmay be supplied for the address parameter, and it will be resolved with DNS. An\noptional callback may be specified to detect any DNS errors and when buf may be\nre-used. Note that DNS lookups will delay the time that a send takes place, at\nleast until the next tick. The only way to know for sure that a send has taken place\nis to use the callback.\n\n

\n

If the socket has not been previously bound with a call to bind, it's\nassigned a random port number and bound to the "all interfaces" address\n(0.0.0.0 for udp4 sockets, ::0 for udp6 sockets).\n\n

\n

Example of sending a UDP packet to a random port on localhost;\n\n

\n
var dgram = require('dgram');\nvar message = new Buffer("Some bytes");\nvar client = dgram.createSocket("udp4");\nclient.send(message, 0, message.length, 41234, "localhost", function(err, bytes) {\n  client.close();\n});
\n

A Note about UDP datagram size\n\n

\n

The maximum size of an IPv4/v6 datagram depends on the MTU (Maximum Transmission Unit)\nand on the Payload Length field size.\n\n

\n
    \n

  • The Payload Length field is 16 bits wide, which means that a normal payload\ncannot be larger than 64K octets including internet header and data\n(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header);\nthis is generally true for loopback interfaces, but such long datagrams\nare impractical for most hosts and networks.

    \n
    • \n

  • The MTU is the largest size a given link layer technology can support for datagrams.\nFor any link, IPv4 mandates a minimum MTU of 68 octets, while the recommended MTU\nfor IPv4 is 576 (typically recommended as the MTU for dial-up type applications),\nwhether they arrive whole or in fragments.

    \n

    For IPv6, the minimum MTU is 1280 octets, however, the mandatory minimum\nfragment reassembly buffer size is 1500 octets.\nThe value of 68 octets is very small, since most current link layer technologies have\na minimum MTU of 1500 (like Ethernet).

    \n
    • \n
\n

Note that it's impossible to know in advance the MTU of each link through which\na packet might travel, and that generally sending a datagram greater than\nthe (receiver) MTU won't work (the packet gets silently dropped, without\ninforming the source that the data did not reach its intended recipient).\n\n

\n" + }, + { + "textRaw": "dgram.bind(port, [address])", + "type": "method", + "name": "bind", + "signatures": [ + { + "params": [ + { + "textRaw": "`port` Integer ", + "name": "port", + "desc": "Integer" + }, + { + "textRaw": "`address` String, Optional ", + "name": "address", + "optional": true, + "desc": "String" + } + ] + }, + { + "params": [ + { + "name": "port" + }, + { + "name": "address", + "optional": true + } + ] + } + ], + "desc": "

For UDP sockets, listen for datagrams on a named port and optional address. If\naddress is not specified, the OS will try to listen on all addresses.\n\n

\n

Example of a UDP server listening on port 41234:\n\n

\n
var dgram = require("dgram");\n\nvar server = dgram.createSocket("udp4");\n\nserver.on("message", function (msg, rinfo) {\n  console.log("server got: " + msg + " from " +\n    rinfo.address + ":" + rinfo.port);\n});\n\nserver.on("listening", function () {\n  var address = server.address();\n  console.log("server listening " +\n      address.address + ":" + address.port);\n});\n\nserver.bind(41234);\n// server listening 0.0.0.0:41234
\n" + }, + { + "textRaw": "dgram.close()", + "type": "method", + "name": "close", + "desc": "

Close the underlying socket and stop listening for data on it.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "dgram.address()", + "type": "method", + "name": "address", + "desc": "

Returns an object containing the address information for a socket. For UDP sockets,\nthis object will contain address and port.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "dgram.setBroadcast(flag)", + "type": "method", + "name": "setBroadcast", + "signatures": [ + { + "params": [ + { + "textRaw": "`flag` Boolean ", + "name": "flag", + "desc": "Boolean" + } + ] + }, + { + "params": [ + { + "name": "flag" + } + ] + } + ], + "desc": "

Sets or clears the SO_BROADCAST socket option. When this option is set, UDP packets\nmay be sent to a local interface's broadcast address.\n\n

\n" + }, + { + "textRaw": "dgram.setTTL(ttl)", + "type": "method", + "name": "setTTL", + "signatures": [ + { + "params": [ + { + "textRaw": "`ttl` Integer ", + "name": "ttl", + "desc": "Integer" + } + ] + }, + { + "params": [ + { + "name": "ttl" + } + ] + } + ], + "desc": "

Sets the IP_TTL socket option. TTL stands for "Time to Live," but in this context it\nspecifies the number of IP hops that a packet is allowed to go through. Each router or\ngateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a\nrouter, it will not be forwarded. Changing TTL values is typically done for network\nprobes or when multicasting.\n\n

\n

The argument to setTTL() is a number of hops between 1 and 255. The default on most\nsystems is 64.\n\n

\n" + }, + { + "textRaw": "dgram.setMulticastTTL(ttl)", + "type": "method", + "name": "setMulticastTTL", + "signatures": [ + { + "params": [ + { + "textRaw": "`ttl` Integer ", + "name": "ttl", + "desc": "Integer" + } + ] + }, + { + "params": [ + { + "name": "ttl" + } + ] + } + ], + "desc": "

Sets the IP_MULTICAST_TTL socket option. TTL stands for "Time to Live," but in this\ncontext it specifies the number of IP hops that a packet is allowed to go through,\nspecifically for multicast traffic. Each router or gateway that forwards a packet\ndecrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded.\n\n

\n

The argument to setMulticastTTL() is a number of hops between 0 and 255. The default on most\nsystems is 64.\n\n

\n" + }, + { + "textRaw": "dgram.setMulticastLoopback(flag)", + "type": "method", + "name": "setMulticastLoopback", + "signatures": [ + { + "params": [ + { + "textRaw": "`flag` Boolean ", + "name": "flag", + "desc": "Boolean" + } + ] + }, + { + "params": [ + { + "name": "flag" + } + ] + } + ], + "desc": "

Sets or clears the IP_MULTICAST_LOOP socket option. When this option is set, multicast\npackets will also be received on the local interface.\n\n

\n" + }, + { + "textRaw": "dgram.addMembership(multicastAddress, [multicastInterface])", + "type": "method", + "name": "addMembership", + "signatures": [ + { + "params": [ + { + "textRaw": "`multicastAddress` String ", + "name": "multicastAddress", + "desc": "String" + }, + { + "textRaw": "`multicastInterface` String, Optional ", + "name": "multicastInterface", + "optional": true, + "desc": "String" + } + ] + }, + { + "params": [ + { + "name": "multicastAddress" + }, + { + "name": "multicastInterface", + "optional": true + } + ] + } + ], + "desc": "

Tells the kernel to join a multicast group with IP_ADD_MEMBERSHIP socket option.\n\n

\n

If multicastInterface is not specified, the OS will try to add membership to all valid\ninterfaces.\n\n

\n" + }, + { + "textRaw": "dgram.dropMembership(multicastAddress, [multicastInterface])", + "type": "method", + "name": "dropMembership", + "signatures": [ + { + "params": [ + { + "textRaw": "`multicastAddress` String ", + "name": "multicastAddress", + "desc": "String" + }, + { + "textRaw": "`multicastInterface` String, Optional ", + "name": "multicastInterface", + "optional": true, + "desc": "String" + } + ] + }, + { + "params": [ + { + "name": "multicastAddress" + }, + { + "name": "multicastInterface", + "optional": true + } + ] + } + ], + "desc": "

Opposite of addMembership - tells the kernel to leave a multicast group with\nIP_DROP_MEMBERSHIP socket option. This is automatically called by the kernel\nwhen the socket is closed or process terminates, so most apps will never need to call\nthis.\n\n

\n

If multicastInterface is not specified, the OS will try to drop membership to all valid\ninterfaces.\n

\n" + } + ] + } + ], + "type": "module", + "displayName": "dgram" + } + ] +} --- /dev/null +++ b/doc/api/fs.html @@ -0,0 +1,815 @@ + + + + + File System Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ +
+

Table of Contents

+ + +
+ +
+

File System#

+
Stability: 3 - Stable
+ + +

File I/O is provided by simple wrappers around standard POSIX functions. To +use this module do require('fs'). All the methods have asynchronous and +synchronous forms. + +

+

The asynchronous form always take a completion callback as its last argument. +The arguments passed to the completion callback depend on the method, but the +first argument is always reserved for an exception. If the operation was +completed successfully, then the first argument will be null or undefined. + +

+

When using the synchronous form any exceptions are immediately thrown. +You can use try/catch to handle exceptions or allow them to bubble up. + +

+

Here is an example of the asynchronous version: + +

+
var fs = require('fs');
+
+fs.unlink('/tmp/hello', function (err) {
+  if (err) throw err;
+  console.log('successfully deleted /tmp/hello');
+});
+

Here is the synchronous version: + +

+
var fs = require('fs');
+
+fs.unlinkSync('/tmp/hello')
+console.log('successfully deleted /tmp/hello');
+

With the asynchronous methods there is no guaranteed ordering. So the +following is prone to error: + +

+
fs.rename('/tmp/hello', '/tmp/world', function (err) {
+  if (err) throw err;
+  console.log('renamed complete');
+});
+fs.stat('/tmp/world', function (err, stats) {
+  if (err) throw err;
+  console.log('stats: ' + JSON.stringify(stats));
+});
+

It could be that fs.stat is executed before fs.rename. +The correct way to do this is to chain the callbacks. + +

+
fs.rename('/tmp/hello', '/tmp/world', function (err) {
+  if (err) throw err;
+  fs.stat('/tmp/world', function (err, stats) {
+    if (err) throw err;
+    console.log('stats: ' + JSON.stringify(stats));
+  });
+});
+

In busy processes, the programmer is strongly encouraged to use the +asynchronous versions of these calls. The synchronous versions will block +the entire process until they complete--halting all connections. + +

+

Relative path to filename can be used, remember however that this path will be relative +to process.cwd(). + +

+

fs.rename(path1, path2, [callback])#

+

Asynchronous rename(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.renameSync(path1, path2)#

+

Synchronous rename(2). + +

+

fs.truncate(fd, len, [callback])#

+

Asynchronous ftruncate(2). No arguments other than a possible exception are +given to the completion callback. + +

+

fs.truncateSync(fd, len)#

+

Synchronous ftruncate(2). + +

+

fs.chown(path, uid, gid, [callback])#

+

Asynchronous chown(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.chownSync(path, uid, gid)#

+

Synchronous chown(2). + +

+

fs.fchown(fd, uid, gid, [callback])#

+

Asynchronous fchown(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.fchownSync(fd, uid, gid)#

+

Synchronous fchown(2). + +

+

fs.lchown(path, uid, gid, [callback])#

+

Asynchronous lchown(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.lchownSync(path, uid, gid)#

+

Synchronous lchown(2). + +

+

fs.chmod(path, mode, [callback])#

+

Asynchronous chmod(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.chmodSync(path, mode)#

+

Synchronous chmod(2). + +

+

fs.fchmod(fd, mode, [callback])#

+

Asynchronous fchmod(2). No arguments other than a possible exception +are given to the completion callback. + +

+

fs.fchmodSync(fd, mode)#

+

Synchronous fchmod(2). + +

+

fs.lchmod(path, mode, [callback])#

+

Asynchronous lchmod(2). No arguments other than a possible exception +are given to the completion callback. + +

+

fs.lchmodSync(path, mode)#

+

Synchronous lchmod(2). + +

+

fs.stat(path, [callback])#

+

Asynchronous stat(2). The callback gets two arguments (err, stats) where +stats is a fs.Stats object. See the fs.Stats +section below for more information. + +

+

fs.lstat(path, [callback])#

+

Asynchronous lstat(2). The callback gets two arguments (err, stats) where +stats is a fs.Stats object. lstat() is identical to stat(), except that if +path is a symbolic link, then the link itself is stat-ed, not the file that it +refers to. + +

+

fs.fstat(fd, [callback])#

+

Asynchronous fstat(2). The callback gets two arguments (err, stats) where +stats is a fs.Stats object. fstat() is identical to stat(), except that +the file to be stat-ed is specified by the file descriptor fd. + +

+

fs.statSync(path)#

+

Synchronous stat(2). Returns an instance of fs.Stats. + +

+

fs.lstatSync(path)#

+

Synchronous lstat(2). Returns an instance of fs.Stats. + +

+

fs.fstatSync(fd)#

+

Synchronous fstat(2). Returns an instance of fs.Stats. + +

+

fs.link(srcpath, dstpath, [callback])#

+

Asynchronous link(2). No arguments other than a possible exception are given to +the completion callback. + +

+

fs.linkSync(srcpath, dstpath)#

+

Synchronous link(2). + +

+

fs.symlink(linkdata, path, [type], [callback])#

+

Asynchronous symlink(2). No arguments other than a possible exception are given +to the completion callback. +type argument can be either 'dir' or 'file' (default is 'file'). It is only +used on Windows (ignored on other platforms). + +

+

fs.symlinkSync(linkdata, path, [type])#

+

Synchronous symlink(2). + +

+

fs.readlink(path, [callback])#

+

Asynchronous readlink(2). The callback gets two arguments (err, +linkString). + +

+

fs.readlinkSync(path)#

+

Synchronous readlink(2). Returns the symbolic link's string value. + +

+

fs.realpath(path, [callback])#

+

Asynchronous realpath(2). The callback gets two arguments (err, +resolvedPath). May use process.cwd to resolve relative paths. + +

+

fs.realpathSync(path)#

+

Synchronous realpath(2). Returns the resolved path. + +

+

fs.unlink(path, [callback])#

+

Asynchronous unlink(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.unlinkSync(path)#

+

Synchronous unlink(2). + +

+

fs.rmdir(path, [callback])#

+

Asynchronous rmdir(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.rmdirSync(path)#

+

Synchronous rmdir(2). + +

+

fs.mkdir(path, [mode], [callback])#

+

Asynchronous mkdir(2). No arguments other than a possible exception are given +to the completion callback. mode defaults to 0777. + +

+

fs.mkdirSync(path, [mode])#

+

Synchronous mkdir(2). + +

+

fs.readdir(path, [callback])#

+

Asynchronous readdir(3). Reads the contents of a directory. +The callback gets two arguments (err, files) where files is an array of +the names of the files in the directory excluding '.' and '..'. + +

+

fs.readdirSync(path)#

+

Synchronous readdir(3). Returns an array of filenames excluding '.' and +'..'. + +

+

fs.close(fd, [callback])#

+

Asynchronous close(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.closeSync(fd)#

+

Synchronous close(2). + +

+

fs.open(path, flags, [mode], [callback])#

+

Asynchronous file open. See open(2). flags can be: + +

+
    +

  • 'r' - Open file for reading. +An exception occurs if the file does not exist.

    +
    • +

  • 'r+' - Open file for reading and writing. +An exception occurs if the file does not exist.

    +
    • +

  • 'w' - Open file for writing. +The file is created (if it does not exist) or truncated (if it exists).

    +
    • +

  • 'w+' - Open file for reading and writing. +The file is created (if it does not exist) or truncated (if it exists).

    +
    • +

  • 'a' - Open file for appending. +The file is created if it does not exist.

    +
    • +

  • 'a+' - Open file for reading and appending. +The file is created if it does not exist.

    +
    • +
+

mode defaults to 0666. The callback gets two arguments (err, fd). + +

+

fs.openSync(path, flags, [mode])#

+

Synchronous open(2). + +

+

fs.utimes(path, atime, mtime, [callback])#

+

fs.utimesSync(path, atime, mtime)#

+

Change file timestamps of the file referenced by the supplied path. + +

+

fs.futimes(fd, atime, mtime, [callback])#

+

fs.futimesSync(fd, atime, mtime)#

+

Change the file timestamps of a file referenced by the supplied file +descriptor. + +

+

fs.fsync(fd, [callback])#

+

Asynchronous fsync(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.fsyncSync(fd)#

+

Synchronous fsync(2). + +

+

fs.write(fd, buffer, offset, length, position, [callback])#

+

Write buffer to the file specified by fd. + +

+

offset and length determine the part of the buffer to be written. + +

+

position refers to the offset from the beginning of the file where this data +should be written. If position is null, the data will be written at the +current position. +See pwrite(2). + +

+

The callback will be given three arguments (err, written, buffer) where written +specifies how many bytes were written from buffer. + +

+

Note that it is unsafe to use fs.write multiple times on the same file +without waiting for the callback. For this scenario, +fs.createWriteStream is strongly recommended. + +

+

fs.writeSync(fd, buffer, offset, length, position)#

+

Synchronous version of buffer-based fs.write(). Returns the number of bytes +written. + +

+

fs.writeSync(fd, str, position, [encoding])#

+

Synchronous version of string-based fs.write(). encoding defaults to +'utf8'. Returns the number of bytes written. + +

+

fs.read(fd, buffer, offset, length, position, [callback])#

+

Read data from the file specified by fd. + +

+

buffer is the buffer that the data will be written to. + +

+

offset is offset within the buffer where writing will start. + +

+

length is an integer specifying the number of bytes to read. + +

+

position is an integer specifying where to begin reading from in the file. +If position is null, data will be read from the current file position. + +

+

The callback is given the three arguments, (err, bytesRead, buffer). + +

+

fs.readSync(fd, buffer, offset, length, position)#

+

Synchronous version of buffer-based fs.read. Returns the number of +bytesRead. + +

+

fs.readSync(fd, length, position, encoding)#

+

Synchronous version of string-based fs.read. Returns the number of +bytesRead. + +

+

fs.readFile(filename, [encoding], [callback])#

+

Asynchronously reads the entire contents of a file. Example: + +

+
fs.readFile('/etc/passwd', function (err, data) {
+  if (err) throw err;
+  console.log(data);
+});
+

The callback is passed two arguments (err, data), where data is the +contents of the file. + +

+

If no encoding is specified, then the raw buffer is returned. + + +

+

fs.readFileSync(filename, [encoding])#

+

Synchronous version of fs.readFile. Returns the contents of the filename. + +

+

If encoding is specified then this function returns a string. Otherwise it +returns a buffer. + + +

+

fs.writeFile(filename, data, [encoding], [callback])#

+

Asynchronously writes data to a file, replacing the file if it already exists. +data can be a string or a buffer. The encoding argument is ignored if +data is a buffer. It defaults to 'utf8'. + +

+

Example: + +

+
fs.writeFile('message.txt', 'Hello Node', function (err) {
+  if (err) throw err;
+  console.log('It\'s saved!');
+});
+

fs.writeFileSync(filename, data, [encoding])#

+

The synchronous version of fs.writeFile. + +

+

fs.watchFile(filename, [options], listener)#

+
Stability: 2 - Unstable.  Use fs.watch instead, if available.
+

Watch for changes on filename. The callback listener will be called each +time the file is accessed. + +

+

The second argument is optional. The options if provided should be an object +containing two members a boolean, persistent, and interval. persistent +indicates whether the process should continue to run as long as files are +being watched. interval indicates how often the target should be polled, +in milliseconds. (On Linux systems with inotify, interval is ignored.) The +default is { persistent: true, interval: 0 }. + +

+

The listener gets two arguments the current stat object and the previous +stat object: + +

+
fs.watchFile('message.text', function (curr, prev) {
+  console.log('the current mtime is: ' + curr.mtime);
+  console.log('the previous mtime was: ' + prev.mtime);
+});
+

These stat objects are instances of fs.Stat. + +

+

If you want to be notified when the file was modified, not just accessed +you need to compare curr.mtime and prev.mtime. + + +

+

fs.unwatchFile(filename)#

+
Stability: 2 - Unstable.  Use fs.watch instead, if available.
+

Stop watching for changes on filename. + +

+

fs.watch(filename, [options], listener)#

+
Stability: 2 - Unstable.  Not available on all platforms.
+

Watch for changes on filename, where filename is either a file or a +directory. The returned object is a fs.FSWatcher. + +

+

The second argument is optional. The options if provided should be an object +containing a boolean member persistent, which indicates whether the process +should continue to run as long as files are being watched. The default is +{ persistent: true }. + +

+

The listener callback gets two arguments (event, filename). event is either +'rename' or 'change', and filename is the name of the file which triggered +the event. + +

+

Caveats#

+ + +

The fs.watch API is not 100% consistent across platforms, and is +unavailable in some situations. + +

+

Availability#

+ + +

This feature depends on the underlying operating system providing a way +to be notified of filesystem changes. + +

+
    +
  • On Linux systems, this uses inotify.
    • +
  • On BSD systems (including OS X), this uses kqueue.
    • +
  • On SunOS systems (including Solaris and SmartOS), this uses event ports.
    • +
  • On Windows systems, this feature depends on ReadDirectoryChangesW.
    • +
+

If the underlying functionality is not available for some reason, then +fs.watch will not be able to function. You can still use +fs.watchFile, which uses stat polling, but it is slower and less +reliable. + +

+

Filename Argument#

+ + +

Providing filename argument in the callback is not supported +on every platform (currently it's only supported on Linux and Windows). Even +on supported platforms filename is not always guaranteed to be provided. +Therefore, don't assume that filename argument is always provided in the +callback, and have some fallback logic if it is null. + +

+
fs.watch('somedir', function (event, filename) {
+  console.log('event is: ' + event);
+  if (filename) {
+    console.log('filename provided: ' + filename);
+  } else {
+    console.log('filename not provided');
+  }
+});
+

Class: fs.Stats#

+

Objects returned from fs.stat(), fs.lstat() and fs.fstat() and their +synchronous counterparts are of this type. + +

+
    +
  • stats.isFile()
    • +
  • stats.isDirectory()
    • +
  • stats.isBlockDevice()
    • +
  • stats.isCharacterDevice()
    • +
  • stats.isSymbolicLink() (only valid with fs.lstat())
    • +
  • stats.isFIFO()
    • +
  • stats.isSocket()
    • +
+

For a regular file util.inspect(stats) would return a string very +similar to this: + +

+
{ dev: 2114,
+  ino: 48064969,
+  mode: 33188,
+  nlink: 1,
+  uid: 85,
+  gid: 100,
+  rdev: 0,
+  size: 527,
+  blksize: 4096,
+  blocks: 8,
+  atime: Mon, 10 Oct 2011 23:24:11 GMT,
+  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
+  ctime: Mon, 10 Oct 2011 23:24:11 GMT }
+

Please note that atime, mtime and ctime are instances +of Date object and to compare the values of +these objects you should use appropriate methods. For most +general uses getTime() will return +the number of milliseconds elapsed since 1 January 1970 +00:00:00 UTC and this integer should be sufficient for +any comparison, however there additional methods which can +be used for displaying fuzzy information. More details can +be found in the MDN JavaScript Reference page. + +

+

fs.createReadStream(path, [options])#

+

Returns a new ReadStream object (See Readable Stream). + +

+

options is an object with the following defaults: + +

+
{ flags: 'r',
+  encoding: null,
+  fd: null,
+  mode: 0666,
+  bufferSize: 64 * 1024
+}
+

options can include start and end values to read a range of bytes from +the file instead of the entire file. Both start and end are inclusive and +start at 0. + +

+

An example to read the last 10 bytes of a file which is 100 bytes long: + +

+
fs.createReadStream('sample.txt', {start: 90, end: 99});
+

Class: fs.ReadStream#

+

ReadStream is a Readable Stream. + +

+

Event: 'open'#

+
    +
  • fd Integer file descriptor used by the ReadStream.
    • +
+

Emitted when the ReadStream's file is opened. + + +

+

fs.createWriteStream(path, [options])#

+

Returns a new WriteStream object (See Writable Stream). + +

+

options is an object with the following defaults: + +

+
{ flags: 'w',
+  encoding: null,
+  mode: 0666 }
+

options may also include a start option to allow writing data at +some position past the beginning of the file. Modifying a file rather +than replacing it may require a flags mode of r+ rather than the +default mode w. + +

+

fs.WriteStream#

+

WriteStream is a Writable Stream. + +

+

Event: 'open'#

+
    +
  • fd Integer file descriptor used by the ReadStream.
    • +
+

Emitted when the WriteStream's file is opened. + +

+

file.bytesWritten#

+

The number of bytes written so far. Does not include data that is still queued +for writing. + +

+

Class: fs.FSWatcher#

+

Objects returned from fs.watch() are of this type. + +

+

watcher.close()#

+

Stop watching for changes on the given fs.FSWatcher. + +

+

Event: 'change'#

+
    +
  • event String The type of fs change
    • +
  • filename String The filename that changed (if relevant/available)
    • +
+

Emitted when something changes in a watched directory or file. +See more details in fs.watch. + +

+

Event: 'error'#

+
    +
  • error Error object
    • +
+

Emitted when an error occurs. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/process.html @@ -0,0 +1,450 @@ + + + + + process Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

process#

+ + +

The process object is a global object and can be accessed from anywhere. +It is an instance of EventEmitter. + + +

+

Event: 'exit'#

+

Emitted when the process is about to exit. This is a good hook to perform +constant time checks of the module's state (like for unit tests). The main +event loop will no longer be run after the 'exit' callback finishes, so +timers may not be scheduled. + +

+

Example of listening for exit: + +

+
process.on('exit', function () {
+  process.nextTick(function () {
+   console.log('This will not run');
+  });
+  console.log('About to exit.');
+});
+

Event: 'uncaughtException'#

+

Emitted when an exception bubbles all the way back to the event loop. If a +listener is added for this exception, the default action (which is to print +a stack trace and exit) will not occur. + +

+

Example of listening for uncaughtException: + +

+
process.on('uncaughtException', function (err) {
+  console.log('Caught exception: ' + err);
+});
+
+setTimeout(function () {
+  console.log('This will still run.');
+}, 500);
+
+// Intentionally cause an exception, but don't catch it.
+nonexistentFunc();
+console.log('This will not run.');
+

Note that uncaughtException is a very crude mechanism for exception +handling. Using try / catch in your program will give you more control over +your program's flow. Especially for server programs that are designed to +stay running forever, uncaughtException can be a useful safety mechanism. + + +

+

Signal Events#

+ + + +

Emitted when the processes receives a signal. See sigaction(2) for a list of +standard POSIX signal names such as SIGINT, SIGUSR1, etc. + +

+

Example of listening for SIGINT: + +

+
// Start reading from stdin so we don't exit.
+process.stdin.resume();
+
+process.on('SIGINT', function () {
+  console.log('Got SIGINT.  Press Control-D to exit.');
+});
+

An easy way to send the SIGINT signal is with Control-C in most terminal +programs. + + +

+

process.stdout#

+

A Writable Stream to stdout. + +

+

Example: the definition of console.log + +

+
console.log = function (d) {
+  process.stdout.write(d + '\n');
+};
+

process.stderr and process.stdout are unlike other streams in Node in +that writes to them are usually blocking. They are blocking in the case +that they refer to regular files or TTY file descriptors. In the case they +refer to pipes, they are non-blocking like other streams. + + +

+

process.stderr#

+

A writable stream to stderr. + +

+

process.stderr and process.stdout are unlike other streams in Node in +that writes to them are usually blocking. They are blocking in the case +that they refer to regular files or TTY file descriptors. In the case they +refer to pipes, they are non-blocking like other streams. + + +

+

process.stdin#

+

A Readable Stream for stdin. The stdin stream is paused by default, so one +must call process.stdin.resume() to read from it. + +

+

Example of opening standard input and listening for both events: + +

+
process.stdin.resume();
+process.stdin.setEncoding('utf8');
+
+process.stdin.on('data', function (chunk) {
+  process.stdout.write('data: ' + chunk);
+});
+
+process.stdin.on('end', function () {
+  process.stdout.write('end');
+});
+

process.argv#

+

An array containing the command line arguments. The first element will be +'node', the second element will be the name of the JavaScript file. The +next elements will be any additional command line arguments. + +

+
// print process.argv
+process.argv.forEach(function (val, index, array) {
+  console.log(index + ': ' + val);
+});
+

This will generate: + +

+
$ node process-2.js one two=three four
+0: node
+1: /Users/mjr/work/node/process-2.js
+2: one
+3: two=three
+4: four
+

process.execPath#

+

This is the absolute pathname of the executable that started the process. + +

+

Example: + +

+
/usr/local/bin/node
+

process.chdir(directory)#

+

Changes the current working directory of the process or throws an exception if that fails. + +

+
console.log('Starting directory: ' + process.cwd());
+try {
+  process.chdir('/tmp');
+  console.log('New directory: ' + process.cwd());
+}
+catch (err) {
+  console.log('chdir: ' + err);
+}
+

process.cwd()#

+

Returns the current working directory of the process. + +

+
console.log('Current directory: ' + process.cwd());
+

process.env#

+

An object containing the user environment. See environ(7). + + +

+

process.exit([code])#

+

Ends the process with the specified code. If omitted, exit uses the +'success' code 0. + +

+

To exit with a 'failure' code: + +

+
process.exit(1);
+

The shell that executed node should see the exit code as 1. + + +

+

process.getgid()#

+

Gets the group identity of the process. (See getgid(2).) +This is the numerical group id, not the group name. + +

+
console.log('Current gid: ' + process.getgid());
+

process.setgid(id)#

+

Sets the group identity of the process. (See setgid(2).) This accepts either +a numerical ID or a groupname string. If a groupname is specified, this method +blocks while resolving it to a numerical ID. + +

+
console.log('Current gid: ' + process.getgid());
+try {
+  process.setgid(501);
+  console.log('New gid: ' + process.getgid());
+}
+catch (err) {
+  console.log('Failed to set gid: ' + err);
+}
+

process.getuid()#

+

Gets the user identity of the process. (See getuid(2).) +This is the numerical userid, not the username. + +

+
console.log('Current uid: ' + process.getuid());
+

process.setuid(id)#

+

Sets the user identity of the process. (See setuid(2).) This accepts either +a numerical ID or a username string. If a username is specified, this method +blocks while resolving it to a numerical ID. + +

+
console.log('Current uid: ' + process.getuid());
+try {
+  process.setuid(501);
+  console.log('New uid: ' + process.getuid());
+}
+catch (err) {
+  console.log('Failed to set uid: ' + err);
+}
+

process.version#

+

A compiled-in property that exposes NODE_VERSION. + +

+
console.log('Version: ' + process.version);
+

process.versions#

+

A property exposing version strings of node and its dependencies. + +

+
console.log(process.versions);
+

Will output: + +

+
{ node: '0.4.12',
+  v8: '3.1.8.26',
+  ares: '1.7.4',
+  ev: '4.4',
+  openssl: '1.0.0e-fips' }
+

process.installPrefix#

+

A compiled-in property that exposes NODE_PREFIX. + +

+
console.log('Prefix: ' + process.installPrefix);
+

process.kill(pid, [signal])#

+

Send a signal to a process. pid is the process id and signal is the +string describing the signal to send. Signal names are strings like +'SIGINT' or 'SIGUSR1'. If omitted, the signal will be 'SIGTERM'. +See kill(2) for more information. + +

+

Note that just because the name of this function is process.kill, it is +really just a signal sender, like the kill system call. The signal sent +may do something other than kill the target process. + +

+

Example of sending a signal to yourself: + +

+
process.on('SIGHUP', function () {
+  console.log('Got SIGHUP signal.');
+});
+
+setTimeout(function () {
+  console.log('Exiting.');
+  process.exit(0);
+}, 100);
+
+process.kill(process.pid, 'SIGHUP');
+

process.pid#

+

The PID of the process. + +

+
console.log('This process is pid ' + process.pid);
+

process.title#

+

Getter/setter to set what is displayed in 'ps'. + + +

+

process.arch#

+

What processor architecture you're running on: 'arm', 'ia32', or 'x64'. + +

+
console.log('This processor architecture is ' + process.arch);
+

process.platform#

+

What platform you're running on. 'linux2', 'darwin', etc. + +

+
console.log('This platform is ' + process.platform);
+

process.memoryUsage()#

+

Returns an object describing the memory usage of the Node process +measured in bytes. + +

+
var util = require('util');
+
+console.log(util.inspect(process.memoryUsage()));
+

This will generate: + +

+
{ rss: 4935680,
+  heapTotal: 1826816,
+  heapUsed: 650472 }
+

heapTotal and heapUsed refer to V8's memory usage. + + +

+

process.nextTick(callback)#

+

On the next loop around the event loop call this callback. +This is not a simple alias to setTimeout(fn, 0), it's much more +efficient. + +

+
process.nextTick(function () {
+  console.log('nextTick callback');
+});
+

process.umask([mask])#

+

Sets or reads the process's file mode creation mask. Child processes inherit +the mask from the parent process. Returns the old mask if mask argument is +given, otherwise returns the current mask. + +

+
var oldmask, newmask = 0644;
+
+oldmask = process.umask(newmask);
+console.log('Changed umask from: ' + oldmask.toString(8) +
+            ' to ' + newmask.toString(8));
+

process.uptime()#

+

Number of seconds Node has been running. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/cluster.json @@ -0,0 +1,48 @@ +{ + "source": "doc/api/cluster.markdown", + "modules": [ + { + "textRaw": "Cluster", + "name": "cluster", + "stability": 1, + "stabilityText": "Experimental - Drastic changes in future versions", + "desc": "

A single instance of Node runs in a single thread. To take advantage of\nmulti-core systems the user will sometimes want to launch a cluster of Node\nprocesses to handle the load.\n\n

\n

The cluster module allows you to easily create a network of processes that\nall share server ports.\n\n

\n
var cluster = require('cluster');\nvar http = require('http');\nvar numCPUs = require('os').cpus().length;\n\nif (cluster.isMaster) {\n  // Fork workers.\n  for (var i = 0; i < numCPUs; i++) {\n    cluster.fork();\n  }\n\n  cluster.on('death', function(worker) {\n    console.log('worker ' + worker.pid + ' died');\n  });\n} else {\n  // Worker processes have a http server.\n  http.Server(function(req, res) {\n    res.writeHead(200);\n    res.end("hello world\\n");\n  }).listen(8000);\n}
\n

Running node will now share port 8000 between the workers:\n\n

\n
% node server.js\nWorker 2438 online\nWorker 2437 online
\n

The difference between cluster.fork() and child_process.fork() is simply\nthat cluster allows TCP servers to be shared between workers. cluster.fork\nis implemented on top of child_process.fork. The message passing API that\nis available with child_process.fork is available with cluster as well.\nAs an example, here is a cluster which keeps count of the number of requests\nin the master process via message passing:\n\n

\n
var cluster = require('cluster');\nvar http = require('http');\nvar numReqs = 0;\n\nif (cluster.isMaster) {\n  // Fork workers.\n  for (var i = 0; i < 2; i++) {\n    var worker = cluster.fork();\n\n    worker.on('message', function(msg) {\n      if (msg.cmd && msg.cmd == 'notifyRequest') {\n        numReqs++;\n      }\n    });\n  }\n\n  setInterval(function() {\n    console.log("numReqs =", numReqs);\n  }, 1000);\n} else {\n  // Worker processes have a http server.\n  http.Server(function(req, res) {\n    res.writeHead(200);\n    res.end("hello world\\n");\n    // Send message to master process\n    process.send({ cmd: 'notifyRequest' });\n  }).listen(8000);\n}
\n", + "methods": [ + { + "textRaw": "cluster.fork()", + "type": "method", + "name": "fork", + "desc": "

Spawn a new worker process. This can only be called from the master process.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "properties": [ + { + "textRaw": "cluster.isMaster", + "name": "isMaster", + "desc": "

Boolean flags to determine if the current process is a master or a worker\nprocess in a cluster. A process isMaster if process.env.NODE_WORKER_ID\nis undefined.\n\n

\n" + }, + { + "textRaw": "cluster.isWorker", + "name": "isWorker", + "desc": "

Boolean flags to determine if the current process is a master or a worker\nprocess in a cluster. A process isMaster if process.env.NODE_WORKER_ID\nis undefined.\n\n

\n" + } + ], + "events": [ + { + "textRaw": "Event: 'death'", + "type": "event", + "name": "death", + "desc": "

When any of the workers die the cluster module will emit the 'death' event.\nThis can be used to restart the worker by calling fork() again.\n\n

\n
cluster.on('death', function(worker) {\n  console.log('worker ' + worker.pid + ' died. restart...');\n  cluster.fork();\n});
\n

Different techniques can be used to restart the worker depending on the\napplication.\n

\n", + "params": [] + } + ], + "type": "module", + "displayName": "Cluster" + } + ] +} --- /dev/null +++ b/doc/api/repl.json @@ -0,0 +1,54 @@ +{ + "source": "doc/api/repl.markdown", + "modules": [ + { + "textRaw": "REPL", + "name": "repl", + "desc": "

A Read-Eval-Print-Loop (REPL) is available both as a standalone program and easily\nincludable in other programs. REPL provides a way to interactively run\nJavaScript and see the results. It can be used for debugging, testing, or\njust trying things out.\n\n

\n

By executing node without any arguments from the command-line you will be\ndropped into the REPL. It has simplistic emacs line-editing.\n\n

\n
mjr:~$ node\nType '.help' for options.\n> a = [ 1, 2, 3];\n[ 1, 2, 3 ]\n> a.forEach(function (v) {\n...   console.log(v);\n...   });\n1\n2\n3
\n

For advanced line-editors, start node with the environmental variable NODE_NO_READLINE=1.\nThis will start the REPL in canonical terminal settings which will allow you to use with rlwrap.\n\n

\n

For example, you could add this to your bashrc file:\n\n

\n
alias node="env NODE_NO_READLINE=1 rlwrap node"
\n", + "methods": [ + { + "textRaw": "repl.start([prompt], [stream], [eval], [useGlobal], [ignoreUndefined])", + "type": "method", + "name": "start", + "desc": "

Starts a REPL with prompt as the prompt and stream for all I/O. prompt\nis optional and defaults to > . stream is optional and defaults to\nprocess.stdin. eval is optional too and defaults to async wrapper for\neval().\n\n

\n

If useGlobal is set to true, then the repl will use the global object,\ninstead of running scripts in a separate context. Defaults to false.\n\n

\n

If ignoreUndefined is set to true, then the repl will not output return value\nof command if it's undefined. Defaults to false.\n\n

\n

You can use your own eval function if it has following signature:\n\n

\n
function eval(cmd, callback) {\n  callback(null, result);\n}
\n

Multiple REPLs may be started against the same running instance of node. Each\nwill share the same global object but will have unique I/O.\n\n

\n

Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:\n\n

\n
var net = require("net"),\n    repl = require("repl");\n\nconnections = 0;\n\nrepl.start("node via stdin> ");\n\nnet.createServer(function (socket) {\n  connections += 1;\n  repl.start("node via Unix socket> ", socket);\n}).listen("/tmp/node-repl-sock");\n\nnet.createServer(function (socket) {\n  connections += 1;\n  repl.start("node via TCP socket> ", socket);\n}).listen(5001);
\n

Running this program from the command line will start a REPL on stdin. Other\nREPL clients may connect through the Unix socket or TCP socket. telnet is useful\nfor connecting to TCP sockets, and socat can be used to connect to both Unix and\nTCP sockets.\n\n

\n

By starting a REPL from a Unix socket-based server instead of stdin, you can\nconnect to a long-running node process without restarting it.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "prompt", + "optional": true + }, + { + "name": "stream", + "optional": true + }, + { + "name": "eval", + "optional": true + }, + { + "name": "useGlobal", + "optional": true + }, + { + "name": "ignoreUndefined", + "optional": true + } + ] + } + ] + } + ], + "miscs": [ + { + "textRaw": "REPL Features", + "name": "REPL Features", + "type": "misc", + "desc": "

Inside the REPL, Control+D will exit. Multi-line expressions can be input.\nTab completion is supported for both global and local variables.\n\n

\n

The special variable _ (underscore) contains the result of the last expression.\n\n

\n
> [ "a", "b", "c" ]\n[ 'a', 'b', 'c' ]\n> _.length\n3\n> _ += 1\n4
\n

The REPL provides access to any variables in the global scope. You can expose\na variable to the REPL explicitly by assigning it to the context object\nassociated with each REPLServer. For example:\n\n

\n
// repl_test.js\nvar repl = require("repl"),\n    msg = "message";\n\nrepl.start().context.m = msg;
\n

Things in the context object appear as local within the REPL:\n\n

\n
mjr:~$ node repl_test.js\n> m\n'message'
\n

There are a few special REPL commands:\n\n

\n
    \n
  • .break - While inputting a multi-line expression, sometimes you get lost\nor just don't care about completing it. .break will start over.
    • \n
  • .clear - Resets the context object to an empty object and clears any\nmulti-line expression.
    • \n
  • .exit - Close the I/O stream, which will cause the REPL to exit.
    • \n
  • .help - Show this list of special commands.
    • \n
  • .save - Save the current REPL session to a file
    \n

    .save ./file/to/save.js

    \n
    \n
    • \n
  • .load - Load a file into the current REPL session.
    \n

    .load ./file/to/load.js

    \n
    \n
    • \n
\n

The following key combinations in the REPL have these special effects:\n\n

\n
    \n
  • <ctrl>C - Similar to the .break keyword. Terminates the current\ncommand. Press twice on a blank line to forcibly exit.
    • \n
  • <ctrl>D - Similar to the .exit keyword.
    • \n
\n" + } + ], + "type": "module", + "displayName": "REPL" + } + ] +} --- /dev/null +++ b/doc/api/url.json @@ -0,0 +1,72 @@ +{ + "source": "doc/api/url.markdown", + "modules": [ + { + "textRaw": "URL", + "name": "url", + "stability": 3, + "stabilityText": "Stable", + "desc": "

This module has utilities for URL resolution and parsing.\nCall require('url') to use it.\n\n

\n

Parsed URL objects have some or all of the following fields, depending on\nwhether or not they exist in the URL string. Any parts that are not in the URL\nstring will not be in the parsed object. Examples are shown for the URL\n\n

\n

'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'\n\n

\n
    \n

  • href: The full URL that was originally parsed. Both the protocol and host are lowercased.

    \n

    Example: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

    \n
    • \n

  • protocol: The request protocol, lowercased.

    \n

    Example: 'http:'

    \n
    • \n

  • host: The full lowercased host portion of the URL, including port\ninformation.

    \n

    Example: 'host.com:8080'

    \n
    • \n

  • auth: The authentication information portion of a URL.

    \n

    Example: 'user:pass'

    \n
    • \n

  • hostname: Just the lowercased hostname portion of the host.

    \n

    Example: 'host.com'

    \n
    • \n

  • port: The port number portion of the host.

    \n

    Example: '8080'

    \n
    • \n

  • pathname: The path section of the URL, that comes after the host and\nbefore the query, including the initial slash if present.

    \n

    Example: '/p/a/t/h'

    \n
    • \n

  • search: The 'query string' portion of the URL, including the leading\nquestion mark.

    \n

    Example: '?query=string'

    \n
    • \n

  • path: Concatenation of pathname and search.

    \n

    Example: '/p/a/t/h?query=string'

    \n
    • \n

  • query: Either the 'params' portion of the query string, or a\nquerystring-parsed object.

    \n

    Example: 'query=string' or {'query':'string'}

    \n
    • \n

  • hash: The 'fragment' portion of the URL including the pound-sign.

    \n

    Example: '#hash'

    \n
    • \n
\n

The following methods are provided by the URL module:\n\n

\n", + "methods": [ + { + "textRaw": "url.parse(urlStr, [parseQueryString], [slashesDenoteHost])", + "type": "method", + "name": "parse", + "desc": "

Take a URL string, and return an object.\n\n

\n

Pass true as the second argument to also parse\nthe query string using the querystring module.\nDefaults to false.\n\n

\n

Pass true as the third argument to treat //foo/bar as\n{ host: 'foo', pathname: '/bar' } rather than\n{ pathname: '//foo/bar' }. Defaults to false.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "urlStr" + }, + { + "name": "parseQueryString", + "optional": true + }, + { + "name": "slashesDenoteHost", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "url.format(urlObj)", + "type": "method", + "name": "format", + "desc": "

Take a parsed URL object, and return a formatted URL string.\n\n

\n
    \n
  • href will be ignored.
    • \n
  • protocolis treated the same with or without the trailing : (colon).
      \n
    • The protocols http, https, ftp, gopher, file will be\npostfixed with :// (colon-slash-slash).
      • \n
    • All other protocols mailto, xmpp, aim, sftp, foo, etc will\nbe postfixed with : (colon)
      • \n
    \n
    • \n
  • auth will be used if present.
    • \n
  • hostname will only be used if host is absent.
    • \n
  • port will only be used if host is absent.
    • \n
  • host will be used in place of auth, hostname, and port
    • \n
  • pathname is treated the same with or without the leading / (slash)
    • \n
  • search will be used in place of query
    • \n
  • query (object; see querystring) will only be used if search is absent.
    • \n
  • search is treated the same with or without the leading ? (question mark)
    • \n
  • hash is treated the same with or without the leading # (pound sign, anchor)
    • \n
\n", + "signatures": [ + { + "params": [ + { + "name": "urlObj" + } + ] + } + ] + }, + { + "textRaw": "url.resolve(from, to)", + "type": "method", + "name": "resolve", + "desc": "

Take a base URL, and a href URL, and resolve them as a browser would for\nan anchor tag.\n

\n", + "signatures": [ + { + "params": [ + { + "name": "from" + }, + { + "name": "to" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "URL" + } + ] +} --- /dev/null +++ b/doc/api/stdio.html @@ -0,0 +1,159 @@ + + + + + console Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

console#

+
Stability: 4 - API Frozen
+
    +
  • {Object}
    • +
+ + +

For printing to stdout and stderr. Similar to the console object functions +provided by most web browsers, here the output is sent to stdout or stderr. + + +

+

console.log()#

+

Prints to stdout with newline. This function can take multiple arguments in a +printf()-like way. Example: + +

+
console.log('count: %d', count);
+

If formatting elements are not found in the first string then util.inspect +is used on each argument. +See util.format() for more information. + +

+

console.info()#

+

Same as console.log. + +

+

console.warn()#

+

console.error()#

+

Same as console.log but prints to stderr. + +

+

console.dir(obj)#

+

Uses util.inspect on obj and prints resulting string to stderr. + +

+

console.time(label)#

+

Mark a time. + + +

+

console.timeEnd(label)#

+

Finish timer, record output. Example + +

+
console.time('100-elements');
+for (var i = 0; i < 100; i++) {
+  ;
+}
+console.timeEnd('100-elements');
+

console.trace()#

+

Print a stack trace to stderr of the current position. + +

+

console.assert()#

+

Same as assert.ok(). + +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/https.json @@ -0,0 +1,92 @@ +{ + "source": "doc/api/https.markdown", + "modules": [ + { + "textRaw": "HTTPS", + "name": "https", + "stability": 3, + "stabilityText": "Stable", + "desc": "

HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a\nseparate module.\n\n

\n", + "classes": [ + { + "textRaw": "Class: https.Server", + "type": "class", + "name": "https.Server", + "desc": "

This class is a subclass of tls.Server and emits events same as\nhttp.Server. See http.Server for more information.\n\n

\n" + }, + { + "textRaw": "Class: https.Agent", + "type": "class", + "name": "https.Agent", + "desc": "

An Agent object for HTTPS similar to http.Agent.\nSee https.request() for more information.\n\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "https.createServer(options, [requestListener])", + "type": "method", + "name": "createServer", + "desc": "

Returns a new HTTPS web server object. The options is similar to\ntls.createServer(). The requestListener is a function which is\nautomatically added to the 'request' event.\n\n

\n

Example:\n\n

\n
// curl -k https://localhost:8000/\nvar https = require('https');\nvar fs = require('fs');\n\nvar options = {\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\n\nhttps.createServer(options, function (req, res) {\n  res.writeHead(200);\n  res.end("hello world\\n");\n}).listen(8000);
\n

Or\n\n

\n
var https = require('https');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('server.pfx')\n};\n\nhttps.createServer(options, function (req, res) {\n  res.writeHead(200);\n  res.end("hello world\\n");\n}).listen(8000);
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "requestListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "https.request(options, callback)", + "type": "method", + "name": "request", + "desc": "

Makes a request to a secure web server.\nAll options from http.request() are valid.\n\n

\n

Example:\n\n

\n
var https = require('https');\n\nvar options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET'\n};\n\nvar req = https.request(options, function(res) {\n  console.log("statusCode: ", res.statusCode);\n  console.log("headers: ", res.headers);\n\n  res.on('data', function(d) {\n    process.stdout.write(d);\n  });\n});\nreq.end();\n\nreq.on('error', function(e) {\n  console.error(e);\n});
\n

The options argument has the following options\n\n

\n
    \n
  • host: IP or domain of host to make request to. Defaults to 'localhost'.
    • \n
  • port: port of host to request to. Defaults to 443.
    • \n
  • path: Path to request. Default '/'.
    • \n

  • method: HTTP request method. Default 'GET'.

    \n
    • \n

  • host: A domain name or IP address of the server to issue the request to.\nDefaults to 'localhost'.

    \n
    • \n
  • hostname: To support url.parse() hostname is preferred over host
    • \n
  • port: Port of remote server. Defaults to 443.
    • \n
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • \n
  • path: Request path. Defaults to '/'. Should include query string if any.\nE.G. '/index.html?page=12'
    • \n
  • headers: An object containing request headers.
    • \n
  • auth: Basic authentication i.e. 'user:password' to compute an\nAuthorization header.
    • \n
  • agent: Controls Agent behavior. When an Agent is\nused request will default to Connection: keep-alive. Possible values:
      \n
    • undefined (default): use globalAgent for this\nhost and port.
      • \n
    • Agent object: explicitly use the passed in Agent.
      • \n
    • false: opts out of connection pooling with an Agent, defaults request to\nConnection: close.
      • \n
    \n
    • \n
\n

The following options from tls.connect() can also be\nspecified. However, a globalAgent silently ignores these.\n\n

\n
    \n
  • pfx: Certificate, Private key and CA certificates to use for SSL. Default null.
    • \n
  • key: Private key to use for SSL. Default null.
    • \n
  • passphrase: A string of passphrase for the private key or pfx. Default null.
    • \n
  • cert: Public x509 certificate to use. Default null.
    • \n
  • ca: An authority certificate or array of authority certificates to check\nthe remote host against.
    • \n
\n

In order to specify these options, use a custom Agent.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\noptions.agent = new https.Agent(options);\n\nvar req = https.request(options, function(res) {\n  ...\n}
\n

Or does not use an Agent.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),\n  agent: false\n};\n\nvar req = https.request(options, function(res) {\n  ...\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "https.get(options, callback)", + "type": "method", + "name": "get", + "desc": "

Like http.get() but for HTTPS.\n\n

\n

Example:\n\n

\n
var https = require('https');\n\nhttps.get({ host: 'encrypted.google.com', path: '/' }, function(res) {\n  console.log("statusCode: ", res.statusCode);\n  console.log("headers: ", res.headers);\n\n  res.on('data', function(d) {\n    process.stdout.write(d);\n  });\n\n}).on('error', function(e) {\n  console.error(e);\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "callback" + } + ] + } + ] + } + ], + "properties": [ + { + "textRaw": "https.globalAgent", + "name": "globalAgent", + "desc": "

Global instance of https.Agent which is used as the default\nfor all HTTPS client requests.\n

\n" + } + ], + "type": "module", + "displayName": "HTTPS" + } + ] +} --- /dev/null +++ b/doc/api/vm.json @@ -0,0 +1,152 @@ +{ + "source": "doc/api/vm.markdown", + "modules": [ + { + "textRaw": "Executing JavaScript", + "name": "vm", + "stability": 3, + "stabilityText": "Stable", + "desc": "

You can access this module with:\n\n

\n
var vm = require('vm');
\n

JavaScript code can be compiled and run immediately or compiled, saved, and run later.\n\n\n

\n", + "methods": [ + { + "textRaw": "vm.runInThisContext(code, [filename])", + "type": "method", + "name": "runInThisContext", + "desc": "

vm.runInThisContext() compiles code, runs it and returns the result. Running\ncode does not have access to local scope. filename is optional, it's used only\nin stack traces.\n\n

\n

Example of using vm.runInThisContext and eval to run the same code:\n\n

\n
var localVar = 123,\n    usingscript, evaled,\n    vm = require('vm');\n\nusingscript = vm.runInThisContext('localVar = 1;',\n  'myfile.vm');\nconsole.log('localVar: ' + localVar + ', usingscript: ' +\n  usingscript);\nevaled = eval('localVar = 1;');\nconsole.log('localVar: ' + localVar + ', evaled: ' +\n  evaled);\n\n// localVar: 123, usingscript: 1\n// localVar: 1, evaled: 1
\n

vm.runInThisContext does not have access to the local scope, so localVar is unchanged.\neval does have access to the local scope, so localVar is changed.\n\n

\n

In case of syntax error in code, vm.runInThisContext emits the syntax error to stderr\nand throws an exception.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code" + }, + { + "name": "filename", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "vm.runInNewContext(code, [sandbox], [filename])", + "type": "method", + "name": "runInNewContext", + "desc": "

vm.runInNewContext compiles code, then runs it in sandbox and returns the\nresult. Running code does not have access to local scope. The object sandbox\nwill be used as the global object for code.\nsandbox and filename are optional, filename is only used in stack traces.\n\n

\n

Example: compile and execute code that increments a global variable and sets a new one.\nThese globals are contained in the sandbox.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    sandbox = {\n      animal: 'cat',\n      count: 2\n    };\n\nvm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');\nconsole.log(util.inspect(sandbox));\n\n// { animal: 'cat', count: 3, name: 'kitty' }
\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, vm.runInNewContext is quite useful, but safely running untrusted code\nrequires a separate process.\n\n

\n

In case of syntax error in code, vm.runInNewContext emits the syntax error to stderr\nand throws an exception.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code" + }, + { + "name": "sandbox", + "optional": true + }, + { + "name": "filename", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "vm.runInContext(code, context, [filename])", + "type": "method", + "name": "runInContext", + "desc": "

vm.runInContext compiles code, then runs it in context and returns the\nresult. A (V8) context comprises a global object, together with a set of\nbuilt-in objects and functions. Running code does not have access to local scope\nand the global object held within context will be used as the global object\nfor code.\nfilename is optional, it's used only in stack traces.\n\n

\n

Example: compile and execute code in a existing context.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    initSandbox = {\n      animal: 'cat',\n      count: 2\n    },\n    context = vm.createContext(initSandbox);\n\nvm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');\nconsole.log(util.inspect(context));\n\n// { animal: 'cat', count: 3, name: 'CATT' }
\n

Note that createContext will perform a shallow clone of the supplied sandbox object in order to\ninitialise the global object of the freshly constructed context.\n\n

\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, vm.runInContext is quite useful, but safely running untrusted code\nrequires a separate process.\n\n

\n

In case of syntax error in code, vm.runInContext emits the syntax error to stderr\nand throws an exception.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code" + }, + { + "name": "context" + }, + { + "name": "filename", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "vm.createContext([initSandbox])", + "type": "method", + "name": "createContext", + "desc": "

vm.createContext creates a new context which is suitable for use as the 2nd argument of a subsequent\ncall to vm.runInContext. A (V8) context comprises a global object together with a set of\nbuild-in objects and functions. The optional argument initSandbox will be shallow-copied\nto seed the initial contents of the global object used by the context.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "initSandbox", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "vm.createScript(code, [filename])", + "type": "method", + "name": "createScript", + "desc": "

createScript compiles code but does not run it. Instead, it returns a\nvm.Script object representing this compiled code. This script can be run\nlater many times using methods below. The returned script is not bound to any\nglobal object. It is bound before each run, just for that run. filename is\noptional, it's only used in stack traces.\n\n

\n

In case of syntax error in code, createScript prints the syntax error to stderr\nand throws an exception.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code" + }, + { + "name": "filename", + "optional": true + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: Script", + "type": "class", + "name": "Script", + "desc": "

A class for running scripts. Returned by vm.createScript.\n\n

\n", + "methods": [ + { + "textRaw": "script.runInThisContext()", + "type": "method", + "name": "runInThisContext", + "desc": "

Similar to vm.runInThisContext but a method of a precompiled Script object.\nscript.runInThisContext runs the code of script and returns the result.\nRunning code does not have access to local scope, but does have access to the global object\n(v8: in actual context).\n\n

\n

Example of using script.runInThisContext to compile code once and run it multiple times:\n\n

\n
var vm = require('vm');\n\nglobalVar = 0;\n\nvar script = vm.createScript('globalVar += 1', 'myfile.vm');\n\nfor (var i = 0; i < 1000 ; i += 1) {\n  script.runInThisContext();\n}\n\nconsole.log(globalVar);\n\n// 1000
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "script.runInNewContext([sandbox])", + "type": "method", + "name": "runInNewContext", + "desc": "

Similar to vm.runInNewContext a method of a precompiled Script object.\nscript.runInNewContext runs the code of script with sandbox as the global object and returns the result.\nRunning code does not have access to local scope. sandbox is optional.\n\n

\n

Example: compile code that increments a global variable and sets one, then execute this code multiple times.\nThese globals are contained in the sandbox.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    sandbox = {\n      animal: 'cat',\n      count: 2\n    };\n\nvar script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');\n\nfor (var i = 0; i < 10 ; i += 1) {\n  script.runInNewContext(sandbox);\n}\n\nconsole.log(util.inspect(sandbox));\n\n// { animal: 'cat', count: 12, name: 'kitty' }
\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, script.runInNewContext is quite useful, but safely running untrusted code\nrequires a separate process.\n

\n", + "signatures": [ + { + "params": [ + { + "name": "sandbox", + "optional": true + } + ] + } + ] + } + ] + } + ], + "type": "module", + "displayName": "vm" + } + ] +} --- /dev/null +++ b/doc/api/addons.html @@ -0,0 +1,725 @@ + + + + + Addons Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Addons#

+

Addons are dynamically linked shared objects. They can provide glue to C and +C++ libraries. The API (at the moment) is rather complex, involving +knowledge of several libraries: + +

+
    +

  • V8 JavaScript, a C++ library. Used for interfacing with JavaScript: +creating objects, calling functions, etc. Documented mostly in the +v8.h header file (deps/v8/include/v8.h in the Node source tree), +which is also available online.

    +
    • +

  • libuv, C event loop library. Anytime one +needs to wait for a file descriptor to become readable, wait for a timer, or +wait for a signal to received one will need to interface with libuv. That is, +if you perform any I/O, libuv will need to be used.

    +
    • +

  • Internal Node libraries. Most importantly is the node::ObjectWrap +class which you will likely want to derive from.

    +
    • +

  • Others. Look in deps/ for what else is available.

    +
    • +
+

Node statically compiles all its dependencies into the executable. When +compiling your module, you don't need to worry about linking to any of these +libraries. + + +

+

Hello world#

+

To get started let's make a small Addon which is the C++ equivalent of +the following Javascript code: + +

+
exports.hello = function() { return 'world'; };
+

First we create a file hello.cc: + +

+
#include <node.h>
+#include <v8.h>
+
+using namespace v8;
+
+Handle<Value> Method(const Arguments& args) {
+  HandleScope scope;
+  return scope.Close(String::New("world"));
+}
+
+void init(Handle<Object> target) {
+  target->Set(String::NewSymbol("hello"),
+      FunctionTemplate::New(Method)->GetFunction());
+}
+NODE_MODULE(hello, init)
+

Note that all Node addons must export an initialization function: + +

+
void Initialize (Handle<Object> target);
+NODE_MODULE(module_name, Initialize)
+

There is no semi-colon after NODE_MODULE as it's not a function (see node.h). + +

+

The module_name needs to match the filename of the final binary (minus the +.node suffix). + +

+

The source code needs to be built into hello.node, the binary Addon. To +do this we create a file called wscript which is python code and looks +like this: + +

+
srcdir = '.'
+blddir = 'build'
+VERSION = '0.0.1'
+
+def set_options(opt):
+  opt.tool_options('compiler_cxx')
+
+def configure(conf):
+  conf.check_tool('compiler_cxx')
+  conf.check_tool('node_addon')
+
+def build(bld):
+  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
+  obj.target = 'hello'
+  obj.source = 'hello.cc'
+

Running node-waf configure build will create a file +build/default/hello.node which is our Addon. + +

+

node-waf is just WAF, the python-based build system. node-waf is +provided for the ease of users. + +

+

You can now use the binary addon in a Node project hello.js by pointing require to +the recently built module: + +

+
var addon = require('./build/Release/hello');
+
+console.log(addon.hello()); // 'world'
+

Please see patterns below for further information or +

+

https://github.com/pietern/hiredis-node for an example in production. + + +

+

Addon patterns#

+

Below are some addon patterns to help you get started. Consult the online +v8 reference for help with the various v8 +calls, and v8's Embedder's Guide +for an explanation of several concepts used such as handles, scopes, +function templates, etc. + +

+

To compile these examples, create the wscript file below and run +node-waf configure build: + +

+
srcdir = '.'
+blddir = 'build'
+VERSION = '0.0.1'
+
+def set_options(opt):
+  opt.tool_options('compiler_cxx')
+
+def configure(conf):
+  conf.check_tool('compiler_cxx')
+  conf.check_tool('node_addon')
+
+def build(bld):
+  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
+  obj.target = 'addon'
+  obj.source = ['addon.cc']
+

In cases where there is more than one .cc file, simply add the file name to the +obj.source array, e.g.: + +

+
obj.source = ['addon.cc', 'myexample.cc']
+

Function arguments#

+

The following pattern illustrates how to read arguments from JavaScript +function calls and return a result. This is the main and only needed source +addon.cc: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+
+using namespace v8;
+
+Handle<Value> Add(const Arguments& args) {
+  HandleScope scope;
+
+  if (args.Length() < 2) {
+    ThrowException(Exception::TypeError(String::New("Wrong number of arguments")));
+    return scope.Close(Undefined());
+  }
+
+  if (!args[0]->IsNumber() || !args[1]->IsNumber()) {
+    ThrowException(Exception::TypeError(String::New("Wrong arguments")));
+    return scope.Close(Undefined());
+  }
+
+  Local<Number> num = Number::New(args[0]->NumberValue() +
+      args[1]->NumberValue());
+  return scope.Close(num);
+}
+
+void Init(Handle<Object> target) {
+  target->Set(String::NewSymbol("add"),
+      FunctionTemplate::New(Add)->GetFunction());
+}
+
+NODE_MODULE(addon, Init)
+

You can test it with the following JavaScript snippet: + +

+
var addon = require('./build/Release/addon');
+
+console.log( 'This should be eight:', addon.add(3,5) );
+

Callbacks#

+

You can pass JavaScript functions to a C++ function and execute them from +there. Here's addon.cc: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+
+using namespace v8;
+
+Handle<Value> RunCallback(const Arguments& args) {
+  HandleScope scope;
+
+  Local<Function> cb = Local<Function>::Cast(args[0]);
+  const unsigned argc = 1;
+  Local<Value> argv[argc] = { Local<Value>::New(String::New("hello world")) };
+  cb->Call(Context::GetCurrent()->Global(), argc, argv);
+
+  return scope.Close(Undefined());
+}
+
+void Init(Handle<Object> target) {
+  target->Set(String::NewSymbol("runCallback"),
+      FunctionTemplate::New(RunCallback)->GetFunction());
+}
+
+NODE_MODULE(addon, Init)
+

To test it run the following JavaScript snippet: + +

+
var addon = require('./build/Release/addon');
+
+addon.runCallback(function(msg){
+  console.log(msg); // 'hello world'
+});
+

Object factory#

+

You can create and return new objects from within a C++ function with this +addon.cc pattern, which returns an object with property msg that echoes +the string passed to createObject(): + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+
+using namespace v8;
+
+Handle<Value> CreateObject(const Arguments& args) {
+  HandleScope scope;
+
+  Local<Object> obj = Object::New();
+  obj->Set(String::NewSymbol("msg"), args[0]->ToString());
+
+  return scope.Close(obj);
+}
+
+void Init(Handle<Object> target) {
+  target->Set(String::NewSymbol("createObject"),
+      FunctionTemplate::New(CreateObject)->GetFunction());
+}
+
+NODE_MODULE(addon, Init)
+

To test it in JavaScript: + +

+
var addon = require('./build/Release/addon');
+
+var obj1 = addon.createObject('hello');
+var obj2 = addon.createObject('world');
+console.log(obj1.msg+' '+obj2.msg); // 'hello world'
+

Function factory#

+

This pattern illustrates how to create and return a JavaScript function that +wraps a C++ function: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+
+using namespace v8;
+
+Handle<Value> MyFunction(const Arguments& args) {
+  HandleScope scope;
+  return scope.Close(String::New("hello world"));
+}
+
+Handle<Value> CreateFunction(const Arguments& args) {
+  HandleScope scope;
+
+  Local<FunctionTemplate> tpl = FunctionTemplate::New(MyFunction);
+  Local<Function> fn = tpl->GetFunction();
+  fn->SetName(String::NewSymbol("theFunction")); // omit this to make it anonymous
+
+  return scope.Close(fn);
+}
+
+void Init(Handle<Object> target) {
+  target->Set(String::NewSymbol("createFunction"),
+      FunctionTemplate::New(CreateFunction)->GetFunction());
+}
+
+NODE_MODULE(addon, Init)
+

To test: + +

+
var addon = require('./build/Release/addon');
+
+var fn = addon.createFunction();
+console.log(fn()); // 'hello world'
+

Wrapping C++ objects#

+

Here we will create a wrapper for a C++ object/class MyObject that can be +instantiated in JavaScript through the new operator. First prepare the main +module addon.cc: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+void InitAll(Handle<Object> target) {
+  MyObject::Init(target);
+}
+
+NODE_MODULE(addon, InitAll)
+

Then in myobject.h make your wrapper inherit from node::ObjectWrap: + +

+
#ifndef MYOBJECT_H
+#define MYOBJECT_H
+
+#include <node.h>
+
+class MyObject : public node::ObjectWrap {
+ public:
+  static void Init(v8::Handle<v8::Object> target);
+
+ private:
+  MyObject();
+  ~MyObject();
+
+  static v8::Handle<v8::Value> New(const v8::Arguments& args);
+  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);
+  double counter_;
+};
+
+#endif
+

And in myobject.cc implement the various methods that you want to expose. +Here we expose the method plusOne by adding it to the constructor's +prototype: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+MyObject::MyObject() {};
+MyObject::~MyObject() {};
+
+void MyObject::Init(Handle<Object> target) {
+  // Prepare constructor template
+  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
+  tpl->SetClassName(String::NewSymbol("MyObject"));
+  tpl->InstanceTemplate()->SetInternalFieldCount(1);
+  // Prototype
+  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),
+      FunctionTemplate::New(PlusOne)->GetFunction());
+
+  Persistent<Function> constructor = Persistent<Function>::New(tpl->GetFunction());
+  target->Set(String::NewSymbol("MyObject"), constructor);
+}
+
+Handle<Value> MyObject::New(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj = new MyObject();
+  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
+  obj->Wrap(args.This());
+
+  return args.This();
+}
+
+Handle<Value> MyObject::PlusOne(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());
+  obj->counter_ += 1;
+
+  return scope.Close(Number::New(obj->counter_));
+}
+

Test it with: + +

+
var addon = require('./build/Release/addon');
+
+var obj = new addon.MyObject(10);
+console.log( obj.plusOne() ); // 11
+console.log( obj.plusOne() ); // 12
+console.log( obj.plusOne() ); // 13
+

Factory of wrapped objects#

+

This is useful when you want to be able to create native objects without +explicitly instantiating them with the new operator in JavaScript, e.g. + +

+
var obj = addon.createObject();
+// instead of:
+// var obj = new addon.Object();
+

Let's register our createObject method in addon.cc: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+Handle<Value> CreateObject(const Arguments& args) {
+  HandleScope scope;
+  return scope.Close(MyObject::NewInstance(args));
+}
+
+void InitAll(Handle<Object> target) {
+  MyObject::Init();
+
+  target->Set(String::NewSymbol("createObject"),
+      FunctionTemplate::New(CreateObject)->GetFunction());
+}
+
+NODE_MODULE(addon, InitAll)
+

In myobject.h we now introduce the static method NewInstance that takes +care of instantiating the object (i.e. it does the job of new in JavaScript): + +

+
#define BUILDING_NODE_EXTENSION
+#ifndef MYOBJECT_H
+#define MYOBJECT_H
+
+#include <node.h>
+
+class MyObject : public node::ObjectWrap {
+ public:
+  static void Init();
+  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);
+
+ private:
+  MyObject();
+  ~MyObject();
+
+  static v8::Persistent<v8::Function> constructor;
+  static v8::Handle<v8::Value> New(const v8::Arguments& args);
+  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);
+  double counter_;
+};
+
+#endif
+

The implementation is similar to the above in myobject.cc: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+MyObject::MyObject() {};
+MyObject::~MyObject() {};
+
+Persistent<Function> MyObject::constructor;
+
+void MyObject::Init() {
+  // Prepare constructor template
+  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
+  tpl->SetClassName(String::NewSymbol("MyObject"));
+  tpl->InstanceTemplate()->SetInternalFieldCount(1);
+  // Prototype
+  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),
+      FunctionTemplate::New(PlusOne)->GetFunction());
+
+  constructor = Persistent<Function>::New(tpl->GetFunction());
+}
+
+Handle<Value> MyObject::New(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj = new MyObject();
+  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
+  obj->Wrap(args.This());
+
+  return args.This();
+}
+
+Handle<Value> MyObject::NewInstance(const Arguments& args) {
+  HandleScope scope;
+
+  const unsigned argc = 1;
+  Handle<Value> argv[argc] = { args[0] };
+  Local<Object> instance = constructor->NewInstance(argc, argv);
+
+  return scope.Close(instance);
+}
+
+Handle<Value> MyObject::PlusOne(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());
+  obj->counter_ += 1;
+
+  return scope.Close(Number::New(obj->counter_));
+}
+

Test it with: + +

+
var addon = require('./build/Release/addon');
+
+var obj = addon.createObject(10);
+console.log( obj.plusOne() ); // 11
+console.log( obj.plusOne() ); // 12
+console.log( obj.plusOne() ); // 13
+
+var obj2 = addon.createObject(20);
+console.log( obj2.plusOne() ); // 21
+console.log( obj2.plusOne() ); // 22
+console.log( obj2.plusOne() ); // 23
+

Passing wrapped objects around#

+

In addition to wrapping and returning C++ objects, you can pass them around +by unwrapping them with Node's node::ObjectWrap::Unwrap helper function. +In the following addon.cc we introduce a function add() that can take on two +MyObject objects: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+Handle<Value> CreateObject(const Arguments& args) {
+  HandleScope scope;
+  return scope.Close(MyObject::NewInstance(args));
+}
+
+Handle<Value> Add(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(
+      args[0]->ToObject());
+  MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(
+      args[1]->ToObject());
+
+  double sum = obj1->Val() + obj2->Val();
+  return scope.Close(Number::New(sum));
+}
+
+void InitAll(Handle<Object> target) {
+  MyObject::Init();
+
+  target->Set(String::NewSymbol("createObject"),
+      FunctionTemplate::New(CreateObject)->GetFunction());
+
+  target->Set(String::NewSymbol("add"),
+      FunctionTemplate::New(Add)->GetFunction());
+}
+
+NODE_MODULE(addon, InitAll)
+

To make things interesting we introduce a public method in myobject.h so we +can probe private values after unwrapping the object: + +

+
#define BUILDING_NODE_EXTENSION
+#ifndef MYOBJECT_H
+#define MYOBJECT_H
+
+#include <node.h>
+
+class MyObject : public node::ObjectWrap {
+ public:
+  static void Init();
+  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);
+  double Val() const { return val_; }
+
+ private:
+  MyObject();
+  ~MyObject();
+
+  static v8::Persistent<v8::Function> constructor;
+  static v8::Handle<v8::Value> New(const v8::Arguments& args);
+  double val_;
+};
+
+#endif
+

The implementation of myobject.cc is similar as before: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+MyObject::MyObject() {};
+MyObject::~MyObject() {};
+
+Persistent<Function> MyObject::constructor;
+
+void MyObject::Init() {
+  // Prepare constructor template
+  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
+  tpl->SetClassName(String::NewSymbol("MyObject"));
+  tpl->InstanceTemplate()->SetInternalFieldCount(1);
+
+  constructor = Persistent<Function>::New(tpl->GetFunction());
+}
+
+Handle<Value> MyObject::New(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj = new MyObject();
+  obj->val_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
+  obj->Wrap(args.This());
+
+  return args.This();
+}
+
+Handle<Value> MyObject::NewInstance(const Arguments& args) {
+  HandleScope scope;
+
+  const unsigned argc = 1;
+  Handle<Value> argv[argc] = { args[0] };
+  Local<Object> instance = constructor->NewInstance(argc, argv);
+
+  return scope.Close(instance);
+}
+

Test it with: + +

+
var addon = require('./build/Release/addon');
+
+var obj1 = addon.createObject(10);
+var obj2 = addon.createObject(20);
+var result = addon.add(obj1, obj2);
+
+console.log(result); // 30
+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/util.json @@ -0,0 +1,184 @@ +{ + "source": "doc/api/util.markdown", + "modules": [ + { + "textRaw": "util", + "name": "util", + "stability": 5, + "stabilityText": "Locked", + "desc": "

These functions are in the module 'util'. Use require('util') to access\nthem.\n\n\n

\n", + "methods": [ + { + "textRaw": "util.format()", + "type": "method", + "name": "format", + "desc": "

Returns a formatted string using the first argument as a printf-like format.\n\n

\n

The first argument is a string that contains zero or more placeholders.\nEach placeholder is replaced with the converted value from its corresponding\nargument. Supported placeholders are:\n\n

\n
    \n
  • %s - String.
    • \n
  • %d - Number (both integer and float).
    • \n
  • %j - JSON.
    • \n
  • %% - single percent sign ('%'). This does not consume an argument.
    • \n
\n

If the placeholder does not have a corresponding argument, the placeholder is\nnot replaced.\n\n

\n
util.format('%s:%s', 'foo'); // 'foo:%s'
\n

If there are more arguments than placeholders, the extra arguments are\nconverted to strings with util.inspect() and these strings are concatenated,\ndelimited by a space.\n\n

\n
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
\n

If the first argument is not a format string then util.format() returns\na string that is the concatenation of all its arguments separated by spaces.\nEach argument is converted to a string with util.inspect().\n\n

\n
util.format(1, 2, 3); // '1 2 3'
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "util.debug(string)", + "type": "method", + "name": "debug", + "desc": "

A synchronous output function. Will block the process and\noutput string immediately to stderr.\n\n

\n
require('util').debug('message on stderr');
\n", + "signatures": [ + { + "params": [ + { + "name": "string" + } + ] + } + ] + }, + { + "textRaw": "util.log(string)", + "type": "method", + "name": "log", + "desc": "

Output with timestamp on stdout.\n\n

\n
require('util').log('Timestamped message.');
\n", + "signatures": [ + { + "params": [ + { + "name": "string" + } + ] + } + ] + }, + { + "textRaw": "util.inspect(object, [showHidden], [depth], [colors])", + "type": "method", + "name": "inspect", + "desc": "

Return a string representation of object, which is useful for debugging.\n\n

\n

If showHidden is true, then the object's non-enumerable properties will be\nshown too. Defaults to false.\n\n

\n

If depth is provided, it tells inspect how many times to recurse while\nformatting the object. This is useful for inspecting large complicated objects.\n\n

\n

The default is to only recurse twice. To make it recurse indefinitely, pass\nin null for depth.\n\n

\n

If colors is true, the output will be styled with ANSI color codes.\nDefaults to false.\n\n

\n

Example of inspecting all properties of the util object:\n\n

\n
var util = require('util');\n\nconsole.log(util.inspect(util, true, null));
\n", + "signatures": [ + { + "params": [ + { + "name": "object" + }, + { + "name": "showHidden", + "optional": true + }, + { + "name": "depth", + "optional": true + }, + { + "name": "colors", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "util.isArray(object)", + "type": "method", + "name": "isArray", + "desc": "

Returns true if the given "object" is an Array. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isArray([])\n  // true\nutil.isArray(new Array)\n  // true\nutil.isArray({})\n  // false
\n", + "signatures": [ + { + "params": [ + { + "name": "object" + } + ] + } + ] + }, + { + "textRaw": "util.isRegExp(object)", + "type": "method", + "name": "isRegExp", + "desc": "

Returns true if the given "object" is a RegExp. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isRegExp(/some regexp/)\n  // true\nutil.isRegExp(new RegExp('another regexp'))\n  // true\nutil.isRegExp({})\n  // false
\n", + "signatures": [ + { + "params": [ + { + "name": "object" + } + ] + } + ] + }, + { + "textRaw": "util.isDate(object)", + "type": "method", + "name": "isDate", + "desc": "

Returns true if the given "object" is a Date. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isDate(new Date())\n  // true\nutil.isDate(Date())\n  // false (without 'new' returns a String)\nutil.isDate({})\n  // false
\n", + "signatures": [ + { + "params": [ + { + "name": "object" + } + ] + } + ] + }, + { + "textRaw": "util.isError(object)", + "type": "method", + "name": "isError", + "desc": "

Returns true if the given "object" is an Error. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isError(new Error())\n  // true\nutil.isError(new TypeError())\n  // true\nutil.isError({ name: 'Error', message: 'an error occurred' })\n  // false
\n", + "signatures": [ + { + "params": [ + { + "name": "object" + } + ] + } + ] + }, + { + "textRaw": "util.pump(readableStream, writableStream, [callback])", + "type": "method", + "name": "pump", + "desc": "

Experimental\n\n

\n

Read the data from readableStream and send it to the writableStream.\nWhen writableStream.write(data) returns false readableStream will be\npaused until the drain event occurs on the writableStream. callback gets\nan error as its only argument and is called when writableStream is closed or\nwhen an error occurs.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "readableStream" + }, + { + "name": "writableStream" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "util.inherits(constructor, superConstructor)", + "type": "method", + "name": "inherits", + "desc": "

Inherit the prototype methods from one\nconstructor\ninto another. The prototype of constructor will be set to a new\nobject created from superConstructor.\n\n

\n

As an additional convenience, superConstructor will be accessible\nthrough the constructor.super_ property.\n\n

\n
var util = require("util");\nvar events = require("events");\n\nfunction MyStream() {\n    events.EventEmitter.call(this);\n}\n\nutil.inherits(MyStream, events.EventEmitter);\n\nMyStream.prototype.write = function(data) {\n    this.emit("data", data);\n}\n\nvar stream = new MyStream();\n\nconsole.log(stream instanceof events.EventEmitter); // true\nconsole.log(MyStream.super_ === events.EventEmitter); // true\n\nstream.on("data", function(data) {\n    console.log('Received data: "' + data + '"');\n})\nstream.write("It works!"); // Received data: "It works!"
\n", + "signatures": [ + { + "params": [ + { + "name": "constructor" + }, + { + "name": "superConstructor" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "util" + } + ] +} --- /dev/null +++ b/doc/api/querystring.json @@ -0,0 +1,74 @@ +{ + "source": "doc/api/querystring.markdown", + "modules": [ + { + "textRaw": "Query String", + "name": "querystring", + "stability": 3, + "stabilityText": "Stable", + "desc": "

This module provides utilities for dealing with query strings.\nIt provides the following methods:\n\n

\n", + "methods": [ + { + "textRaw": "querystring.stringify(obj, [sep], [eq])", + "type": "method", + "name": "stringify", + "desc": "

Serialize an object to a query string.\nOptionally override the default separator ('&') and assignment ('=')\ncharacters.\n\n

\n

Example:\n\n

\n
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })\n// returns\n'foo=bar&baz=qux&baz=quux&corge='\n\nquerystring.stringify({foo: 'bar', baz: 'qux'}, ';', ':')\n// returns\n'foo:bar;baz:qux'
\n", + "signatures": [ + { + "params": [ + { + "name": "obj" + }, + { + "name": "sep", + "optional": true + }, + { + "name": "eq", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "querystring.parse(str, [sep], [eq])", + "type": "method", + "name": "parse", + "desc": "

Deserialize a query string to an object.\nOptionally override the default separator ('&') and assignment ('=')\ncharacters.\n\n

\n

Example:\n\n

\n
querystring.parse('foo=bar&baz=qux&baz=quux&corge')\n// returns\n{ foo: 'bar', baz: ['qux', 'quux'], corge: '' }
\n", + "signatures": [ + { + "params": [ + { + "name": "str" + }, + { + "name": "sep", + "optional": true + }, + { + "name": "eq", + "optional": true + } + ] + } + ] + } + ], + "properties": [ + { + "textRaw": "querystring.escape", + "name": "escape", + "desc": "

The escape function used by querystring.stringify,\nprovided so that it could be overridden if necessary.\n\n

\n" + }, + { + "textRaw": "querystring.unescape", + "name": "unescape", + "desc": "

The unescape function used by querystring.parse,\nprovided so that it could be overridden if necessary.\n

\n" + } + ], + "type": "module", + "displayName": "querystring" + } + ] +} --- /dev/null +++ b/doc/api/url.html @@ -0,0 +1,192 @@ + + + + + URL Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

URL#

+
Stability: 3 - Stable
+

This module has utilities for URL resolution and parsing. +Call require('url') to use it. + +

+

Parsed URL objects have some or all of the following fields, depending on +whether or not they exist in the URL string. Any parts that are not in the URL +string will not be in the parsed object. Examples are shown for the URL + +

+

'http://user:pass@host.com:8080/p/a/t/h?query=string#hash' + +

+
    +

  • href: The full URL that was originally parsed. Both the protocol and host are lowercased.

    +

    Example: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

    +
    • +

  • protocol: The request protocol, lowercased.

    +

    Example: 'http:'

    +
    • +

  • host: The full lowercased host portion of the URL, including port +information.

    +

    Example: 'host.com:8080'

    +
    • +

  • auth: The authentication information portion of a URL.

    +

    Example: 'user:pass'

    +
    • +

  • hostname: Just the lowercased hostname portion of the host.

    +

    Example: 'host.com'

    +
    • +

  • port: The port number portion of the host.

    +

    Example: '8080'

    +
    • +

  • pathname: The path section of the URL, that comes after the host and +before the query, including the initial slash if present.

    +

    Example: '/p/a/t/h'

    +
    • +

  • search: The 'query string' portion of the URL, including the leading +question mark.

    +

    Example: '?query=string'

    +
    • +

  • path: Concatenation of pathname and search.

    +

    Example: '/p/a/t/h?query=string'

    +
    • +

  • query: Either the 'params' portion of the query string, or a +querystring-parsed object.

    +

    Example: 'query=string' or {'query':'string'}

    +
    • +

  • hash: The 'fragment' portion of the URL including the pound-sign.

    +

    Example: '#hash'

    +
    • +
+

The following methods are provided by the URL module: + +

+

url.parse(urlStr, [parseQueryString], [slashesDenoteHost])#

+

Take a URL string, and return an object. + +

+

Pass true as the second argument to also parse +the query string using the querystring module. +Defaults to false. + +

+

Pass true as the third argument to treat //foo/bar as +{ host: 'foo', pathname: '/bar' } rather than +{ pathname: '//foo/bar' }. Defaults to false. + +

+

url.format(urlObj)#

+

Take a parsed URL object, and return a formatted URL string. + +

+
    +
  • href will be ignored.
    • +
  • protocolis treated the same with or without the trailing : (colon).
      +
    • The protocols http, https, ftp, gopher, file will be +postfixed with :// (colon-slash-slash).
      • +
    • All other protocols mailto, xmpp, aim, sftp, foo, etc will +be postfixed with : (colon)
      • +
    +
    • +
  • auth will be used if present.
    • +
  • hostname will only be used if host is absent.
    • +
  • port will only be used if host is absent.
    • +
  • host will be used in place of auth, hostname, and port
    • +
  • pathname is treated the same with or without the leading / (slash)
    • +
  • search will be used in place of query
    • +
  • query (object; see querystring) will only be used if search is absent.
    • +
  • search is treated the same with or without the leading ? (question mark)
    • +
  • hash is treated the same with or without the leading # (pound sign, anchor)
    • +
+

url.resolve(from, to)#

+

Take a base URL, and a href URL, and resolve them as a browser would for +an anchor tag. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/tty.json @@ -0,0 +1,46 @@ +{ + "source": "doc/api/tty.markdown", + "modules": [ + { + "textRaw": "TTY", + "name": "tty", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Use require('tty') to access this module.\n\n

\n

Example:\n\n

\n
var tty = require('tty');\nprocess.stdin.resume();\ntty.setRawMode(true);\nprocess.stdin.on('keypress', function(char, key) {\n  if (key && key.ctrl && key.name == 'c') {\n    console.log('graceful exit');\n    process.exit()\n  }\n});
\n", + "methods": [ + { + "textRaw": "tty.isatty(fd)", + "type": "method", + "name": "isatty", + "desc": "

Returns true or false depending on if the fd is associated with a\nterminal.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + } + ] + } + ] + }, + { + "textRaw": "tty.setRawMode(mode)", + "type": "method", + "name": "setRawMode", + "desc": "

mode should be true or false. This sets the properties of the current\nprocess's stdin fd to act either as a raw device or default.\n

\n", + "signatures": [ + { + "params": [ + { + "name": "mode" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "TTY" + } + ] +} --- /dev/null +++ b/doc/api/documentation.json @@ -0,0 +1,28 @@ +{ + "source": "doc/api/documentation.markdown", + "miscs": [ + { + "textRaw": "About this Documentation", + "name": "About this Documentation", + "type": "misc", + "desc": "

The goal of this documentation is to comprehensively explain the Node.js\nAPI, both from a reference as well as a conceptual point of view. Each\nsection describes a built-in module or high-level concept.\n\n

\n

Where appropriate, property types, method arguments, and the arguments\nprovided to event handlers are detailed in a list underneath the topic\nheading.\n\n

\n

Every .html document has a corresponding .json document presenting\nthe same information in a structured manner. This feature is\nexperimental, and added for the benefit of IDEs and other utilities that\nwish to do programmatic things with the documentation.\n\n

\n

Every .html and .json file is generated based on the corresponding\n.markdown file in the doc/api/ folder in node's source tree. The\ndocumentation is generated using the tools/doc/generate.js program.\nThe HTML template is located at doc/template.html.\n\n

\n", + "miscs": [ + { + "textRaw": "Stability Index", + "name": "Stability Index", + "type": "misc", + "desc": "

Throughout the documentation, you will see indications of a section's\nstability. The Node.js API is still somewhat changing, and as it\nmatures, certain parts are more reliable than others. Some are so\nproven, and so relied upon, that they are unlikely to ever change at\nall. Others are brand new and experimental, or known to be hazardous\nand in the process of being redesigned.\n\n

\n

The notices look like this:\n\n

\n
Stability: 1 Experimental
\n

The stability indices are as follows:\n\n

\n
    \n
  • 0 - Deprecated This feature is known to be problematic, and changes are\nplanned. Do not rely on it. Use of the feature may cause warnings. Backwards\ncompatibility should not be expected.
    • \n
\n
    \n
  • 1 - Experimental This feature was introduced recently, and may change\nor be removed in future versions. Please try it out and provide feedback.\nIf it addresses a use-case that is important to you, tell the node core team.
    • \n
\n
    \n
  • 2 - Unstable The API is in the process of settling, but has not yet had\nsufficient real-world testing to be considered stable. Backwards-compatibility\nwill be maintained if reasonable.
    • \n
\n
    \n
  • 3 - Stable The API has proven satisfactory, but cleanup in the underlying\ncode may cause minor changes. Backwards-compatibility is guaranteed.
    • \n
\n
    \n
  • 4 - API Frozen This API has been tested extensively in production and is\nunlikely to ever have to change.
    • \n
\n
    \n
  • 5 - Locked Unless serious bugs are found, this code will not ever\nchange. Please do not suggest changes in this area; they will be refused.
    • \n
\n" + }, + { + "textRaw": "JSON Output", + "name": "json_output", + "stability": 1, + "stabilityText": "Experimental", + "desc": "

Every HTML file in the markdown has a corresponding JSON file with the\nsame data.\n\n

\n

This feature is new as of node v0.6.12. It is experimental.\n

\n", + "type": "misc", + "displayName": "JSON Output" + } + ] + } + ] +} --- /dev/null +++ b/doc/api/zlib.json @@ -0,0 +1,324 @@ +{ + "source": "doc/api/zlib.markdown", + "modules": [ + { + "textRaw": "Zlib", + "name": "zlib", + "stability": 3, + "stabilityText": "Stable", + "desc": "

You can access this module with:\n\n

\n
var zlib = require('zlib');
\n

This provides bindings to Gzip/Gunzip, Deflate/Inflate, and\nDeflateRaw/InflateRaw classes. Each class takes the same options, and\nis a readable/writable Stream.\n\n

\n

Examples

\n

Compressing or decompressing a file can be done by piping an\nfs.ReadStream into a zlib stream, then into an fs.WriteStream.\n\n

\n
var gzip = zlib.createGzip();\nvar fs = require('fs');\nvar inp = fs.createReadStream('input.txt');\nvar out = fs.createWriteStream('input.txt.gz');\n\ninp.pipe(gzip).pipe(out);
\n

Compressing or decompressing data in one step can be done by using\nthe convenience methods.\n\n

\n
var input = '.................................';\nzlib.deflate(input, function(err, buffer) {\n  if (!err) {\n    console.log(buffer.toString('base64'));\n  }\n});\n\nvar buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');\nzlib.unzip(buffer, function(err, buffer) {\n  if (!err) {\n    console.log(buffer.toString());\n  }\n});
\n

To use this module in an HTTP client or server, use the\naccept-encoding\non requests, and the\ncontent-encoding\nheader on responses.\n\n

\n

Note: these examples are drastically simplified to show\nthe basic concept. Zlib encoding can be expensive, and the results\nought to be cached. See Memory Usage Tuning\nbelow for more information on the speed/memory/compression\ntradeoffs involved in zlib usage.\n\n

\n
// client request example\nvar zlib = require('zlib');\nvar http = require('http');\nvar fs = require('fs');\nvar request = http.get({ host: 'izs.me',\n                         path: '/',\n                         port: 80,\n                         headers: { 'accept-encoding': 'gzip,deflate' } });\nrequest.on('response', function(response) {\n  var output = fs.createWriteStream('izs.me_index.html');\n\n  switch (response.headers['content-encoding']) {\n    // or, just use zlib.createUnzip() to handle both cases\n    case 'gzip':\n      response.pipe(zlib.createGunzip()).pipe(output);\n      break;\n    case 'deflate':\n      response.pipe(zlib.createInflate()).pipe(output);\n      break;\n    default:\n      response.pipe(output);\n      break;\n  }\n});\n\n// server example\n// Running a gzip operation on every request is quite expensive.\n// It would be much more efficient to cache the compressed buffer.\nvar zlib = require('zlib');\nvar http = require('http');\nvar fs = require('fs');\nhttp.createServer(function(request, response) {\n  var raw = fs.createReadStream('index.html');\n  var acceptEncoding = request.headers['accept-encoding'];\n  if (!acceptEncoding) {\n    acceptEncoding = '';\n  }\n\n  // Note: this is not a conformant accept-encoding parser.\n  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3\n  if (acceptEncoding.match(/\\bdeflate\\b/)) {\n    response.writeHead(200, { 'content-encoding': 'deflate' });\n    raw.pipe(zlib.createDeflate()).pipe(response);\n  } else if (acceptEncoding.match(/\\bgzip\\b/)) {\n    response.writeHead(200, { 'content-encoding': 'gzip' });\n    raw.pipe(zlib.createGzip()).pipe(response);\n  } else {\n    response.writeHead(200, {});\n    raw.pipe(response);\n  }\n}).listen(1337);
\n", + "miscs": [ + { + "textRaw": "Constants", + "name": "Constants", + "type": "misc", + "desc": "

All of the constants defined in zlib.h are also defined on\nrequire('zlib'). They are described in more detail in the zlib\ndocumentation. See http://zlib.net/manual.html#Constants\nfor more details.\n\n

\n" + }, + { + "textRaw": "Convenience Methods", + "name": "Convenience Methods", + "type": "misc", + "desc": "

All of these take a string or buffer as the first argument, and call the\nsupplied callback with callback(error, result). The\ncompression/decompression engine is created using the default settings\nin all convenience methods. To supply different options, use the\nzlib classes directly.\n\n

\n" + }, + { + "textRaw": "Options", + "name": "Options", + "type": "misc", + "desc": "

Each class takes an options object. All options are optional. (The\nconvenience methods use the default settings for all options.)\n\n

\n

Note that some options are only\nrelevant when compressing, and are ignored by the decompression classes.\n\n

\n
    \n
  • chunkSize (default: 16*1024)
    • \n
  • windowBits
    • \n
  • level (compression only)
    • \n
  • memLevel (compression only)
    • \n
  • strategy (compression only)
    • \n
\n

See the description of deflateInit2 and inflateInit2 at\n

\n

http://zlib.net/manual.html#Advanced for more information on these.\n\n

\n" + }, + { + "textRaw": "Memory Usage Tuning", + "name": "Memory Usage Tuning", + "type": "misc", + "desc": "

From zlib/zconf.h, modified to node's usage:\n\n

\n

The memory requirements for deflate are (in bytes):\n\n

\n
(1 << (windowBits+2)) +  (1 << (memLevel+9))
\n

that is: 128K for windowBits=15 + 128K for memLevel = 8\n(default values) plus a few kilobytes for small objects.\n\n

\n

For example, if you want to reduce\nthe default memory requirements from 256K to 128K, set the options to:\n\n

\n
{ windowBits: 14, memLevel: 7 }
\n

Of course this will generally degrade compression (there's no free lunch).\n\n

\n

The memory requirements for inflate are (in bytes)\n\n

\n
1 << windowBits
\n

that is, 32K for windowBits=15 (default value) plus a few kilobytes\nfor small objects.\n\n

\n

This is in addition to a single internal output slab buffer of size\nchunkSize, which defaults to 16K.\n\n

\n

The speed of zlib compression is affected most dramatically by the\nlevel setting. A higher level will result in better compression, but\nwill take longer to complete. A lower level will result in less\ncompression, but will be much faster.\n\n

\n

In general, greater memory usage options will mean that node has to make\nfewer calls to zlib, since it'll be able to process more data in a\nsingle write operation. So, this is another factor that affects the\nspeed, at the cost of memory usage.\n

\n" + } + ], + "methods": [ + { + "textRaw": "zlib.createGzip([options])", + "type": "method", + "name": "createGzip", + "desc": "

Returns a new Gzip object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createGunzip([options])", + "type": "method", + "name": "createGunzip", + "desc": "

Returns a new Gunzip object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createDeflate([options])", + "type": "method", + "name": "createDeflate", + "desc": "

Returns a new Deflate object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createInflate([options])", + "type": "method", + "name": "createInflate", + "desc": "

Returns a new Inflate object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createDeflateRaw([options])", + "type": "method", + "name": "createDeflateRaw", + "desc": "

Returns a new DeflateRaw object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createInflateRaw([options])", + "type": "method", + "name": "createInflateRaw", + "desc": "

Returns a new InflateRaw object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createUnzip([options])", + "type": "method", + "name": "createUnzip", + "desc": "

Returns a new Unzip object with an options.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.deflate(buf, callback)", + "type": "method", + "name": "deflate", + "desc": "

Compress a string with Deflate.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.deflateRaw(buf, callback)", + "type": "method", + "name": "deflateRaw", + "desc": "

Compress a string with DeflateRaw.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.gzip(buf, callback)", + "type": "method", + "name": "gzip", + "desc": "

Compress a string with Gzip.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.gunzip(buf, callback)", + "type": "method", + "name": "gunzip", + "desc": "

Decompress a raw Buffer with Gunzip.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.inflate(buf, callback)", + "type": "method", + "name": "inflate", + "desc": "

Decompress a raw Buffer with Inflate.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.inflateRaw(buf, callback)", + "type": "method", + "name": "inflateRaw", + "desc": "

Decompress a raw Buffer with InflateRaw.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.unzip(buf, callback)", + "type": "method", + "name": "unzip", + "desc": "

Decompress a raw Buffer with Unzip.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: zlib.Gzip", + "type": "class", + "name": "zlib.Gzip", + "desc": "

Compress data using gzip.\n\n

\n" + }, + { + "textRaw": "Class: zlib.Gunzip", + "type": "class", + "name": "zlib.Gunzip", + "desc": "

Decompress a gzip stream.\n\n

\n" + }, + { + "textRaw": "Class: zlib.Deflate", + "type": "class", + "name": "zlib.Deflate", + "desc": "

Compress data using deflate.\n\n

\n" + }, + { + "textRaw": "Class: zlib.Inflate", + "type": "class", + "name": "zlib.Inflate", + "desc": "

Decompress a deflate stream.\n\n

\n" + }, + { + "textRaw": "Class: zlib.DeflateRaw", + "type": "class", + "name": "zlib.DeflateRaw", + "desc": "

Compress data using deflate, and do not append a zlib header.\n\n

\n" + }, + { + "textRaw": "Class: zlib.InflateRaw", + "type": "class", + "name": "zlib.InflateRaw", + "desc": "

Decompress a raw deflate stream.\n\n

\n" + }, + { + "textRaw": "Class: zlib.Unzip", + "type": "class", + "name": "zlib.Unzip", + "desc": "

Decompress either a Gzip- or Deflate-compressed stream by auto-detecting\nthe header.\n\n

\n" + } + ], + "type": "module", + "displayName": "Zlib" + } + ] +} --- /dev/null +++ b/doc/api/appendix_1.json @@ -0,0 +1,12 @@ +{ + "source": "doc/api/appendix_1.markdown", + "modules": [ + { + "textRaw": "Appendix 1 - Third Party Modules", + "name": "appendix_1_-_third_party_modules", + "desc": "

There are many third party modules for Node. At the time of writing, August\n2010, the master repository of modules is\nthe wiki page.\n\n

\n

This appendix is intended as a SMALL guide to new-comers to help them\nquickly find what are considered to be quality modules. It is not intended\nto be a complete list. There may be better more complete modules found\nelsewhere.\n\n

\n\n

Patches to this list are welcome.\n

\n", + "type": "module", + "displayName": "Appendix 1 - Third Party Modules" + } + ] +} --- /dev/null +++ b/doc/api/debugger.json @@ -0,0 +1,51 @@ +{ + "source": "doc/api/debugger.markdown", + "stability": 3, + "stabilityText": "Stable", + "miscs": [ + { + "textRaw": "Debugger", + "name": "Debugger", + "stability": 3, + "stabilityText": "Stable", + "type": "misc", + "desc": "

V8 comes with an extensive debugger which is accessible out-of-process via a\nsimple TCP protocol.\nNode has a built-in client for this debugger. To use this, start Node with the\ndebug argument; a prompt will appear:\n\n

\n
% node debug myscript.js\n< debugger listening on port 5858\nconnecting... ok\nbreak in /home/indutny/Code/git/indutny/myscript.js:1\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\ndebug>
\n

Node's debugger client doesn't support the full range of commands, but\nsimple step and inspection is possible. By putting the statement debugger;\ninto the source code of your script, you will enable a breakpoint.\n\n

\n

For example, suppose myscript.js looked like this:\n\n

\n
// myscript.js\nx = 5;\nsetTimeout(function () {\n  debugger;\n  console.log("world");\n}, 1000);\nconsole.log("hello");
\n

Then once the debugger is run, it will break on line 4.\n\n

\n
% node debug myscript.js\n< debugger listening on port 5858\nconnecting... ok\nbreak in /home/indutny/Code/git/indutny/myscript.js:1\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\ndebug> cont\n< hello\nbreak in /home/indutny/Code/git/indutny/myscript.js:3\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\ndebug> next\nbreak in /home/indutny/Code/git/indutny/myscript.js:4\n  2 setTimeout(function () {\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\n  6 console.log("hello");\ndebug> repl\nPress Ctrl + C to leave debug repl\n> x\n5\n> 2+2\n4\ndebug> next\n< world\nbreak in /home/indutny/Code/git/indutny/myscript.js:5\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\n  6 console.log("hello");\n  7\ndebug> quit\n%
\n

The repl command allows you to evaluate code remotely. The next command\nsteps over to the next line. There are a few other commands available and more\nto come. Type help to see others.\n\n

\n", + "miscs": [ + { + "textRaw": "Watchers", + "name": "watchers", + "desc": "

You can watch expression and variable values while debugging your code.\nOn every breakpoint each expression from the watchers list will be evaluated\nin the current context and displayed just before the breakpoint's source code\nlisting.\n\n

\n

To start watching an expression, type watch("my_expression"). watchers\nprints the active watchers. To remove a watcher, type\nunwatch("my_expression").\n\n

\n", + "type": "misc", + "displayName": "Watchers" + }, + { + "textRaw": "Commands reference", + "name": "commands_reference", + "modules": [ + { + "textRaw": "Execution control", + "name": "Execution control", + "type": "module", + "displayName": "Various" + }, + { + "textRaw": "Various", + "name": "various", + "type": "module", + "displayName": "Various" + } + ], + "type": "misc", + "displayName": "Commands reference" + }, + { + "textRaw": "Advanced Usage", + "name": "advanced_usage", + "desc": "

The V8 debugger can be enabled and accessed either by starting Node with\nthe --debug command-line flag or by signaling an existing Node process\nwith SIGUSR1.\n

\n", + "type": "misc", + "displayName": "Advanced Usage" + } + ] + } + ] +} --- /dev/null +++ b/doc/api/assert.json @@ -0,0 +1,258 @@ +{ + "source": "doc/api/assert.markdown", + "modules": [ + { + "textRaw": "Assert", + "name": "assert", + "stability": 5, + "stabilityText": "Locked", + "desc": "

This module is used for writing unit tests for your applications, you can\naccess it with require('assert').\n\n

\n", + "methods": [ + { + "textRaw": "assert.fail(actual, expected, message, operator)", + "type": "method", + "name": "fail", + "desc": "

Throws an exception that displays the values for actual and expected separated by the provided operator.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message" + }, + { + "name": "operator" + } + ] + } + ] + }, + { + "textRaw": "assert(value, message), assert.ok(value, [message])", + "type": "method", + "name": "ok", + "desc": "

Tests if value is a true value, it is equivalent to assert.equal(true, value, message);\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "value" + }, + { + "name": "message)" + }, + { + "name": "assert.ok(value" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.equal(actual, expected, [message])", + "type": "method", + "name": "equal", + "desc": "

Tests shallow, coercive equality with the equal comparison operator ( == ).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.notEqual(actual, expected, [message])", + "type": "method", + "name": "notEqual", + "desc": "

Tests shallow, coercive non-equality with the not equal comparison operator ( != ).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.deepEqual(actual, expected, [message])", + "type": "method", + "name": "deepEqual", + "desc": "

Tests for deep equality.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.notDeepEqual(actual, expected, [message])", + "type": "method", + "name": "notDeepEqual", + "desc": "

Tests for any deep inequality.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.strictEqual(actual, expected, [message])", + "type": "method", + "name": "strictEqual", + "desc": "

Tests strict equality, as determined by the strict equality operator ( === )\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.notStrictEqual(actual, expected, [message])", + "type": "method", + "name": "notStrictEqual", + "desc": "

Tests strict non-equality, as determined by the strict not equal operator ( !== )\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.throws(block, [error], [message])", + "type": "method", + "name": "throws", + "desc": "

Expects block to throw an error. error can be constructor, regexp or \nvalidation function.\n\n

\n

Validate instanceof using constructor:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  Error\n);
\n

Validate error message using RegExp:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  /value/\n);
\n

Custom error validation:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  function(err) {\n    if ( (err instanceof Error) && /value/.test(err) ) {\n      return true;\n    }\n  },\n  "unexpected error"\n);
\n", + "signatures": [ + { + "params": [ + { + "name": "block" + }, + { + "name": "error", + "optional": true + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.doesNotThrow(block, [error], [message])", + "type": "method", + "name": "doesNotThrow", + "desc": "

Expects block not to throw an error, see assert.throws for details.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "block" + }, + { + "name": "error", + "optional": true + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.ifError(value)", + "type": "method", + "name": "ifError", + "desc": "

Tests if value is not a false value, throws if it is a true value. Useful when\ntesting the first argument, error in callbacks.\n

\n", + "signatures": [ + { + "params": [ + { + "name": "value" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "Assert" + } + ] +} --- /dev/null +++ b/doc/api/path.html @@ -0,0 +1,259 @@ + + + + + Path Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Path#

+
Stability: 3 - Stable
+

This module contains utilities for handling and transforming file +paths. Almost all these methods perform only string transformations. +The file system is not consulted to check whether paths are valid. + +

+

path.exists and path.existsSync are the exceptions, and should +logically be found in the fs module as they do access the file system. + +

+

Use require('path') to use this module. The following methods are provided: + +

+

path.normalize(p)#

+

Normalize a string path, taking care of '..' and '.' parts. + +

+

When multiple slashes are found, they're replaced by a single one; +when the path contains a trailing slash, it is preserved. +On windows backslashes are used. + +

+

Example: + +

+
path.normalize('/foo/bar//baz/asdf/quux/..')
+// returns
+'/foo/bar/baz/asdf'
+

path.join([path1], [path2], [...])#

+

Join all arguments together and normalize the resulting path. +Non-string arguments are ignored. + +

+

Example: + +

+
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
+// returns
+'/foo/bar/baz/asdf'
+
+path.join('foo', {}, 'bar')
+// returns
+'foo/bar'
+

path.resolve([from ...], to)#

+

Resolves to to an absolute path. + +

+

If to isn't already absolute from arguments are prepended in right to left +order, until an absolute path is found. If after using all from paths still +no absolute path is found, the current working directory is used as well. The +resulting path is normalized, and trailing slashes are removed unless the path +gets resolved to the root directory. Non-string arguments are ignored. + +

+

Another way to think of it is as a sequence of cd commands in a shell. + +

+
path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
+

Is similar to: + +

+
cd foo/bar
+cd /tmp/file/
+cd ..
+cd a/../subfile
+pwd
+

The difference is that the different paths don't need to exist and may also be +files. + +

+

Examples: + +

+
path.resolve('/foo/bar', './baz')
+// returns
+'/foo/bar/baz'
+
+path.resolve('/foo/bar', '/tmp/file/')
+// returns
+'/tmp/file'
+
+path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
+// if currently in /home/myself/node, it returns
+'/home/myself/node/wwwroot/static_files/gif/image.gif'
+

path.relative(from, to)#

+

Solve the relative path from from to to. + +

+

At times we have two absolute paths, and we need to derive the relative +path from one to the other. This is actually the reverse transform of +path.resolve, which means we see that: + +

+
path.resolve(from, path.relative(from, to)) == path.resolve(to)
+

Examples: + +

+
path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb')
+// returns
+'..\\..\\impl\\bbb'
+
+path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
+// returns
+'../../impl/bbb'
+

path.dirname(p)#

+

Return the directory name of a path. Similar to the Unix dirname command. + +

+

Example: + +

+
path.dirname('/foo/bar/baz/asdf/quux')
+// returns
+'/foo/bar/baz/asdf'
+

path.basename(p, [ext])#

+

Return the last portion of a path. Similar to the Unix basename command. + +

+

Example: + +

+
path.basename('/foo/bar/baz/asdf/quux.html')
+// returns
+'quux.html'
+
+path.basename('/foo/bar/baz/asdf/quux.html', '.html')
+// returns
+'quux'
+

path.extname(p)#

+

Return the extension of the path, from the last '.' to end of string +in the last portion of the path. If there is no '.' in the last portion +of the path or the first character of it is '.', then it returns +an empty string. Examples: + +

+
path.extname('index.html')
+// returns
+'.html'
+
+path.extname('index.')
+// returns
+'.'
+
+path.extname('index')
+// returns
+''
+

path.exists(p, [callback])#

+

Test whether or not the given path exists by checking with the file system. +Then call the callback argument with either true or false. Example: + +

+
path.exists('/etc/passwd', function (exists) {
+  util.debug(exists ? "it's there" : "no passwd!");
+});
+

path.existsSync(p)#

+

Synchronous version of path.exists. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/process.json @@ -0,0 +1,269 @@ +{ + "source": "doc/api/process.markdown", + "globals": [ + { + "textRaw": "process", + "name": "process", + "type": "global", + "desc": "

The process object is a global object and can be accessed from anywhere.\nIt is an instance of EventEmitter.\n\n\n

\n", + "events": [ + { + "textRaw": "Event: 'exit'", + "type": "event", + "name": "exit", + "desc": "

Emitted when the process is about to exit. This is a good hook to perform\nconstant time checks of the module's state (like for unit tests). The main\nevent loop will no longer be run after the 'exit' callback finishes, so\ntimers may not be scheduled.\n\n

\n

Example of listening for exit:\n\n

\n
process.on('exit', function () {\n  process.nextTick(function () {\n   console.log('This will not run');\n  });\n  console.log('About to exit.');\n});
\n", + "params": [] + }, + { + "textRaw": "Event: 'uncaughtException'", + "type": "event", + "name": "uncaughtException", + "desc": "

Emitted when an exception bubbles all the way back to the event loop. If a\nlistener is added for this exception, the default action (which is to print\na stack trace and exit) will not occur.\n\n

\n

Example of listening for uncaughtException:\n\n

\n
process.on('uncaughtException', function (err) {\n  console.log('Caught exception: ' + err);\n});\n\nsetTimeout(function () {\n  console.log('This will still run.');\n}, 500);\n\n// Intentionally cause an exception, but don't catch it.\nnonexistentFunc();\nconsole.log('This will not run.');
\n

Note that uncaughtException is a very crude mechanism for exception\nhandling. Using try / catch in your program will give you more control over\nyour program's flow. Especially for server programs that are designed to\nstay running forever, uncaughtException can be a useful safety mechanism.\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Signal Events", + "name": "SIGINT, SIGUSR1, etc.", + "type": "event", + "desc": "

Emitted when the processes receives a signal. See sigaction(2) for a list of\nstandard POSIX signal names such as SIGINT, SIGUSR1, etc.\n\n

\n

Example of listening for SIGINT:\n\n

\n
// Start reading from stdin so we don't exit.\nprocess.stdin.resume();\n\nprocess.on('SIGINT', function () {\n  console.log('Got SIGINT.  Press Control-D to exit.');\n});
\n

An easy way to send the SIGINT signal is with Control-C in most terminal\nprograms.\n\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "process.stdout", + "name": "stdout", + "desc": "

A Writable Stream to stdout.\n\n

\n

Example: the definition of console.log\n\n

\n
console.log = function (d) {\n  process.stdout.write(d + '\\n');\n};
\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" + }, + { + "textRaw": "process.stderr", + "name": "stderr", + "desc": "

A writable stream to stderr.\n\n

\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" + }, + { + "textRaw": "process.stdin", + "name": "stdin", + "desc": "

A Readable Stream for stdin. The stdin stream is paused by default, so one\nmust call process.stdin.resume() to read from it.\n\n

\n

Example of opening standard input and listening for both events:\n\n

\n
process.stdin.resume();\nprocess.stdin.setEncoding('utf8');\n\nprocess.stdin.on('data', function (chunk) {\n  process.stdout.write('data: ' + chunk);\n});\n\nprocess.stdin.on('end', function () {\n  process.stdout.write('end');\n});
\n" + }, + { + "textRaw": "process.argv", + "name": "argv", + "desc": "

An array containing the command line arguments. The first element will be\n'node', the second element will be the name of the JavaScript file. The\nnext elements will be any additional command line arguments.\n\n

\n
// print process.argv\nprocess.argv.forEach(function (val, index, array) {\n  console.log(index + ': ' + val);\n});
\n

This will generate:\n\n

\n
$ node process-2.js one two=three four\n0: node\n1: /Users/mjr/work/node/process-2.js\n2: one\n3: two=three\n4: four
\n" + }, + { + "textRaw": "process.execPath", + "name": "execPath", + "desc": "

This is the absolute pathname of the executable that started the process.\n\n

\n

Example:\n\n

\n
/usr/local/bin/node
\n" + }, + { + "textRaw": "process.env", + "name": "env", + "desc": "

An object containing the user environment. See environ(7).\n\n\n

\n" + }, + { + "textRaw": "process.version", + "name": "version", + "desc": "

A compiled-in property that exposes NODE_VERSION.\n\n

\n
console.log('Version: ' + process.version);
\n" + }, + { + "textRaw": "process.versions", + "name": "versions", + "desc": "

A property exposing version strings of node and its dependencies.\n\n

\n
console.log(process.versions);
\n

Will output:\n\n

\n
{ node: '0.4.12',\n  v8: '3.1.8.26',\n  ares: '1.7.4',\n  ev: '4.4',\n  openssl: '1.0.0e-fips' }
\n" + }, + { + "textRaw": "process.installPrefix", + "name": "installPrefix", + "desc": "

A compiled-in property that exposes NODE_PREFIX.\n\n

\n
console.log('Prefix: ' + process.installPrefix);
\n" + }, + { + "textRaw": "process.pid", + "name": "pid", + "desc": "

The PID of the process.\n\n

\n
console.log('This process is pid ' + process.pid);
\n" + }, + { + "textRaw": "process.title", + "name": "title", + "desc": "

Getter/setter to set what is displayed in 'ps'.\n\n\n

\n" + }, + { + "textRaw": "process.arch", + "name": "arch", + "desc": "

What processor architecture you're running on: 'arm', 'ia32', or 'x64'.\n\n

\n
console.log('This processor architecture is ' + process.arch);
\n" + }, + { + "textRaw": "process.platform", + "name": "platform", + "desc": "

What platform you're running on. 'linux2', 'darwin', etc.\n\n

\n
console.log('This platform is ' + process.platform);
\n" + } + ], + "methods": [ + { + "textRaw": "process.chdir(directory)", + "type": "method", + "name": "chdir", + "desc": "

Changes the current working directory of the process or throws an exception if that fails.\n\n

\n
console.log('Starting directory: ' + process.cwd());\ntry {\n  process.chdir('/tmp');\n  console.log('New directory: ' + process.cwd());\n}\ncatch (err) {\n  console.log('chdir: ' + err);\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "directory" + } + ] + } + ] + }, + { + "textRaw": "process.cwd()", + "type": "method", + "name": "cwd", + "desc": "

Returns the current working directory of the process.\n\n

\n
console.log('Current directory: ' + process.cwd());
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.exit([code])", + "type": "method", + "name": "exit", + "desc": "

Ends the process with the specified code. If omitted, exit uses the\n'success' code 0.\n\n

\n

To exit with a 'failure' code:\n\n

\n
process.exit(1);
\n

The shell that executed node should see the exit code as 1.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "process.getgid()", + "type": "method", + "name": "getgid", + "desc": "

Gets the group identity of the process. (See getgid(2).)\nThis is the numerical group id, not the group name.\n\n

\n
console.log('Current gid: ' + process.getgid());
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.setgid(id)", + "type": "method", + "name": "setgid", + "desc": "

Sets the group identity of the process. (See setgid(2).) This accepts either\na numerical ID or a groupname string. If a groupname is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current gid: ' + process.getgid());\ntry {\n  process.setgid(501);\n  console.log('New gid: ' + process.getgid());\n}\ncatch (err) {\n  console.log('Failed to set gid: ' + err);\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "id" + } + ] + } + ] + }, + { + "textRaw": "process.getuid()", + "type": "method", + "name": "getuid", + "desc": "

Gets the user identity of the process. (See getuid(2).)\nThis is the numerical userid, not the username.\n\n

\n
console.log('Current uid: ' + process.getuid());
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.setuid(id)", + "type": "method", + "name": "setuid", + "desc": "

Sets the user identity of the process. (See setuid(2).) This accepts either\na numerical ID or a username string. If a username is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current uid: ' + process.getuid());\ntry {\n  process.setuid(501);\n  console.log('New uid: ' + process.getuid());\n}\ncatch (err) {\n  console.log('Failed to set uid: ' + err);\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "id" + } + ] + } + ] + }, + { + "textRaw": "process.kill(pid, [signal])", + "type": "method", + "name": "kill", + "desc": "

Send a signal to a process. pid is the process id and signal is the\nstring describing the signal to send. Signal names are strings like\n'SIGINT' or 'SIGUSR1'. If omitted, the signal will be 'SIGTERM'.\nSee kill(2) for more information.\n\n

\n

Note that just because the name of this function is process.kill, it is\nreally just a signal sender, like the kill system call. The signal sent\nmay do something other than kill the target process.\n\n

\n

Example of sending a signal to yourself:\n\n

\n
process.on('SIGHUP', function () {\n  console.log('Got SIGHUP signal.');\n});\n\nsetTimeout(function () {\n  console.log('Exiting.');\n  process.exit(0);\n}, 100);\n\nprocess.kill(process.pid, 'SIGHUP');
\n", + "signatures": [ + { + "params": [ + { + "name": "pid" + }, + { + "name": "signal", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "process.memoryUsage()", + "type": "method", + "name": "memoryUsage", + "desc": "

Returns an object describing the memory usage of the Node process\nmeasured in bytes.\n\n

\n
var util = require('util');\n\nconsole.log(util.inspect(process.memoryUsage()));
\n

This will generate:\n\n

\n
{ rss: 4935680,\n  heapTotal: 1826816,\n  heapUsed: 650472 }
\n

heapTotal and heapUsed refer to V8's memory usage.\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.nextTick(callback)", + "type": "method", + "name": "nextTick", + "desc": "

On the next loop around the event loop call this callback.\nThis is not a simple alias to setTimeout(fn, 0), it's much more\nefficient.\n\n

\n
process.nextTick(function () {\n  console.log('nextTick callback');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "process.umask([mask])", + "type": "method", + "name": "umask", + "desc": "

Sets or reads the process's file mode creation mask. Child processes inherit\nthe mask from the parent process. Returns the old mask if mask argument is\ngiven, otherwise returns the current mask.\n\n

\n
var oldmask, newmask = 0644;\n\noldmask = process.umask(newmask);\nconsole.log('Changed umask from: ' + oldmask.toString(8) +\n            ' to ' + newmask.toString(8));
\n", + "signatures": [ + { + "params": [ + { + "name": "mask", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "process.uptime()", + "type": "method", + "name": "uptime", + "desc": "

Number of seconds Node has been running.\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + } + ] +} --- /dev/null +++ b/doc/api/globals.json @@ -0,0 +1,219 @@ +{ + "source": "doc/api/globals.markdown", + "globals": [ + { + "textRaw": "global", + "name": "global", + "type": "global", + "desc": "

In browsers, the top-level scope is the global scope. That means that in\nbrowsers if you're in the global scope var something will define a global\nvariable. In Node this is different. The top-level scope is not the global\nscope; var something inside a Node module will be local to that module.\n\n

\n" + }, + { + "textRaw": "process", + "name": "process", + "type": "global", + "desc": "

The process object. See the process object section.\n\n

\n" + }, + { + "textRaw": "console", + "name": "console", + "type": "global", + "desc": "

Used to print to stdout and stderr. See the stdio section.\n\n

\n" + }, + { + "textRaw": "Buffer", + "name": "Buffer", + "type": "global", + "desc": "

Used to handle binary data. See the buffer section.\n\n

\n" + }, + { + "textRaw": "clearInterval(t)", + "type": "global", + "name": "clearInterval", + "desc": "

The timer functions are global variables. See the timers section.\n

\n" + } + ], + "vars": [ + { + "textRaw": "require()", + "type": "var", + "name": "require", + "desc": "

To require modules. See the Modules section.\nrequire isn't actually a global but rather local to each module.\n\n\n

\n", + "methods": [ + { + "textRaw": "require.resolve()", + "type": "method", + "name": "resolve", + "desc": "

Use the internal require() machinery to look up the location of a module,\nbut rather than loading the module, just return the resolved filename.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "properties": [ + { + "textRaw": "`cache` {Object} ", + "name": "cache", + "desc": "

Modules are cached in this object when they are required. By deleting a key\nvalue from this object, the next require will reload the module.\n\n

\n" + } + ] + }, + { + "textRaw": "__filename", + "name": "__filename", + "type": "var", + "desc": "

The filename of the code being executed. This is the resolved absolute path\nof this code file. For a main program this is not necessarily the same\nfilename used in the command line. The value inside a module is the path\nto that module file.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__filename);\n// /Users/mjr/example.js
\n

__filename isn't actually a global but rather local to each module.\n\n

\n" + }, + { + "textRaw": "__dirname", + "name": "__dirname", + "type": "var", + "desc": "

The name of the directory that the currently executing script resides in.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__dirname);\n// /Users/mjr
\n

__dirname isn't actually a global but rather local to each module.\n\n\n

\n" + }, + { + "textRaw": "module", + "name": "module", + "type": "var", + "desc": "

A reference to the current module. In particular\nmodule.exports is the same as the exports object. See src/node.js\nfor more information.\nmodule isn't actually a global but rather local to each module.\n\n\n

\n" + }, + { + "textRaw": "exports", + "name": "exports", + "type": "var", + "desc": "

An object which is shared between all instances of the current module and\nmade accessible through require().\nexports is the same as the module.exports object. See src/node.js\nfor more information.\nexports isn't actually a global but rather local to each module.\n\n

\n

See the module system documentation for more\ninformation.\n\n

\n

See the module section for more information.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "setInterval(cb, ms)", + "type": "method", + "name": "setInterval", + "desc": "

The timer functions are global variables. See the timers section.\n

\n", + "signatures": [ + { + "params": [ + { + "name": "cb" + }, + { + "name": "ms" + } + ] + } + ] + } + ], + "miscs": [ + { + "textRaw": "Global Objects", + "name": "Global Objects", + "type": "misc", + "desc": "

These objects are available in all modules. Some of these objects aren't\nactually in the global scope but in the module scope - this will be noted.\n\n

\n", + "globals": [ + { + "textRaw": "global", + "name": "global", + "type": "global", + "desc": "

In browsers, the top-level scope is the global scope. That means that in\nbrowsers if you're in the global scope var something will define a global\nvariable. In Node this is different. The top-level scope is not the global\nscope; var something inside a Node module will be local to that module.\n\n

\n" + }, + { + "textRaw": "process", + "name": "process", + "type": "global", + "desc": "

The process object. See the process object section.\n\n

\n" + }, + { + "textRaw": "console", + "name": "console", + "type": "global", + "desc": "

Used to print to stdout and stderr. See the stdio section.\n\n

\n" + }, + { + "textRaw": "Buffer", + "name": "Buffer", + "type": "global", + "desc": "

Used to handle binary data. See the buffer section.\n\n

\n" + }, + { + "textRaw": "clearInterval(t)", + "type": "global", + "name": "clearInterval", + "desc": "

The timer functions are global variables. See the timers section.\n

\n" + } + ], + "vars": [ + { + "textRaw": "require()", + "type": "var", + "name": "require", + "desc": "

To require modules. See the Modules section.\nrequire isn't actually a global but rather local to each module.\n\n\n

\n", + "methods": [ + { + "textRaw": "require.resolve()", + "type": "method", + "name": "resolve", + "desc": "

Use the internal require() machinery to look up the location of a module,\nbut rather than loading the module, just return the resolved filename.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "properties": [ + { + "textRaw": "`cache` {Object} ", + "name": "cache", + "desc": "

Modules are cached in this object when they are required. By deleting a key\nvalue from this object, the next require will reload the module.\n\n

\n" + } + ] + }, + { + "textRaw": "__filename", + "name": "__filename", + "type": "var", + "desc": "

The filename of the code being executed. This is the resolved absolute path\nof this code file. For a main program this is not necessarily the same\nfilename used in the command line. The value inside a module is the path\nto that module file.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__filename);\n// /Users/mjr/example.js
\n

__filename isn't actually a global but rather local to each module.\n\n

\n" + }, + { + "textRaw": "__dirname", + "name": "__dirname", + "type": "var", + "desc": "

The name of the directory that the currently executing script resides in.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__dirname);\n// /Users/mjr
\n

__dirname isn't actually a global but rather local to each module.\n\n\n

\n" + }, + { + "textRaw": "module", + "name": "module", + "type": "var", + "desc": "

A reference to the current module. In particular\nmodule.exports is the same as the exports object. See src/node.js\nfor more information.\nmodule isn't actually a global but rather local to each module.\n\n\n

\n" + }, + { + "textRaw": "exports", + "name": "exports", + "type": "var", + "desc": "

An object which is shared between all instances of the current module and\nmade accessible through require().\nexports is the same as the module.exports object. See src/node.js\nfor more information.\nexports isn't actually a global but rather local to each module.\n\n

\n

See the module system documentation for more\ninformation.\n\n

\n

See the module section for more information.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "setInterval(cb, ms)", + "type": "method", + "name": "setInterval", + "desc": "

The timer functions are global variables. See the timers section.\n

\n", + "signatures": [ + { + "params": [ + { + "name": "cb" + }, + { + "name": "ms" + } + ] + } + ] + } + ] + } + ] +} --- /dev/null +++ b/doc/api/tls.html @@ -0,0 +1,599 @@ + + + + + TLS (SSL) Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

TLS (SSL)#

+
Stability: 3 - Stable
+

Use require('tls') to access this module. + +

+

The tls module uses OpenSSL to provide Transport Layer Security and/or +Secure Socket Layer: encrypted stream communication. + +

+

TLS/SSL is a public/private key infrastructure. Each client and each +server must have a private key. A private key is created like this + +

+
openssl genrsa -out ryans-key.pem 1024
+

All severs and some clients need to have a certificate. Certificates are public +keys signed by a Certificate Authority or self-signed. The first step to +getting a certificate is to create a "Certificate Signing Request" (CSR) +file. This is done with: + +

+
openssl req -new -key ryans-key.pem -out ryans-csr.pem
+

To create a self-signed certificate with the CSR, do this: + +

+
openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem
+

Alternatively you can send the CSR to a Certificate Authority for signing. + +

+

(TODO: docs on creating a CA, for now interested users should just look at +test/fixtures/keys/Makefile in the Node source code) + +

+

To create .pfx or .p12, do this: + +

+
openssl pkcs12 -export -in agent5-cert.pem -inkey agent5-key.pem \
+    -certfile ca-cert.pem -out agent5.pfx
+
    +
  • in: certificate
    • +
  • inkey: private key
    • +
  • certfile: all CA certs concatenated in one file like +cat ca1-cert.pem ca2-cert.pem > ca-cert.pem
    • +
+

Client-initiated renegotiation attack mitigation#

+ + +

The TLS protocol lets the client renegotiate certain aspects of the TLS session. +Unfortunately, session renegotiation requires a disproportional amount of +server-side resources, which makes it a potential vector for denial-of-service +attacks. + +

+

To mitigate this, renegotiations are limited to three times every 10 minutes. An +error is emitted on the CleartextStream instance when +the threshold is exceeded. The limits are configurable: + +

+
    +

  • tls.CLIENT_RENEG_LIMIT: renegotiation limit, default is 3.

    +
    • +

  • tls.CLIENT_RENEG_WINDOW: renegotiation window in seconds, default is

    +
                           10 minutes.
    +
    • +
+

Don't change the defaults unless you know what you are doing. + +

+

To test your server, connect to it with openssl s_client -connect address:port +and tap R<CR> (that's the letter R followed by a carriage return) a few +times. + + +

+

NPN and SNI#

+ + +

NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS +handshake extensions allowing you: + +

+
    +
  • NPN - to use one TLS server for multiple protocols (HTTP, SPDY)
    • +
  • SNI - to use one TLS server for multiple hostnames with different SSL +certificates.
    • +
+

tls.createServer(options, [secureConnectionListener])#

+

Creates a new tls.Server. +The connectionListener argument is automatically set as a listener for the +secureConnection event. +The options object has these possibilities: + +

+
    +

  • pfx: A string or Buffer containing the private key, certificate and +CA certs of the server in PFX or PKCS12 format. (Mutually exclusive with +the key, cert and ca options.)

    +
    • +

  • key: A string or Buffer containing the private key of the server in +PEM format. (Required)

    +
    • +

  • passphrase: A string of passphrase for the private key or pfx.

    +
    • +

  • cert: A string or Buffer containing the certificate key of the server in +PEM format. (Required)

    +
    • +

  • ca: An array of strings or Buffers of trusted certificates. If this is +omitted several well known "root" CAs will be used, like VeriSign. +These are used to authorize connections.

    +
    • +

  • ciphers: A string describing the ciphers to use or exclude. Consult +http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for +details on the format.

    +
    • +

  • requestCert: If true the server will request a certificate from +clients that connect and attempt to verify that certificate. Default: +false.

    +
    • +

  • rejectUnauthorized: If true the server will reject any connection +which is not authorized with the list of supplied CAs. This option only +has an effect if requestCert is true. Default: false.

    +
    • +

  • NPNProtocols: An array or Buffer of possible NPN protocols. (Protocols +should be ordered by their priority).

    +
    • +

  • SNICallback: A function that will be called if client supports SNI TLS +extension. Only one argument will be passed to it: servername. And +SNICallback should return SecureContext instance. +(You can use crypto.createCredentials(...).context to get proper +SecureContext). If SNICallback wasn't provided - default callback with +high-level API will be used (see below).

    +
    • +

  • sessionIdContext: A string containing a opaque identifier for session +resumption. If requestCert is true, the default is MD5 hash value +generated from command-line. Otherwise, the default is not provided.

    +
    • +
+

Here is a simple example echo server: + +

+
var tls = require('tls');
+var fs = require('fs');
+
+var options = {
+  key: fs.readFileSync('server-key.pem'),
+  cert: fs.readFileSync('server-cert.pem'),
+
+  // This is necessary only if using the client certificate authentication.
+  requestCert: true,
+
+  // This is necessary only if the client uses the self-signed certificate.
+  ca: [ fs.readFileSync('client-cert.pem') ]
+};
+
+var server = tls.createServer(options, function(cleartextStream) {
+  console.log('server connected',
+              cleartextStream.authorized ? 'authorized' : 'unauthorized');
+  cleartextStream.write("welcome!\n");
+  cleartextStream.setEncoding('utf8');
+  cleartextStream.pipe(cleartextStream);
+});
+server.listen(8000, function() {
+  console.log('server bound');
+});
+

Or + +

+
var tls = require('tls');
+var fs = require('fs');
+
+var options = {
+  pfx: fs.readFileSync('server.pfx'),
+
+  // This is necessary only if using the client certificate authentication.
+  requestCert: true,
+
+};
+
+var server = tls.createServer(options, function(cleartextStream) {
+  console.log('server connected',
+              cleartextStream.authorized ? 'authorized' : 'unauthorized');
+  cleartextStream.write("welcome!\n");
+  cleartextStream.setEncoding('utf8');
+  cleartextStream.pipe(cleartextStream);
+});
+server.listen(8000, function() {
+  console.log('server bound');
+});
+

You can test this server by connecting to it with openssl s_client: + + +

+
openssl s_client -connect 127.0.0.1:8000
+

tls.connect(port, [host], [options], [secureConnectListener])#

+

Creates a new client connection to the given port and host. (If host +defaults to localhost.) options should be an object which specifies + +

+
    +

  • pfx: A string or Buffer containing the private key, certificate and +CA certs of the server in PFX or PKCS12 format.

    +
    • +

  • key: A string or Buffer containing the private key of the client in +PEM format.

    +
    • +

  • passphrase: A string of passphrase for the private key or pfx.

    +
    • +

  • cert: A string or Buffer containing the certificate key of the client in +PEM format.

    +
    • +

  • ca: An array of strings or Buffers of trusted certificates. If this is +omitted several well known "root" CAs will be used, like VeriSign. +These are used to authorize connections.

    +
    • +

  • NPNProtocols: An array of string or Buffer containing supported NPN +protocols. Buffer should have following format: 0x05hello0x05world, +where first byte is next protocol name's length. (Passing array should +usually be much simpler: ['hello', 'world'].)

    +
    • +

  • servername: Servername for SNI (Server Name Indication) TLS extension.

    +
    • +

  • socket: Establish secure connection on a given socket rather than +creating a new socket. If this option is specified, host and port +are ignored. This is intended FOR INTERNAL USE ONLY. As with all +undocumented APIs in Node, they should not be used.

    +
    • +
+

The secureConnectListener parameter will be added as a listener for the +'secureConnect' event. + +

+

tls.connect() returns a CleartextStream object. + +

+

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

+
var tls = require('tls');
+var fs = require('fs');
+
+var options = {
+  // These are necessary only if using the client certificate authentication
+  key: fs.readFileSync('client-key.pem'),
+  cert: fs.readFileSync('client-cert.pem'),
+
+  // This is necessary only if the server uses the self-signed certificate
+  ca: [ fs.readFileSync('server-cert.pem') ]
+};
+
+var cleartextStream = tls.connect(8000, options, function() {
+  console.log('client connected',
+              cleartextStream.authorized ? 'authorized' : 'unauthorized');
+  process.stdin.pipe(cleartextStream);
+  process.stdin.resume();
+});
+cleartextStream.setEncoding('utf8');
+cleartextStream.on('data', function(data) {
+  console.log(data);
+});
+cleartextStream.on('end', function() {
+  server.close();
+});
+

Or + +

+
var tls = require('tls');
+var fs = require('fs');
+
+var options = {
+  pfx: fs.readFileSync('client.pfx')
+};
+
+var cleartextStream = tls.connect(8000, options, function() {
+  console.log('client connected',
+              cleartextStream.authorized ? 'authorized' : 'unauthorized');
+  process.stdin.pipe(cleartextStream);
+  process.stdin.resume();
+});
+cleartextStream.setEncoding('utf8');
+cleartextStream.on('data', function(data) {
+  console.log(data);
+});
+cleartextStream.on('end', function() {
+  server.close();
+});
+

tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])#

+

Creates a new secure pair object with two streams, one of which reads/writes +encrypted data, and one reads/writes cleartext data. +Generally the encrypted one is piped to/from an incoming encrypted data stream, +and the cleartext one is used as a replacement for the initial encrypted stream. + +

+
    +

  • credentials: A credentials object from crypto.createCredentials( ... )

    +
    • +

  • isServer: A boolean indicating whether this tls connection should be +opened as a server or a client.

    +
    • +

  • requestCert: A boolean indicating whether a server should request a +certificate from a connecting client. Only applies to server connections.

    +
    • +

  • rejectUnauthorized: A boolean indicating whether a server should +automatically reject clients with invalid certificates. Only applies to +servers with requestCert enabled.

    +
    • +
+

tls.createSecurePair() returns a SecurePair object with +cleartext and encrypted stream properties. + +

+

Class: SecurePair#

+

Returned by tls.createSecurePair. + +

+

Event: 'secure'#

+

The event is emitted from the SecurePair once the pair has successfully +established a secure connection. + +

+

Similarly to the checking for the server 'secureConnection' event, +pair.cleartext.authorized should be checked to confirm whether the certificate +used properly authorized. + +

+

Class: tls.Server#

+

This class is a subclass of net.Server and has the same methods on it. +Instead of accepting just raw TCP connections, this accepts encrypted +connections using TLS or SSL. + +

+

Event: 'secureConnection'#

+

function (cleartextStream) {} + +

+

This event is emitted after a new connection has been successfully +handshaked. The argument is a instance of +CleartextStream. It has all the common stream methods +and events. + +

+

cleartextStream.authorized is a boolean value which indicates if the +client has verified by one of the supplied certificate authorities for the +server. If cleartextStream.authorized is false, then +cleartextStream.authorizationError is set to describe how authorization +failed. Implied but worth mentioning: depending on the settings of the TLS +server, you unauthorized connections may be accepted. +cleartextStream.npnProtocol is a string containing selected NPN protocol. +cleartextStream.servername is a string containing servername requested with +SNI. + + +

+

Event: 'clientError'#

+

function (exception) { } + +

+

When a client connection emits an 'error' event before secure connection is +established - it will be forwarded here. + + +

+

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

+

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). + +

+

This function is asynchronous. The last parameter callback will be called +when the server has been bound. + +

+

See net.Server for more information. + + +

+

server.close()#

+

Stops the server from accepting new connections. This function is +asynchronous, the server is finally closed when the server emits a 'close' +event. + +

+

server.address()#

+

Returns the bound address and port of the server as reported by the operating +system. +See net.Server.address() for more information. + +

+

server.addContext(hostname, credentials)#

+

Add secure context that will be used if client request's SNI hostname is +matching passed hostname (wildcards can be used). credentials can contain +key, cert and ca. + +

+

server.maxConnections#

+

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

+

server.connections#

+

The number of concurrent connections on the server. + + +

+

Class: tls.CleartextStream#

+

This is a stream on top of the Encrypted stream that makes it possible to +read/write an encrypted data as a cleartext data. + +

+

This instance implements a duplex Stream interfaces. +It has all the common stream methods and events. + +

+

A ClearTextStream is the clear member of a SecurePair object. + +

+

Event: 'secureConnect'#

+

This event is emitted after a new connection has been successfully handshaked. +The listener will be called no matter if the server's certificate was +authorized or not. It is up to the user to test cleartextStream.authorized +to see if the server certificate was signed by one of the specified CAs. +If cleartextStream.authorized === false then the error can be found in +cleartextStream.authorizationError. Also if NPN was used - you can check +cleartextStream.npnProtocol for negotiated protocol. + +

+

cleartextStream.authorized#

+

A boolean that is true if the peer certificate was signed by one of the +specified CAs, otherwise false + +

+

cleartextStream.authorizationError#

+

The reason why the peer's certificate has not been verified. This property +becomes available only when cleartextStream.authorized === false. + +

+

cleartextStream.getPeerCertificate()#

+

Returns an object representing the peer's certificate. The returned object has +some properties corresponding to the field of the certificate. + +

+

Example: + +

+
{ subject: 
+   { C: 'UK',
+     ST: 'Acknack Ltd',
+     L: 'Rhys Jones',
+     O: 'node.js',
+     OU: 'Test TLS Certificate',
+     CN: 'localhost' },
+  issuer: 
+   { C: 'UK',
+     ST: 'Acknack Ltd',
+     L: 'Rhys Jones',
+     O: 'node.js',
+     OU: 'Test TLS Certificate',
+     CN: 'localhost' },
+  valid_from: 'Nov 11 09:52:22 2009 GMT',
+  valid_to: 'Nov  6 09:52:22 2029 GMT',
+  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF' }
+

If the peer does not provide a certificate, it returns null or an empty +object. + +

+

cleartextStream.address()#

+

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

+

cleartextStream.remoteAddress#

+

The string representation of the remote IP address. For example, +'74.125.127.100' or '2001:4860:a005::68'. + +

+

cleartextStream.remotePort#

+

The numeric representation of the remote port. For example, 443. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/_toc.json @@ -0,0 +1,379 @@ +{ + "source": "doc/api/_toc.markdown", + "desc": [ + { + "type": "list_start", + "ordered": false + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[About these Docs](documentation.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Synopsis](synopsis.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Globals](globals.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[STDIO](stdio.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Timers](timers.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Modules](modules.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[C/C++ Addons](addons.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Process](process.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Utilities](util.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Events](events.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Buffer](buffer.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Stream](stream.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Crypto](crypto.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[TLS/SSL](tls.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[String Decoder](string_decoder.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[File System](fs.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Path](path.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Net](net.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[UDP/Datagram](dgram.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[DNS](dns.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[HTTP](http.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[HTTPS](https.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[URL](url.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Query Strings](querystring.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Readline](readline.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[REPL](repl.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[VM](vm.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Child Processes](child_process.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Assertion Testing](assert.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[TTY](tty.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[ZLIB](zlib.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[OS](os.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Debugger](debugger.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Cluster](cluster.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "Appendixes" + }, + { + "type": "list_start", + "ordered": false + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Appendix 1: Recommended Third-party Modules](appendix_1.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_end" + }, + { + "type": "list_item_end" + }, + { + "type": "list_end" + } + ] +} --- /dev/null +++ b/doc/api/modules.html @@ -0,0 +1,615 @@ + + + + + Modules Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Modules#

+
Stability: 5 - Locked
+ + +

Node has a simple module loading system. In Node, files and modules are in +one-to-one correspondence. As an example, foo.js loads the module +circle.js in the same directory. + +

+

The contents of foo.js: + +

+
var circle = require('./circle.js');
+console.log( 'The area of a circle of radius 4 is '
+           + circle.area(4));
+

The contents of circle.js: + +

+
var PI = Math.PI;
+
+exports.area = function (r) {
+  return PI * r * r;
+};
+
+exports.circumference = function (r) {
+  return 2 * PI * r;
+};
+

The module circle.js has exported the functions area() and +circumference(). To export an object, add to the special exports +object. + +

+

Variables +local to the module will be private. In this example the variable PI is +private to circle.js. + +

+

The module system is implemented in the require("module") module. + +

+

Cycles#

+ + +

When there are circular require() calls, a module might not be +done being executed when it is returned. + +

+

Consider this situation: + +

+

a.js: + +

+
console.log('a starting');
+exports.done = false;
+var b = require('./b.js');
+console.log('in a, b.done = %j', b.done);
+exports.done = true;
+console.log('a done');
+

b.js: + +

+
console.log('b starting');
+exports.done = false;
+var a = require('./a.js');
+console.log('in b, a.done = %j', a.done);
+exports.done = true;
+console.log('b done');
+

main.js: + +

+
console.log('main starting');
+var a = require('./a.js');
+var b = require('./b.js');
+console.log('in main, a.done=%j, b.done=%j', a.done, b.done);
+

When main.js loads a.js, then a.js in turn loads b.js. At that +point, b.js tries to load a.js. In order to prevent an infinite +loop an unfinished copy of the a.js exports object is returned to the +b.js module. b.js then finishes loading, and its exports object is +provided to the a.js module. + +

+

By the time main.js has loaded both modules, they're both finished. +The output of this program would thus be: + +

+
$ node main.js
+main starting
+a starting
+b starting
+in b, a.done = false
+b done
+in a, b.done = true
+a done
+in main, a.done=true, b.done=true
+

If you have cyclic module dependencies in your program, make sure to +plan accordingly. + +

+

Core Modules#

+ + +

Node has several modules compiled into the binary. These modules are +described in greater detail elsewhere in this documentation. + +

+

The core modules are defined in node's source in the lib/ folder. + +

+

Core modules are always preferentially loaded if their identifier is +passed to require(). For instance, require('http') will always +return the built in HTTP module, even if there is a file by that name. + +

+

File Modules#

+ + +

If the exact filename is not found, then node will attempt to load the +required filename with the added extension of .js, .json, and then .node. + +

+

.js files are interpreted as JavaScript text files, and .json files are +parsed as JSON text files. .node files are interpreted as compiled addon +modules loaded with dlopen. + +

+

A module prefixed with '/' is an absolute path to the file. For +example, require('/home/marco/foo.js') will load the file at +/home/marco/foo.js. + +

+

A module prefixed with './' is relative to the file calling require(). +That is, circle.js must be in the same directory as foo.js for +require('./circle') to find it. + +

+

Without a leading '/' or './' to indicate a file, the module is either a +"core module" or is loaded from a node_modules folder. + +

+

Loading from node_modules Folders#

+ + +

If the module identifier passed to require() is not a native module, +and does not begin with '/', '../', or './', then node starts at the +parent directory of the current module, and adds /node_modules, and +attempts to load the module from that location. + +

+

If it is not found there, then it moves to the parent directory, and so +on, until the root of the tree is reached. + +

+

For example, if the file at '/home/ry/projects/foo.js' called +require('bar.js'), then node would look in the following locations, in +this order: + +

+
    +
  • /home/ry/projects/node_modules/bar.js
    • +
  • /home/ry/node_modules/bar.js
    • +
  • /home/node_modules/bar.js
    • +
  • /node_modules/bar.js
    • +
+

This allows programs to localize their dependencies, so that they do not +clash. + +

+

Folders as Modules#

+ + +

It is convenient to organize programs and libraries into self-contained +directories, and then provide a single entry point to that library. +There are three ways in which a folder may be passed to require() as +an argument. + +

+

The first is to create a package.json file in the root of the folder, +which specifies a main module. An example package.json file might +look like this: + +

+
{ "name" : "some-library",
+  "main" : "./lib/some-library.js" }
+

If this was in a folder at ./some-library, then +require('./some-library') would attempt to load +./some-library/lib/some-library.js. + +

+

This is the extent of Node's awareness of package.json files. + +

+

If there is no package.json file present in the directory, then node +will attempt to load an index.js or index.node file out of that +directory. For example, if there was no package.json file in the above +example, then require('./some-library') would attempt to load: + +

+
    +
  • ./some-library/index.js
    • +
  • ./some-library/index.node
    • +
+

Caching#

+ + +

Modules are cached after the first time they are loaded. This means +(among other things) that every call to require('foo') will get +exactly the same object returned, if it would resolve to the same file. + +

+

Multiple calls to require('foo') may not cause the module code to be +executed multiple times. This is an important feature. With it, +"partially done" objects can be returned, thus allowing transitive +dependencies to be loaded even when they would cause cycles. + +

+

If you want to have a module execute code multiple times, then export a +function, and call that function. + +

+

Module Caching Caveats#

+ + +

Modules are cached based on their resolved filename. Since modules may +resolve to a different filename based on the location of the calling +module (loading from node_modules folders), it is not a guarantee +that require('foo') will always return the exact same object, if it +would resolve to different files. + +

+

The module Object#

+ + + +
    +
  • {Object}
    • +
+

In each module, the module free variable is a reference to the object +representing the current module. In particular +module.exports is the same as the exports object. +module isn't actually a global but rather local to each module. + +

+

module.exports#

+
    +
  • Object
    • +
+

The exports object is created by the Module system. Sometimes this is not +acceptable, many want their module to be an instance of some class. To do this +assign the desired export object to module.exports. For example suppose we +were making a module called a.js + +

+
var EventEmitter = require('events').EventEmitter;
+
+module.exports = new EventEmitter();
+
+// Do some work, and after some time emit
+// the 'ready' event from the module itself.
+setTimeout(function() {
+  module.exports.emit('ready');
+}, 1000);
+

Then in another file we could do + +

+
var a = require('./a');
+a.on('ready', function() {
+  console.log('module a is ready');
+});
+

Note that assignment to module.exports must be done immediately. It cannot be +done in any callbacks. This does not work: + +

+

x.js: + +

+
setTimeout(function() {
+  module.exports = { a: "hello" };
+}, 0);
+

y.js: + +

+
var x = require('./x');
+console.log(x.a);
+

module.require(id)#

+
    +
  • id String
    • +
  • Return: Object exports from the resolved module
    • +
+

The module.require method provides a way to load a module as if +require() was called from the original module. + +

+

Note that in order to do this, you must get a reference to the module +object. Since require() returns the exports, and the module is +typically only available within a specific module's code, it must be +explicitly exported in order to be used. + + +

+

module.id#

+
    +
  • String
    • +
+

The identifier for the module. Typically this is the fully resolved +filename. + + +

+

module.filename#

+
    +
  • String
    • +
+

The fully resolved filename to the module. + + +

+

module.loaded#

+
    +
  • Boolean
    • +
+

Whether or not the module is done loading, or is in the process of +loading. + + +

+

module.parent#

+
    +
  • Module Object
    • +
+

The module that required this one. + + +

+

module.children#

+
    +
  • Array
    • +
+

The module objects required by this one. + + + +

+

All Together...#

+ + +

To get the exact filename that will be loaded when require() is called, use +the require.resolve() function. + +

+

Putting together all of the above, here is the high-level algorithm +in pseudocode of what require.resolve does: + +

+
require(X) from module at path Y
+1. If X is a core module,
+   a. return the core module
+   b. STOP
+2. If X begins with './' or '/' or '../'
+   a. LOAD_AS_FILE(Y + X)
+   b. LOAD_AS_DIRECTORY(Y + X)
+3. LOAD_NODE_MODULES(X, dirname(Y))
+4. THROW "not found"
+
+LOAD_AS_FILE(X)
+1. If X is a file, load X as JavaScript text.  STOP
+2. If X.js is a file, load X.js as JavaScript text.  STOP
+3. If X.node is a file, load X.node as binary addon.  STOP
+
+LOAD_AS_DIRECTORY(X)
+1. If X/package.json is a file,
+   a. Parse X/package.json, and look for "main" field.
+   b. let M = X + (json main field)
+   c. LOAD_AS_FILE(M)
+2. If X/index.js is a file, load X/index.js as JavaScript text.  STOP
+3. If X/index.node is a file, load X/index.node as binary addon.  STOP
+
+LOAD_NODE_MODULES(X, START)
+1. let DIRS=NODE_MODULES_PATHS(START)
+2. for each DIR in DIRS:
+   a. LOAD_AS_FILE(DIR/X)
+   b. LOAD_AS_DIRECTORY(DIR/X)
+
+NODE_MODULES_PATHS(START)
+1. let PARTS = path split(START)
+2. let ROOT = index of first instance of "node_modules" in PARTS, or 0
+3. let I = count of PARTS - 1
+4. let DIRS = []
+5. while I > ROOT,
+   a. if PARTS[I] = "node_modules" CONTINUE
+   c. DIR = path join(PARTS[0 .. I] + "node_modules")
+   b. DIRS = DIRS + DIR
+   c. let I = I - 1
+6. return DIRS
+

Loading from the global folders#

+ + +

If the NODE_PATH environment variable is set to a colon-delimited list +of absolute paths, then node will search those paths for modules if they +are not found elsewhere. (Note: On Windows, NODE_PATH is delimited by +semicolons instead of colons.) + +

+

Additionally, node will search in the following locations: + +

+
    +
  • 1: $HOME/.node_modules
    • +
  • 2: $HOME/.node_libraries
    • +
  • 3: $PREFIX/lib/node
    • +
+

Where $HOME is the user's home directory, and $PREFIX is node's +configured installPrefix. + +

+

These are mostly for historic reasons. You are highly encouraged to +place your dependencies locally in node_modules folders. They will be +loaded faster, and more reliably. + +

+

Accessing the main module#

+ + +

When a file is run directly from Node, require.main is set to its +module. That means that you can determine whether a file has been run +directly by testing + +

+
require.main === module
+

For a file foo.js, this will be true if run via node foo.js, but +false if run by require('./foo'). + +

+

Because module provides a filename property (normally equivalent to +__filename), the entry point of the current application can be obtained +by checking require.main.filename. + +

+

Addenda: Package Manager Tips#

+ + +

The semantics of Node's require() function were designed to be general +enough to support a number of sane directory structures. Package manager +programs such as dpkg, rpm, and npm will hopefully find it possible to +build native packages from Node modules without modification. + +

+

Below we give a suggested directory structure that could work: + +

+

Let's say that we wanted to have the folder at +/usr/lib/node/<some-package>/<some-version> hold the contents of a +specific version of a package. + +

+

Packages can depend on one another. In order to install package foo, you +may have to install a specific version of package bar. The bar package +may itself have dependencies, and in some cases, these dependencies may even +collide or form cycles. + +

+

Since Node looks up the realpath of any modules it loads (that is, +resolves symlinks), and then looks for their dependencies in the +node_modules folders as described above, this situation is very simple to +resolve with the following architecture: + +

+
    +
  • /usr/lib/node/foo/1.2.3/ - Contents of the foo package, version 1.2.3.
    • +
  • /usr/lib/node/bar/4.3.2/ - Contents of the bar package that foo +depends on.
    • +
  • /usr/lib/node/foo/1.2.3/node_modules/bar - Symbolic link to +/usr/lib/node/bar/4.3.2/.
    • +
  • /usr/lib/node/bar/4.3.2/node_modules/* - Symbolic links to the packages +that bar depends on.
    • +
+

Thus, even if a cycle is encountered, or if there are dependency +conflicts, every module will be able to get a version of its dependency +that it can use. + +

+

When the code in the foo package does require('bar'), it will get the +version that is symlinked into /usr/lib/node/foo/1.2.3/node_modules/bar. +Then, when the code in the bar package calls require('quux'), it'll get +the version that is symlinked into +/usr/lib/node/bar/4.3.2/node_modules/quux. + +

+

Furthermore, to make the module lookup process even more optimal, rather +than putting packages directly in /usr/lib/node, we could put them in +/usr/lib/node_modules/<name>/<version>. Then node will not bother +looking for missing dependencies in /usr/node_modules or /node_modules. + +

+

In order to make modules available to the node REPL, it might be useful to +also add the /usr/lib/node_modules folder to the $NODE_PATH environment +variable. Since the module lookups using node_modules folders are all +relative, and based on the real path of the files making the calls to +require(), the packages themselves can be anywhere. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/child_process.html @@ -0,0 +1,515 @@ + + + + + Child Process Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Child Process#

+
Stability: 3 - Stable
+

Node provides a tri-directional popen(3) facility through the +child_process module. + +

+

It is possible to stream data through a child's stdin, stdout, and +stderr in a fully non-blocking way. + +

+

To create a child process use require('child_process').spawn() or +require('child_process').fork(). The semantics of each are slightly +different, and explained below. + +

+

Class: ChildProcess#

+

ChildProcess is an EventEmitter. + +

+

Child processes always have three streams associated with them. child.stdin, +child.stdout, and child.stderr. These may be shared with the stdio +streams of the parent process, or they may be separate stream objects +which can be piped to and from. + +

+

The ChildProcess class is not intended to be used directly. Use the +spawn() or fork() methods to create a Child Process instance. + +

+

Event: 'exit'#

+
    +
  • code Number the exit code, if it exited normally.
    • +
  • signal String the signal passed to kill the child process, if it +was killed by the parent.
    • +
+

This event is emitted after the child process ends. If the process terminated +normally, code is the final exit code of the process, otherwise null. If +the process terminated due to receipt of a signal, signal is the string name +of the signal, otherwise null. + +

+

See waitpid(2). + +

+

child.stdin#

+
    +
  • Stream object
    • +
+

A Writable Stream that represents the child process's stdin. +Closing this stream via end() often causes the child process to terminate. + +

+

If the child stdio streams are shared with the parent, then this will +not be set. + +

+

child.stdout#

+
    +
  • Stream object
    • +
+

A Readable Stream that represents the child process's stdout. + +

+

If the child stdio streams are shared with the parent, then this will +not be set. + +

+

child.stderr#

+
    +
  • Stream object
    • +
+

A Readable Stream that represents the child process's stderr. + +

+

If the child stdio streams are shared with the parent, then this will +not be set. + +

+

child.pid#

+
    +
  • Integer
    • +
+

The PID of the child process. + +

+

Example: + +

+
var spawn = require('child_process').spawn,
+    grep  = spawn('grep', ['ssh']);
+
+console.log('Spawned child pid: ' + grep.pid);
+grep.stdin.end();
+

child.kill([signal])#

+
    +
  • signal String
    • +
+

Send a signal to the child process. If no argument is given, the process will +be sent 'SIGTERM'. See signal(7) for a list of available signals. + +

+
var spawn = require('child_process').spawn,
+    grep  = spawn('grep', ['ssh']);
+
+grep.on('exit', function (code, signal) {
+  console.log('child process terminated due to receipt of signal '+signal);
+});
+
+// send SIGHUP to process
+grep.kill('SIGHUP');
+

Note that while the function is called kill, the signal delivered to the child +process may not actually kill it. kill really just sends a signal to a process. + +

+

See kill(2) + +

+

child.send(message, [sendHandle])#

+
    +
  • message Object
    • +
  • sendHandle Handle object
    • +
+

Send a message (and, optionally, a handle object) to a child process. + +

+

See child_process.fork() for details. + +

+

child_process.spawn(command, [args], [options])#

+
    +
  • command String The command to run
    • +
  • args Array List of string arguments
    • +
  • options Object
      +
    • cwd String Current working directory of the child process
      • +
    • customFds Array Deprecated File descriptors for the child to use +for stdio. (See below)
      • +
    • env Object Environment key-value pairs
      • +
    +
    • +
  • return: ChildProcess object
    • +
+

Launches a new process with the given command, with command line arguments in args. +If omitted, args defaults to an empty Array. + +

+

The third argument is used to specify additional options, which defaults to: + +

+
{ cwd: undefined,
+  env: process.env
+}
+

cwd allows you to specify the working directory from which the process is spawned. +Use env to specify environment variables that will be visible to the new process. + +

+

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code: + +

+
var util  = require('util'),
+    spawn = require('child_process').spawn,
+    ls    = spawn('ls', ['-lh', '/usr']);
+
+ls.stdout.on('data', function (data) {
+  console.log('stdout: ' + data);
+});
+
+ls.stderr.on('data', function (data) {
+  console.log('stderr: ' + data);
+});
+
+ls.on('exit', function (code) {
+  console.log('child process exited with code ' + code);
+});
+

Example: A very elaborate way to run 'ps ax | grep ssh' + +

+
var util  = require('util'),
+    spawn = require('child_process').spawn,
+    ps    = spawn('ps', ['ax']),
+    grep  = spawn('grep', ['ssh']);
+
+ps.stdout.on('data', function (data) {
+  grep.stdin.write(data);
+});
+
+ps.stderr.on('data', function (data) {
+  console.log('ps stderr: ' + data);
+});
+
+ps.on('exit', function (code) {
+  if (code !== 0) {
+    console.log('ps process exited with code ' + code);
+  }
+  grep.stdin.end();
+});
+
+grep.stdout.on('data', function (data) {
+  console.log(data);
+});
+
+grep.stderr.on('data', function (data) {
+  console.log('grep stderr: ' + data);
+});
+
+grep.on('exit', function (code) {
+  if (code !== 0) {
+    console.log('grep process exited with code ' + code);
+  }
+});
+

Example of checking for failed exec: + +

+
var spawn = require('child_process').spawn,
+    child = spawn('bad_command');
+
+child.stderr.setEncoding('utf8');
+child.stderr.on('data', function (data) {
+  if (/^execvp\(\)/.test(data)) {
+    console.log('Failed to start child process.');
+  }
+});
+

Note that if spawn receives an empty options object, it will result in +spawning the process with an empty environment rather than using +process.env. This due to backwards compatibility issues with a deprecated +API. + +

+

There is a deprecated option called customFds which allows one to specify +specific file descriptors for the stdio of the child process. This API was +not portable to all platforms and therefore removed. +With customFds it was possible to hook up the new process' [stdin, stdout, +stderr] to existing streams; -1 meant that a new stream should be created. +Use at your own risk. + +

+

There are several internal options. In particular stdinStream, +stdoutStream, stderrStream. They are for INTERNAL USE ONLY. As with all +undocumented APIs in Node, they should not be used. + +

+

See also: child_process.exec() and child_process.fork() + +

+

child_process.exec(command, [options], callback)#

+
    +
  • command String The command to run, with space-separated arguments
    • +
  • options Object
      +
    • cwd String Current working directory of the child process
      • +
    • customFds Array Deprecated File descriptors for the child to use +for stdio. (See below)
      • +
    • env Object Environment key-value pairs
      • +
    • encoding String (Default: 'utf8')
      • +
    • timeout Number (Default: 0)
      • +
    • maxBuffer Number (Default: 200*1024)
      • +
    • killSignal String (Default: 'SIGTERM')
      • +
    +
    • +
  • callback Function called with the output when process terminates
      +
    • error Error
      • +
    • stdout Buffer
      • +
    • stderr Buffer
      • +
    +
    • +
  • Return: ChildProcess object
    • +
+

Runs a command in a shell and buffers the output. + +

+
var util = require('util'),
+    exec = require('child_process').exec,
+    child;
+
+child = exec('cat *.js bad_file | wc -l',
+  function (error, stdout, stderr) {
+    console.log('stdout: ' + stdout);
+    console.log('stderr: ' + stderr);
+    if (error !== null) {
+      console.log('exec error: ' + error);
+    }
+});
+

The callback gets the arguments (error, stdout, stderr). On success, error +will be null. On error, error will be an instance of Error and err.code +will be the exit code of the child process, and err.signal will be set to the +signal that terminated the process. + +

+

There is a second optional argument to specify several options. The +default options are + +

+
{ encoding: 'utf8',
+  timeout: 0,
+  maxBuffer: 200*1024,
+  killSignal: 'SIGTERM',
+  cwd: null,
+  env: null }
+

If timeout is greater than 0, then it will kill the child process +if it runs longer than timeout milliseconds. The child process is killed with +killSignal (default: 'SIGTERM'). maxBuffer specifies the largest +amount of data allowed on stdout or stderr - if this value is exceeded then +the child process is killed. + + +

+

child_process.execFile(file, args, options, callback)#

+
    +
  • file String The filename of the program to run
    • +
  • args Array List of string arguments
    • +
  • options Object
      +
    • cwd String Current working directory of the child process
      • +
    • customFds Array Deprecated File descriptors for the child to use +for stdio. (See below)
      • +
    • env Object Environment key-value pairs
      • +
    • encoding String (Default: 'utf8')
      • +
    • timeout Number (Default: 0)
      • +
    • maxBuffer Number (Default: 200*1024)
      • +
    • killSignal String (Default: 'SIGTERM')
      • +
    +
    • +
  • callback Function called with the output when process terminates
      +
    • error Error
      • +
    • stdout Buffer
      • +
    • stderr Buffer
      • +
    +
    • +
  • Return: ChildProcess object
    • +
+

This is similar to child_process.exec() except it does not execute a +subshell but rather the specified file directly. This makes it slightly +leaner than child_process.exec. It has the same options. + + +

+

child_process.fork(modulePath, [args], [options])#

+
    +
  • modulePath String The module to run in the child
    • +
  • args Array List of string arguments
    • +
  • options Object
      +
    • cwd String Current working directory of the child process
      • +
    • customFds Array Deprecated File descriptors for the child to use +for stdio. (See below)
      • +
    • env Object Environment key-value pairs
      • +
    • encoding String (Default: 'utf8')
      • +
    • timeout Number (Default: 0)
      • +
    +
    • +
  • Return: ChildProcess object
    • +
+

This is a special case of the spawn() functionality for spawning Node +processes. In addition to having all the methods in a normal ChildProcess +instance, the returned object has a communication channel built-in. The +channel is written to with child.send(message, [sendHandle]) and messages +are received by a 'message' event on the child. + +

+

For example: + +

+
var cp = require('child_process');
+
+var n = cp.fork(__dirname + '/sub.js');
+
+n.on('message', function(m) {
+  console.log('PARENT got message:', m);
+});
+
+n.send({ hello: 'world' });
+

And then the child script, 'sub.js' might look like this: + +

+
process.on('message', function(m) {
+  console.log('CHILD got message:', m);
+});
+
+process.send({ foo: 'bar' });
+

In the child the process object will have a send() method, and process +will emit objects each time it receives a message on its channel. + +

+

By default the spawned Node process will have the stdin, stdout, stderr +associated with the parent's. + +

+

These child Nodes are still whole new instances of V8. Assume at least 30ms +startup and 10mb memory for each new Node. That is, you cannot create many +thousands of them. + +

+

The sendHandle option to child.send() is for sending a handle object to +another process. Child will receive the handle as as second argument to the +message event. Here is an example of sending a handle: + +

+
var server = require('net').createServer();
+var child = require('child_process').fork(__dirname + '/child.js');
+// Open up the server object and send the handle.
+server.listen(1337, function() {
+  child.send({ server: true }, server._handle);
+});
+

Here is an example of receiving the server handle and sharing it between +processes: + +

+
process.on('message', function(m, serverHandle) {
+  if (serverHandle) {
+    var server = require('net').createServer();
+    server.listen(serverHandle);
+  }
+});
+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/zlib.html @@ -0,0 +1,395 @@ + + + + + Zlib Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Zlib#

+
Stability: 3 - Stable
+

You can access this module with: + +

+
var zlib = require('zlib');
+

This provides bindings to Gzip/Gunzip, Deflate/Inflate, and +DeflateRaw/InflateRaw classes. Each class takes the same options, and +is a readable/writable Stream. + +

+

Examples#

+

Compressing or decompressing a file can be done by piping an +fs.ReadStream into a zlib stream, then into an fs.WriteStream. + +

+
var gzip = zlib.createGzip();
+var fs = require('fs');
+var inp = fs.createReadStream('input.txt');
+var out = fs.createWriteStream('input.txt.gz');
+
+inp.pipe(gzip).pipe(out);
+

Compressing or decompressing data in one step can be done by using +the convenience methods. + +

+
var input = '.................................';
+zlib.deflate(input, function(err, buffer) {
+  if (!err) {
+    console.log(buffer.toString('base64'));
+  }
+});
+
+var buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');
+zlib.unzip(buffer, function(err, buffer) {
+  if (!err) {
+    console.log(buffer.toString());
+  }
+});
+

To use this module in an HTTP client or server, use the +accept-encoding +on requests, and the +content-encoding +header on responses. + +

+

Note: these examples are drastically simplified to show +the basic concept. Zlib encoding can be expensive, and the results +ought to be cached. See Memory Usage Tuning +below for more information on the speed/memory/compression +tradeoffs involved in zlib usage. + +

+
// client request example
+var zlib = require('zlib');
+var http = require('http');
+var fs = require('fs');
+var request = http.get({ host: 'izs.me',
+                         path: '/',
+                         port: 80,
+                         headers: { 'accept-encoding': 'gzip,deflate' } });
+request.on('response', function(response) {
+  var output = fs.createWriteStream('izs.me_index.html');
+
+  switch (response.headers['content-encoding']) {
+    // or, just use zlib.createUnzip() to handle both cases
+    case 'gzip':
+      response.pipe(zlib.createGunzip()).pipe(output);
+      break;
+    case 'deflate':
+      response.pipe(zlib.createInflate()).pipe(output);
+      break;
+    default:
+      response.pipe(output);
+      break;
+  }
+});
+
+// server example
+// Running a gzip operation on every request is quite expensive.
+// It would be much more efficient to cache the compressed buffer.
+var zlib = require('zlib');
+var http = require('http');
+var fs = require('fs');
+http.createServer(function(request, response) {
+  var raw = fs.createReadStream('index.html');
+  var acceptEncoding = request.headers['accept-encoding'];
+  if (!acceptEncoding) {
+    acceptEncoding = '';
+  }
+
+  // Note: this is not a conformant accept-encoding parser.
+  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
+  if (acceptEncoding.match(/\bdeflate\b/)) {
+    response.writeHead(200, { 'content-encoding': 'deflate' });
+    raw.pipe(zlib.createDeflate()).pipe(response);
+  } else if (acceptEncoding.match(/\bgzip\b/)) {
+    response.writeHead(200, { 'content-encoding': 'gzip' });
+    raw.pipe(zlib.createGzip()).pipe(response);
+  } else {
+    response.writeHead(200, {});
+    raw.pipe(response);
+  }
+}).listen(1337);
+

Constants#

+ + +

All of the constants defined in zlib.h are also defined on +require('zlib'). They are described in more detail in the zlib +documentation. See http://zlib.net/manual.html#Constants +for more details. + +

+

zlib.createGzip([options])#

+

Returns a new Gzip object with an options. + +

+

zlib.createGunzip([options])#

+

Returns a new Gunzip object with an options. + +

+

zlib.createDeflate([options])#

+

Returns a new Deflate object with an options. + +

+

zlib.createInflate([options])#

+

Returns a new Inflate object with an options. + +

+

zlib.createDeflateRaw([options])#

+

Returns a new DeflateRaw object with an options. + +

+

zlib.createInflateRaw([options])#

+

Returns a new InflateRaw object with an options. + +

+

zlib.createUnzip([options])#

+

Returns a new Unzip object with an options. + + +

+

Class: zlib.Gzip#

+

Compress data using gzip. + +

+

Class: zlib.Gunzip#

+

Decompress a gzip stream. + +

+

Class: zlib.Deflate#

+

Compress data using deflate. + +

+

Class: zlib.Inflate#

+

Decompress a deflate stream. + +

+

Class: zlib.DeflateRaw#

+

Compress data using deflate, and do not append a zlib header. + +

+

Class: zlib.InflateRaw#

+

Decompress a raw deflate stream. + +

+

Class: zlib.Unzip#

+

Decompress either a Gzip- or Deflate-compressed stream by auto-detecting +the header. + +

+

Convenience Methods#

+ + +

All of these take a string or buffer as the first argument, and call the +supplied callback with callback(error, result). The +compression/decompression engine is created using the default settings +in all convenience methods. To supply different options, use the +zlib classes directly. + +

+

zlib.deflate(buf, callback)#

+

Compress a string with Deflate. + +

+

zlib.deflateRaw(buf, callback)#

+

Compress a string with DeflateRaw. + +

+

zlib.gzip(buf, callback)#

+

Compress a string with Gzip. + +

+

zlib.gunzip(buf, callback)#

+

Decompress a raw Buffer with Gunzip. + +

+

zlib.inflate(buf, callback)#

+

Decompress a raw Buffer with Inflate. + +

+

zlib.inflateRaw(buf, callback)#

+

Decompress a raw Buffer with InflateRaw. + +

+

zlib.unzip(buf, callback)#

+

Decompress a raw Buffer with Unzip. + +

+

Options#

+ + +

Each class takes an options object. All options are optional. (The +convenience methods use the default settings for all options.) + +

+

Note that some options are only +relevant when compressing, and are ignored by the decompression classes. + +

+
    +
  • chunkSize (default: 16*1024)
    • +
  • windowBits
    • +
  • level (compression only)
    • +
  • memLevel (compression only)
    • +
  • strategy (compression only)
    • +
+

See the description of deflateInit2 and inflateInit2 at +

+

http://zlib.net/manual.html#Advanced for more information on these. + +

+

Memory Usage Tuning#

+ + +

From zlib/zconf.h, modified to node's usage: + +

+

The memory requirements for deflate are (in bytes): + +

+
(1 << (windowBits+2)) +  (1 << (memLevel+9))
+

that is: 128K for windowBits=15 + 128K for memLevel = 8 +(default values) plus a few kilobytes for small objects. + +

+

For example, if you want to reduce +the default memory requirements from 256K to 128K, set the options to: + +

+
{ windowBits: 14, memLevel: 7 }
+

Of course this will generally degrade compression (there's no free lunch). + +

+

The memory requirements for inflate are (in bytes) + +

+
1 << windowBits
+

that is, 32K for windowBits=15 (default value) plus a few kilobytes +for small objects. + +

+

This is in addition to a single internal output slab buffer of size +chunkSize, which defaults to 16K. + +

+

The speed of zlib compression is affected most dramatically by the +level setting. A higher level will result in better compression, but +will take longer to complete. A lower level will result in less +compression, but will be much faster. + +

+

In general, greater memory usage options will mean that node has to make +fewer calls to zlib, since it'll be able to process more data in a +single write operation. So, this is another factor that affects the +speed, at the cost of memory usage. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/string_decoder.json @@ -0,0 +1,3 @@ +{ + "source": "doc/api/string_decoder.markdown" +} --- /dev/null +++ b/doc/api/dns.json @@ -0,0 +1,204 @@ +{ + "source": "doc/api/dns.markdown", + "modules": [ + { + "textRaw": "DNS", + "name": "dns", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Use require('dns') to access this module. All methods in the dns module\nuse C-Ares except for dns.lookup which uses getaddrinfo(3) in a thread\npool. C-Ares is much faster than getaddrinfo but the system resolver is\nmore constant with how other programs operate. When a user does\nnet.connect(80, 'google.com') or http.get({ host: 'google.com' }) the\ndns.lookup method is used. Users who need to do a large number of look ups\nquickly should use the methods that go through C-Ares.\n\n

\n

Here is an example which resolves 'www.google.com' then reverse\nresolves the IP addresses which are returned.\n\n

\n
var dns = require('dns');\n\ndns.resolve4('www.google.com', function (err, addresses) {\n  if (err) throw err;\n\n  console.log('addresses: ' + JSON.stringify(addresses));\n\n  addresses.forEach(function (a) {\n    dns.reverse(a, function (err, domains) {\n      if (err) {\n        console.log('reverse for ' + a + ' failed: ' +\n          err.message);\n      } else {\n        console.log('reverse for ' + a + ': ' +\n          JSON.stringify(domains));\n      }\n    });\n  });\n});
\n", + "methods": [ + { + "textRaw": "dns.lookup(domain, [family], callback)", + "type": "method", + "name": "lookup", + "desc": "

Resolves a domain (e.g. 'google.com') into the first found A (IPv4) or\nAAAA (IPv6) record.\nThe family can be the integer 4 or 6. Defaults to null that indicates\nboth Ip v4 and v6 address family.\n\n

\n

The callback has arguments (err, address, family). The address argument\nis a string representation of a IP v4 or v6 address. The family argument\nis either the integer 4 or 6 and denotes the family of address (not\nnecessarily the value initially passed to lookup).\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "family", + "optional": true + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolve(domain, [rrtype], callback)", + "type": "method", + "name": "resolve", + "desc": "

Resolves a domain (e.g. 'google.com') into an array of the record types\nspecified by rrtype. Valid rrtypes are 'A' (IPV4 addresses, default),\n'AAAA' (IPV6 addresses), 'MX' (mail exchange records), 'TXT' (text\nrecords), 'SRV' (SRV records), 'PTR' (used for reverse IP lookups),\n'NS' (name server records) and 'CNAME' (canonical name records).\n\n

\n

The callback has arguments (err, addresses). The type of each item\nin addresses is determined by the record type, and described in the\ndocumentation for the corresponding lookup methods below.\n\n

\n

On error, err would be an instanceof Error object, where err.errno is\none of the error codes listed below and err.message is a string describing\nthe error in English.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "rrtype", + "optional": true + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolve4(domain, callback)", + "type": "method", + "name": "resolve4", + "desc": "

The same as dns.resolve(), but only for IPv4 queries (A records).\naddresses is an array of IPv4 addresses (e.g.\n['74.125.79.104', '74.125.79.105', '74.125.79.106']).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolve6(domain, callback)", + "type": "method", + "name": "resolve6", + "desc": "

The same as dns.resolve4() except for IPv6 queries (an AAAA query).\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolveMx(domain, callback)", + "type": "method", + "name": "resolveMx", + "desc": "

The same as dns.resolve(), but only for mail exchange queries (MX records).\n\n

\n

addresses is an array of MX records, each with a priority and an exchange\nattribute (e.g. [{'priority': 10, 'exchange': 'mx.example.com'},...]).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolveTxt(domain, callback)", + "type": "method", + "name": "resolveTxt", + "desc": "

The same as dns.resolve(), but only for text queries (TXT records).\naddresses is an array of the text records available for domain (e.g.,\n['v=spf1 ip4:0.0.0.0 ~all']).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolveSrv(domain, callback)", + "type": "method", + "name": "resolveSrv", + "desc": "

The same as dns.resolve(), but only for service records (SRV records).\naddresses is an array of the SRV records available for domain. Properties\nof SRV records are priority, weight, port, and name (e.g.,\n[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.reverse(ip, callback)", + "type": "method", + "name": "reverse", + "desc": "

Reverse resolves an ip address to an array of domain names.\n\n

\n

The callback has arguments (err, domains).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "ip" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolveNs(domain, callback)", + "type": "method", + "name": "resolveNs", + "desc": "

The same as dns.resolve(), but only for name server records (NS records).\naddresses is an array of the name server records available for domain\n(e.g., ['ns1.example.com', 'ns2.example.com']).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolveCname(domain, callback)", + "type": "method", + "name": "resolveCname", + "desc": "

The same as dns.resolve(), but only for canonical name records (CNAME\nrecords). addresses is an array of the canonical name records available for\ndomain (e.g., ['bar.example.com']).\n\n

\n

If there an an error, err will be non-null and an instanceof the Error\nobject.\n\n

\n

Each DNS query can return an error code.\n\n

\n
    \n
  • dns.TEMPFAIL: timeout, SERVFAIL or similar.
    • \n
  • dns.PROTOCOL: got garbled reply.
    • \n
  • dns.NXDOMAIN: domain does not exists.
    • \n
  • dns.NODATA: domain exists but no data of reqd type.
    • \n
  • dns.NOMEM: out of memory while processing.
    • \n
  • dns.BADQUERY: the query is malformed.
    • \n
\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "DNS" + } + ] +} --- /dev/null +++ b/doc/api/net.json @@ -0,0 +1,558 @@ +{ + "source": "doc/api/net.markdown", + "modules": [ + { + "textRaw": "net", + "name": "net", + "stability": 3, + "stabilityText": "Stable", + "desc": "

The net module provides you with an asynchronous network wrapper. It contains\nmethods for creating both servers and clients (called streams). You can include\nthis module with require('net');\n\n

\n", + "methods": [ + { + "textRaw": "net.createServer([options], [connectionListener])", + "type": "method", + "name": "createServer", + "desc": "

Creates a new TCP server. The connectionListener argument is\nautomatically set as a listener for the 'connection'\nevent.\n\n

\n

options is an object with the following defaults:\n\n

\n
{ allowHalfOpen: false\n}
\n

If allowHalfOpen is true, then the socket won't automatically send FIN\npacket when the other end of the socket sends a FIN packet. The socket becomes\nnon-readable, but still writable. You should call the end() method explicitly.\nSee 'end' event for more information.\n\n

\n

Here is an example of a echo server which listens for connections\non port 8124:\n\n

\n
var net = require('net');\nvar server = net.createServer(function(c) { //'connection' listener\n  console.log('server connected');\n  c.on('end', function() {\n    console.log('server disconnected');\n  });\n  c.write('hello\\r\\n');\n  c.pipe(c);\n});\nserver.listen(8124, function() { //'listening' listener\n  console.log('server bound');\n});
\n

Test this by using telnet:\n\n

\n
telnet localhost 8124
\n

To listen on the socket /tmp/echo.sock the third line from the last would\njust be changed to\n\n

\n
server.listen('/tmp/echo.sock', function() { //'listening' listener
\n

Use nc to connect to a UNIX domain socket server:\n\n

\n
nc -U /tmp/echo.sock
\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + }, + { + "name": "connectionListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "net.connect(arguments...)", + "type": "method", + "name": "connect", + "desc": "

Construct a new socket object and opens a socket to the given location. When\nthe socket is established the 'connect' event will be\nemitted.\n\n

\n

The arguments for these methods change the type of connection:\n\n

\n
    \n
  • net.connect(port, [host], [connectListener])
    • \n

  • net.createConnection(port, [host], [connectListener])

    \n

    Creates a TCP connection to port on host. If host is omitted,\n'localhost' will be assumed.

    \n
    • \n

  • net.connect(path, [connectListener])

    \n
    • \n

  • net.createConnection(path, [connectListener])

    \n

    Creates unix socket connection to path.

    \n
    • \n
\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n

\n

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

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

To connect on the socket /tmp/echo.sock the second line would just be\nchanged to\n\n

\n
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
\n", + "signatures": [ + { + "params": [ + { + "name": "arguments..." + } + ] + }, + { + "params": [ + { + "name": "arguments..." + } + ] + } + ] + }, + { + "textRaw": "net.createConnection(arguments...)", + "type": "method", + "name": "createConnection", + "desc": "

Construct a new socket object and opens a socket to the given location. When\nthe socket is established the 'connect' event will be\nemitted.\n\n

\n

The arguments for these methods change the type of connection:\n\n

\n
    \n
  • net.connect(port, [host], [connectListener])
    • \n

  • net.createConnection(port, [host], [connectListener])

    \n

    Creates a TCP connection to port on host. If host is omitted,\n'localhost' will be assumed.

    \n
    • \n

  • net.connect(path, [connectListener])

    \n
    • \n

  • net.createConnection(path, [connectListener])

    \n

    Creates unix socket connection to path.

    \n
    • \n
\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n

\n

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

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

To connect on the socket /tmp/echo.sock the second line would just be\nchanged to\n\n

\n
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
\n", + "signatures": [ + { + "params": [ + { + "name": "arguments..." + } + ] + } + ] + }, + { + "textRaw": "net.isIP(input)", + "type": "method", + "name": "isIP", + "desc": "

Tests if input is an IP address. Returns 0 for invalid strings,\nreturns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "input" + } + ] + } + ] + }, + { + "textRaw": "net.isIPv4(input)", + "type": "method", + "name": "isIPv4", + "desc": "

Returns true if input is a version 4 IP address, otherwise returns false.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "input" + } + ] + } + ] + }, + { + "textRaw": "net.isIPv6(input)", + "type": "method", + "name": "isIPv6", + "desc": "

Returns true if input is a version 6 IP address, otherwise returns false.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "input" + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: net.Server", + "type": "class", + "name": "net.Server", + "desc": "

This class is used to create a TCP or UNIX server.\nA server is a net.Socket that can listen for new incoming connections.\n\n

\n", + "methods": [ + { + "textRaw": "server.listen(port, [host], [listeningListener])", + "type": "method", + "name": "listen", + "desc": "

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

\n

This function is asynchronous. When the server has been bound,\n'listening' event will be emitted.\nthe last parameter listeningListener will be added as an listener for the\n'listening' event.\n\n

\n

One issue some users run into is getting EADDRINUSE errors. This means that\nanother server is already running on the requested port. One way of handling this\nwould be to wait a second and then try again. This can be done with\n\n

\n
server.on('error', function (e) {\n  if (e.code == 'EADDRINUSE') {\n    console.log('Address in use, retrying...');\n    setTimeout(function () {\n      server.close();\n      server.listen(PORT, HOST);\n    }, 1000);\n  }\n});
\n

(Note: All sockets in Node set SO_REUSEADDR already)\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "port" + }, + { + "name": "host", + "optional": true + }, + { + "name": "listeningListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "server.listen(path, [listeningListener])", + "type": "method", + "name": "listen", + "desc": "

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

\n

This function is asynchronous. When the server has been bound,\n'listening' event will be emitted.\nthe last parameter listeningListener will be added as an listener for the\n'listening' event.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "listeningListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "server.close()", + "type": "method", + "name": "close", + "desc": "

Stops the server from accepting new connections. This function is\nasynchronous, the server is finally closed when the server emits a 'close'\nevent.\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "server.address()", + "type": "method", + "name": "address", + "desc": "

Returns the bound address and port of the server as reported by the operating system.\nUseful to find which port was assigned when giving getting an OS-assigned address.\nReturns an object with two properties, e.g. {"address":"127.0.0.1", "port":2121}\n\n

\n

Example:\n\n

\n
var server = net.createServer(function (socket) {\n  socket.end("goodbye\\n");\n});\n\n// grab a random port.\nserver.listen(function() {\n  address = server.address();\n  console.log("opened server on %j", address);\n});
\n

Don't call server.address() until the 'listening' event has been emitted.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "properties": [ + { + "textRaw": "server.maxConnections", + "name": "maxConnections", + "desc": "

Set this property to reject connections when the server's connection count gets\nhigh.\n\n

\n" + }, + { + "textRaw": "server.connections", + "name": "connections", + "desc": "

The number of concurrent connections on the server.\n\n\n

\n

net.Server is an EventEmitter with the following events:\n\n

\n" + } + ], + "events": [ + { + "textRaw": "Event: 'listening'", + "type": "event", + "name": "listening", + "desc": "

Emitted when the server has been bound after calling server.listen.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'connection'", + "type": "event", + "name": "connection", + "params": [], + "desc": "

Emitted when a new connection is made. socket is an instance of\nnet.Socket.\n\n

\n" + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

Emitted when the server closes.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "params": [], + "desc": "

Emitted when an error occurs. The 'close' event will be called directly\nfollowing this event. See example in discussion of server.listen.\n\n

\n" + } + ] + }, + { + "textRaw": "Class: net.Socket", + "type": "class", + "name": "net.Socket", + "desc": "

This object is an abstraction of a TCP or UNIX socket. net.Socket\ninstances implement a duplex Stream interface. They can be created by the\nuser and used as a client (with connect()) or they can be created by Node\nand passed to the user through the 'connection' event of a server.\n\n

\n", + "methods": [ + { + "textRaw": "new net.Socket([options])", + "type": "method", + "name": "Socket", + "desc": "

Construct a new socket object.\n\n

\n

options is an object with the following defaults:\n\n

\n
{ fd: null\n  type: null\n  allowHalfOpen: false\n}
\n

fd allows you to specify the existing file descriptor of socket. type\nspecified underlying protocol. It can be 'tcp4', 'tcp6', or 'unix'.\nAbout allowHalfOpen, refer to createServer() and 'end' event.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.connect(port, [host], [connectListener])", + "type": "method", + "name": "connect", + "desc": "

Opens the connection for a given socket. If port and host are given,\nthen the socket will be opened as a TCP socket, if host is omitted,\nlocalhost will be assumed. If a path is given, the socket will be\nopened as a unix socket to that path.\n\n

\n

Normally this method is not needed, as net.createConnection opens the\nsocket. Use this only if you are implementing a custom Socket or if a\nSocket is closed and you want to reuse it to connect to another server.\n\n

\n

This function is asynchronous. When the 'connect' event is\nemitted the socket is established. If there is a problem connecting, the\n'connect' event will not be emitted, the 'error' event will be emitted with\nthe exception.\n\n

\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "connectListener", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "port" + }, + { + "name": "host", + "optional": true + }, + { + "name": "connectListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.connect(path, [connectListener])", + "type": "method", + "name": "connect", + "desc": "

Opens the connection for a given socket. If port and host are given,\nthen the socket will be opened as a TCP socket, if host is omitted,\nlocalhost will be assumed. If a path is given, the socket will be\nopened as a unix socket to that path.\n\n

\n

Normally this method is not needed, as net.createConnection opens the\nsocket. Use this only if you are implementing a custom Socket or if a\nSocket is closed and you want to reuse it to connect to another server.\n\n

\n

This function is asynchronous. When the 'connect' event is\nemitted the socket is established. If there is a problem connecting, the\n'connect' event will not be emitted, the 'error' event will be emitted with\nthe exception.\n\n

\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "connectListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.setEncoding([encoding])", + "type": "method", + "name": "setEncoding", + "desc": "

Sets the encoding (either 'ascii', 'utf8', or 'base64') for data that is\nreceived. Defaults to null.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.setSecure()", + "type": "method", + "name": "setSecure", + "desc": "

This function has been removed in v0.3. It used to upgrade the connection to\nSSL/TLS. See the TLS section for the new API.\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "socket.write(data, [encoding], [callback])", + "type": "method", + "name": "write", + "desc": "

Sends data on the socket. The second parameter specifies the encoding in the\ncase of a string--it defaults to UTF8 encoding.\n\n

\n

Returns true if the entire data was flushed successfully to the kernel\nbuffer. Returns false if all or part of the data was queued in user memory.\n'drain' will be emitted when the buffer is again free.\n\n

\n

The optional callback parameter will be executed when the data is finally\nwritten out - this may not be immediately.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + }, + { + "name": "encoding", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.end([data], [encoding])", + "type": "method", + "name": "end", + "desc": "

Half-closes the socket. i.e., it sends a FIN packet. It is possible the\nserver will still send some data.\n\n

\n

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

\n", + "signatures": [ + { + "params": [ + { + "name": "data", + "optional": true + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.destroy()", + "type": "method", + "name": "destroy", + "desc": "

Ensures that no more I/O activity happens on this socket. Only necessary in\ncase of errors (parse error or so).\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "socket.pause()", + "type": "method", + "name": "pause", + "desc": "

Pauses the reading of data. That is, 'data' events will not be emitted.\nUseful to throttle back an upload.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "socket.resume()", + "type": "method", + "name": "resume", + "desc": "

Resumes reading after a call to pause().\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "socket.setTimeout(timeout, [callback])", + "type": "method", + "name": "setTimeout", + "desc": "

Sets the socket to timeout after timeout milliseconds of inactivity on\nthe socket. By default net.Socket do not have a timeout.\n\n

\n

When an idle timeout is triggered the socket will receive a 'timeout'\nevent but the connection will not be severed. The user must manually end()\nor destroy() the socket.\n\n

\n

If timeout is 0, then the existing idle timeout is disabled.\n\n

\n

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

\n", + "signatures": [ + { + "params": [ + { + "name": "timeout" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.setNoDelay([noDelay])", + "type": "method", + "name": "setNoDelay", + "desc": "

Disables the Nagle algorithm. By default TCP connections use the Nagle\nalgorithm, they buffer data before sending it off. Setting true for\nnoDelay will immediately fire off data each time socket.write() is called.\nnoDelay defaults to true.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "noDelay", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.setKeepAlive([enable], [initialDelay])", + "type": "method", + "name": "setKeepAlive", + "desc": "

Enable/disable keep-alive functionality, and optionally set the initial\ndelay before the first keepalive probe is sent on an idle socket.\nenable defaults to false.\n\n

\n

Set initialDelay (in milliseconds) to set the delay between the last\ndata packet received and the first keepalive probe. Setting 0 for\ninitialDelay will leave the value unchanged from the default\n(or previous) setting. Defaults to 0.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "enable", + "optional": true + }, + { + "name": "initialDelay", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.address()", + "type": "method", + "name": "address", + "desc": "

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

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "properties": [ + { + "textRaw": "socket.bufferSize", + "name": "bufferSize", + "desc": "

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

\n

The consequence of this internal buffering is that memory may grow. This\nproperty shows the number of characters currently buffered to be written.\n(Number of characters is approximately equal to the number of bytes to be\nwritten, but the buffer may contain strings, and the strings are lazily\nencoded, so the exact number of bytes is not known.)\n\n

\n

Users who experience large or growing bufferSize should attempt to\n"throttle" the data flows in their program with pause() and resume().\n\n\n

\n" + }, + { + "textRaw": "socket.remoteAddress", + "name": "remoteAddress", + "desc": "

The string representation of the remote IP address. For example,\n'74.125.127.100' or '2001:4860:a005::68'.\n\n

\n" + }, + { + "textRaw": "socket.remotePort", + "name": "remotePort", + "desc": "

The numeric representation of the remote port. For example,\n80 or 21.\n\n

\n" + }, + { + "textRaw": "socket.bytesRead", + "name": "bytesRead", + "desc": "

The amount of received bytes.\n\n

\n" + }, + { + "textRaw": "socket.bytesWritten", + "name": "bytesWritten", + "desc": "

The amount of bytes sent.\n\n\n

\n

net.Socket instances are EventEmitters with the following events:\n\n

\n" + } + ], + "events": [ + { + "textRaw": "Event: 'connect'", + "type": "event", + "name": "connect", + "desc": "

Emitted when a socket connection is successfully established.\nSee connect().\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'data'", + "type": "event", + "name": "data", + "params": [], + "desc": "

Emitted when data is received. The argument data will be a Buffer or\nString. Encoding of data is set by socket.setEncoding().\n(See the Readable Stream section for more\ninformation.)\n\n

\n

Note that the data will be lost if there is no listener when a Socket\nemits a 'data' event.\n\n

\n" + }, + { + "textRaw": "Event: 'end'", + "type": "event", + "name": "end", + "desc": "

Emitted when the other end of the socket sends a FIN packet.\n\n

\n

By default (allowHalfOpen == false) the socket will destroy its file\ndescriptor once it has written out its pending write queue. However, by\nsetting allowHalfOpen == true the socket will not automatically end()\nits side allowing the user to write arbitrary amounts of data, with the\ncaveat that the user is required to end() their side now.\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'timeout'", + "type": "event", + "name": "timeout", + "desc": "

Emitted if the socket times out from inactivity. This is only to notify that\nthe socket has been idle. The user must manually close the connection.\n\n

\n

See also: socket.setTimeout()\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'drain'", + "type": "event", + "name": "drain", + "desc": "

Emitted when the write buffer becomes empty. Can be used to throttle uploads.\n\n

\n

See also: the return values of socket.write()\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "params": [], + "desc": "

Emitted when an error occurs. The 'close' event will be called directly\nfollowing this event.\n\n

\n" + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "params": [], + "desc": "

Emitted once the socket is fully closed. The argument had_error is a boolean\nwhich says if the socket was closed due to a transmission error.\n\n

\n" + } + ] + } + ], + "type": "module", + "displayName": "net" + } + ] +} --- /dev/null +++ b/doc/api/synopsis.html @@ -0,0 +1,113 @@ + + + + + Synopsis Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ +
+

Table of Contents

+ + +
+ +
+

Synopsis#

+ + +

An example of a web server written with Node which responds with 'Hello +World': + +

+
var http = require('http');
+
+http.createServer(function (request, response) {
+  response.writeHead(200, {'Content-Type': 'text/plain'});
+  response.end('Hello World\n');
+}).listen(8124);
+
+console.log('Server running at http://127.0.0.1:8124/');
+

To run the server, put the code into a file called example.js and execute +it with the node program + +

+
> node example.js
+Server running at http://127.0.0.1:8124/
+

All of the examples in the documentation can be run similarly. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/events.json @@ -0,0 +1,187 @@ +{ + "source": "doc/api/events.markdown", + "modules": [ + { + "textRaw": "Events", + "name": "Events", + "stability": 4, + "stabilityText": "API Frozen", + "type": "module", + "desc": "

Many objects in Node emit events: a net.Server emits an event each time\na peer connects to it, a fs.readStream emits an event when the file is\nopened. All objects which emit events are instances of events.EventEmitter.\nYou can access this module by doing: require("events");\n\n

\n

Typically, event names are represented by a camel-cased string, however,\nthere aren't any strict restrictions on that, as any string will be accepted.\n\n

\n

Functions can then be attached to objects, to be executed when an event\nis emitted. These functions are called listeners.\n\n\n

\n", + "classes": [ + { + "textRaw": "Class: events.EventEmitter", + "type": "class", + "name": "events.EventEmitter", + "desc": "

To access the EventEmitter class, require('events').EventEmitter.\n\n

\n

When an EventEmitter instance experiences an error, the typical action is\nto emit an 'error' event. Error events are treated as a special case in node.\nIf there is no listener for it, then the default action is to print a stack\ntrace and exit the program.\n\n

\n

All EventEmitters emit the event 'newListener' when new listeners are\nadded.\n\n

\n", + "methods": [ + { + "textRaw": "emitter.addListener(event, listener)", + "type": "method", + "name": "addListener", + "desc": "

Adds a listener to the end of the listeners array for the specified event.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "event" + }, + { + "name": "listener" + } + ] + }, + { + "params": [ + { + "name": "event" + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "emitter.on(event, listener)", + "type": "method", + "name": "on", + "desc": "

Adds a listener to the end of the listeners array for the specified event.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "event" + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "emitter.once(event, listener)", + "type": "method", + "name": "once", + "desc": "

Adds a one time listener for the event. This listener is\ninvoked only the next time the event is fired, after which\nit is removed.\n\n

\n
server.once('connection', function (stream) {\n  console.log('Ah, we have our first user!');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "event" + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "emitter.removeListener(event, listener)", + "type": "method", + "name": "removeListener", + "desc": "

Remove a listener from the listener array for the specified event.\nCaution: changes array indices in the listener array behind the listener.\n\n

\n
var callback = function(stream) {\n  console.log('someone connected!');\n};\nserver.on('connection', callback);\n// ...\nserver.removeListener('connection', callback);
\n", + "signatures": [ + { + "params": [ + { + "name": "event" + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "emitter.removeAllListeners([event])", + "type": "method", + "name": "removeAllListeners", + "desc": "

Removes all listeners, or those of the specified event.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "event", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "emitter.setMaxListeners(n)", + "type": "method", + "name": "setMaxListeners", + "desc": "

By default EventEmitters will print a warning if more than 10 listeners are\nadded for a particular event. This is a useful default which helps finding memory leaks.\nObviously not all Emitters should be limited to 10. This function allows\nthat to be increased. Set to zero for unlimited.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "n" + } + ] + } + ] + }, + { + "textRaw": "emitter.listeners(event)", + "type": "method", + "name": "listeners", + "desc": "

Returns an array of listeners for the specified event. This array can be\nmanipulated, e.g. to remove listeners.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});\nconsole.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
\n", + "signatures": [ + { + "params": [ + { + "name": "event" + } + ] + } + ] + }, + { + "textRaw": "emitter.emit(event, [arg1], [arg2], [...])", + "type": "method", + "name": "emit", + "desc": "

Execute each of the listeners in order with the supplied arguments.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "event" + }, + { + "name": "arg1", + "optional": true + }, + { + "name": "arg2", + "optional": true + }, + { + "name": "...", + "optional": true + } + ] + } + ] + } + ], + "events": [ + { + "textRaw": "Event: 'newListener'", + "type": "event", + "name": "newListener", + "params": [], + "desc": "

This event is emitted any time someone adds a new listener.\n

\n" + } + ] + } + ] + } + ] +} --- /dev/null +++ b/doc/api/appendix_1.html @@ -0,0 +1,138 @@ + + + + + Appendix 1 - Third Party Modules Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ +
+

Table of Contents

+ + +
+ +
+

Appendix 1 - Third Party Modules#

+

There are many third party modules for Node. At the time of writing, August +2010, the master repository of modules is +the wiki page. + +

+

This appendix is intended as a SMALL guide to new-comers to help them +quickly find what are considered to be quality modules. It is not intended +to be a complete list. There may be better more complete modules found +elsewhere. + +

+ +

Patches to this list are welcome. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/buffer.html @@ -0,0 +1,837 @@ + + + + + Buffer Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ +
+

Table of Contents

+ + +
+ +
+

Buffer#

+
Stability: 3 - Stable
+

Pure Javascript is Unicode friendly but not nice to binary data. When +dealing with TCP streams or the file system, it's necessary to handle octet +streams. Node has several strategies for manipulating, creating, and +consuming octet streams. + +

+

Raw data is stored in instances of the Buffer class. A Buffer is similar +to an array of integers but corresponds to a raw memory allocation outside +the V8 heap. A Buffer cannot be resized. + +

+

The Buffer class is a global, making it very rare that one would need +to ever require('buffer'). + +

+

Converting between Buffers and JavaScript string objects requires an explicit +encoding method. Here are the different string encodings. + +

+
    +

  • 'ascii' - for 7 bit ASCII data only. This encoding method is very fast, and +will strip the high bit if set. +Note that this encoding converts a null character ('\0' or '\u0000') into +0x20 (character code of a space). If you want to convert a null character +into 0x00, you should use 'utf8'.

    +
    • +

  • 'utf8' - Multi byte encoded Unicode characters. Many web pages and other document formats use UTF-8.

    +
    • +

  • 'ucs2' - 2-bytes, little endian encoded Unicode characters. It can encode +only BMP(Basic Multilingual Plane, U+0000 - U+FFFF).

    +
    • +

  • 'base64' - Base64 string encoding.

    +
    • +

  • 'binary' - A way of encoding raw binary data into strings by using only +the first 8 bits of each character. This encoding method is deprecated and +should be avoided in favor of Buffer objects where possible. This encoding +will be removed in future versions of Node.

    +
    • +

  • 'hex' - Encode each byte as two hexidecimal characters.

    +
    • +
+

Class: Buffer#

+

The Buffer class is a global type for dealing with binary data directly. +It can be constructed in a variety of ways. + +

+

new Buffer(size)#

+
    +
  • size Number
    • +
+

Allocates a new buffer of size octets. + +

+

new Buffer(array)#

+
    +
  • array Array
    • +
+

Allocates a new buffer using an array of octets. + +

+

new Buffer(str, [encoding])#

+
    +
  • str String - string to encode.
    • +
  • encoding String - encoding to use, Optional.
    • +
+

Allocates a new buffer containing the given str. +encoding defaults to 'utf8'. + +

+

buf.write(string, [offset], [length], [encoding])#

+
    +
  • string String - data to be written to buffer
    • +
  • offset Number, Optional, Default: 0
    • +
  • length Number, Optional, Default: buffer.length - offset
    • +
  • encoding String, Optional, Default: 'utf8'
    • +
+

Writes string to the buffer at offset using the given encoding. +offset defaults to 0, encoding defaults to 'utf8'. length is +the number of bytes to write. Returns number of octets written. If buffer did +not contain enough space to fit the entire string, it will write a partial +amount of the string. length defaults to buffer.length - offset. +The method will not write partial characters. + +

+
buf = new Buffer(256);
+len = buf.write('\u00bd + \u00bc = \u00be', 0);
+console.log(len + " bytes: " + buf.toString('utf8', 0, len));
+

The number of characters written (which may be different than the number of +bytes written) is set in Buffer._charsWritten and will be overwritten the +next time buf.write() is called. + + +

+

buf.toString([encoding], [start], [end])#

+
    +
  • encoding String, Optional, Default: 'utf8'
    • +
  • start Number, Optional, Default: 0
    • +
  • end Number, Optional, Default: buffer.length
    • +
+

Decodes and returns a string from buffer data encoded with encoding +(defaults to 'utf8') beginning at start (defaults to 0) and ending at +end (defaults to buffer.length). + +

+

See buffer.write() example, above. + + +

+

buf[index]#

+ + + +

Get and set the octet at index. The values refer to individual bytes, +so the legal range is between 0x00 and 0xFF hex or 0 and 255. + +

+

Example: copy an ASCII string into a buffer, one byte at a time: + +

+
str = "node.js";
+buf = new Buffer(str.length);
+
+for (var i = 0; i < str.length ; i++) {
+  buf[i] = str.charCodeAt(i);
+}
+
+console.log(buf);
+
+// node.js
+

Class Method: Buffer.isBuffer(obj)#

+
    +
  • obj Object
    • +
  • Return: Boolean
    • +
+

Tests if obj is a Buffer. + +

+

Class Method: Buffer.byteLength(string, [encoding])#

+
    +
  • string String
    • +
  • encoding String, Optional, Default: 'utf8'
    • +
  • Return: Number
    • +
+

Gives the actual byte length of a string. encoding defaults to 'utf8'. +This is not the same as String.prototype.length since that returns the +number of characters in a string. + +

+

Example: + +

+
str = '\u00bd + \u00bc = \u00be';
+
+console.log(str + ": " + str.length + " characters, " +
+  Buffer.byteLength(str, 'utf8') + " bytes");
+
+// ½ + ¼ = ¾: 9 characters, 12 bytes
+

buf.length#

+
    +
  • Number
    • +
+

The size of the buffer in bytes. Note that this is not necessarily the size +of the contents. length refers to the amount of memory allocated for the +buffer object. It does not change when the contents of the buffer are changed. + +

+
buf = new Buffer(1234);
+
+console.log(buf.length);
+buf.write("some string", "ascii", 0);
+console.log(buf.length);
+
+// 1234
+// 1234
+

buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])#

+
    +
  • targetBuffer Buffer object - Buffer to copy into
    • +
  • targetStart Number, Optional, Default: 0
    • +
  • sourceStart Number, Optional, Default: 0
    • +
  • sourceEnd Number, Optional, Default: buffer.length
    • +
+

Does copy between buffers. The source and target regions can be overlapped. +targetStart and sourceStart default to 0. +sourceEnd defaults to buffer.length. + +

+

Example: build two Buffers, then copy buf1 from byte 16 through byte 19 +into buf2, starting at the 8th byte in buf2. + +

+
buf1 = new Buffer(26);
+buf2 = new Buffer(26);
+
+for (var i = 0 ; i < 26 ; i++) {
+  buf1[i] = i + 97; // 97 is ASCII a
+  buf2[i] = 33; // ASCII !
+}
+
+buf1.copy(buf2, 8, 16, 20);
+console.log(buf2.toString('ascii', 0, 25));
+
+// !!!!!!!!qrst!!!!!!!!!!!!!
+

buf.slice([start], [end])#

+
    +
  • start Number, Optional, Default: 0
    • +
  • end Number, Optional, Default: buffer.length
    • +
+

Returns a new buffer which references the same memory as the old, but offset +and cropped by the start (defaults to 0) and end (defaults to +buffer.length) indexes. + +

+

Modifying the new buffer slice will modify memory in the original buffer! + +

+

Example: build a Buffer with the ASCII alphabet, take a slice, then modify one +byte from the original Buffer. + +

+
var buf1 = new Buffer(26);
+
+for (var i = 0 ; i < 26 ; i++) {
+  buf1[i] = i + 97; // 97 is ASCII a
+}
+
+var buf2 = buf1.slice(0, 3);
+console.log(buf2.toString('ascii', 0, buf2.length));
+buf1[0] = 33;
+console.log(buf2.toString('ascii', 0, buf2.length));
+
+// abc
+// !bc
+

buf.readUInt8(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads an unsigned 8 bit integer from the buffer at the specified offset. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+
+buf[0] = 0x3;
+buf[1] = 0x4;
+buf[2] = 0x23;
+buf[3] = 0x42;
+
+for (ii = 0; ii < buf.length; ii++) {
+  console.log(buf.readUInt8(ii));
+}
+
+// 0x3
+// 0x4
+// 0x23
+// 0x42
+

buf.readUInt16LE(offset, [noAssert])#

+

buf.readUInt16BE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads an unsigned 16 bit integer from the buffer at the specified offset with +specified endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+
+buf[0] = 0x3;
+buf[1] = 0x4;
+buf[2] = 0x23;
+buf[3] = 0x42;
+
+console.log(buf.readUInt16BE(0));
+console.log(buf.readUInt16LE(0));
+console.log(buf.readUInt16BE(1));
+console.log(buf.readUInt16LE(1));
+console.log(buf.readUInt16BE(2));
+console.log(buf.readUInt16LE(2));
+
+// 0x0304
+// 0x0403
+// 0x0423
+// 0x2304
+// 0x2342
+// 0x4223
+

buf.readUInt32LE(offset, [noAssert])#

+

buf.readUInt32BE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads an unsigned 32 bit integer from the buffer at the specified offset with +specified endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+
+buf[0] = 0x3;
+buf[1] = 0x4;
+buf[2] = 0x23;
+buf[3] = 0x42;
+
+console.log(buf.readUInt32BE(0));
+console.log(buf.readUInt32LE(0));
+
+// 0x03042342
+// 0x42230403
+

buf.readInt8(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads a signed 8 bit integer from the buffer at the specified offset. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Works as buffer.readUInt8, except buffer contents are treated as two's +complement signed values. + +

+

buf.readInt16LE(offset, [noAssert])#

+

buf.readInt16BE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads a signed 16 bit integer from the buffer at the specified offset with +specified endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Works as buffer.readUInt16*, except buffer contents are treated as two's +complement signed values. + +

+

buf.readInt32LE(offset, [noAssert])#

+

buf.readInt32BE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads a signed 32 bit integer from the buffer at the specified offset with +specified endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Works as buffer.readUInt32*, except buffer contents are treated as two's +complement signed values. + +

+

buf.readFloatLE(offset, [noAssert])#

+

buf.readFloatBE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads a 32 bit float from the buffer at the specified offset with specified +endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+
+buf[0] = 0x00;
+buf[1] = 0x00;
+buf[2] = 0x80;
+buf[3] = 0x3f;
+
+console.log(buf.readFloatLE(0));
+
+// 0x01
+

buf.readDoubleLE(offset, [noAssert])#

+

buf.readDoubleBE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads a 64 bit double from the buffer at the specified offset with specified +endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(8);
+
+buf[0] = 0x55;
+buf[1] = 0x55;
+buf[2] = 0x55;
+buf[3] = 0x55;
+buf[4] = 0x55;
+buf[5] = 0x55;
+buf[6] = 0xd5;
+buf[7] = 0x3f;
+
+console.log(buf.readDoubleLE(0));
+
+// 0.3333333333333333
+

buf.writeUInt8(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset. Note, value must be a +valid unsigned 8 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+buf.writeUInt8(0x3, 0);
+buf.writeUInt8(0x4, 1);
+buf.writeUInt8(0x23, 2);
+buf.writeUInt8(0x42, 3);
+
+console.log(buf);
+
+// <Buffer 03 04 23 42>
+

buf.writeUInt16LE(value, offset, [noAssert])#

+

buf.writeUInt16BE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid unsigned 16 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+buf.writeUInt16BE(0xdead, 0);
+buf.writeUInt16BE(0xbeef, 2);
+
+console.log(buf);
+
+buf.writeUInt16LE(0xdead, 0);
+buf.writeUInt16LE(0xbeef, 2);
+
+console.log(buf);
+
+// <Buffer de ad be ef>
+// <Buffer ad de ef be>
+

buf.writeUInt32LE(value, offset, [noAssert])#

+

buf.writeUInt32BE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid unsigned 32 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+buf.writeUInt32BE(0xfeedface, 0);
+
+console.log(buf);
+
+buf.writeUInt32LE(0xfeedface, 0);
+
+console.log(buf);
+
+// <Buffer fe ed fa ce>
+// <Buffer ce fa ed fe>
+

buf.writeInt8(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset. Note, value must be a +valid signed 8 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Works as buffer.writeUInt8, except value is written out as a two's complement +signed integer into buffer. + +

+

buf.writeInt16LE(value, offset, [noAssert])#

+

buf.writeInt16BE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid signed 16 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Works as buffer.writeUInt16*, except value is written out as a two's +complement signed integer into buffer. + +

+

buf.writeInt32LE(value, offset, [noAssert])#

+

buf.writeInt32BE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid signed 32 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Works as buffer.writeUInt32*, except value is written out as a two's +complement signed integer into buffer. + +

+

buf.writeFloatLE(value, offset, [noAssert])#

+

buf.writeFloatBE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid 32 bit float. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+buf.writeFloatBE(0xcafebabe, 0);
+
+console.log(buf);
+
+buf.writeFloatLE(0xcafebabe, 0);
+
+console.log(buf);
+
+// <Buffer 4f 4a fe bb>
+// <Buffer bb fe 4a 4f>
+

buf.writeDoubleLE(value, offset, [noAssert])#

+

buf.writeDoubleBE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid 64 bit double. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(8);
+buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
+
+console.log(buf);
+
+buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
+
+console.log(buf);
+
+// <Buffer 43 eb d5 b7 dd f9 5f d7>
+// <Buffer d7 5f f9 dd b7 d5 eb 43>
+

buf.fill(value, [offset], [end])#

+
    +
  • value
    • +
  • offset Number, Optional
    • +
  • end Number, Optional
    • +
+

Fills the buffer with the specified value. If the offset (defaults to 0) +and end (defaults to buffer.length) are not given it will fill the entire +buffer. + +

+
var b = new Buffer(50);
+b.fill("h");
+

buffer.INSPECT_MAX_BYTES#

+
    +
  • Number, Default: 50
    • +
+

How many bytes will be returned when buffer.inspect() is called. This can +be overridden by user modules. + +

+

Note that this is a property on the buffer module returned by +require('buffer'), not on the Buffer global, or a buffer instance. + +

+

Class: SlowBuffer#

+

This class is primarily for internal use. JavaScript programs should +use Buffer instead of using SlowBuffer. + +

+

In order to avoid the overhead of allocating many C++ Buffer objects for +small blocks of memory in the lifetime of a server, Node allocates memory +in 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it +will be backed by a parent SlowBuffer object. If it is larger than this, +then Node will allocate a SlowBuffer slab for it directly. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/readline.html @@ -0,0 +1,252 @@ + + + + + Readline Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Readline#

+
Stability: 3 - Stable
+

To use this module, do require('readline'). Readline allows reading of a +stream (such as STDIN) on a line-by-line basis. + +

+

Note that once you've invoked this module, your node program will not +terminate until you've closed the interface, and the STDIN stream. Here's how +to allow your program to gracefully terminate: + +

+
var rl = require('readline');
+
+var i = rl.createInterface(process.stdin, process.stdout, null);
+i.question("What do you think of node.js?", function(answer) {
+  // TODO: Log the answer in a database
+  console.log("Thank you for your valuable feedback.");
+
+  // These two lines together allow the program to terminate. Without
+  // them, it would run forever.
+  i.close();
+  process.stdin.destroy();
+});
+

rl.createInterface(input, output, completer)#

+

Takes two streams and creates a readline interface. The completer function +is used for autocompletion. When given a substring, it returns [[substr1, +substr2, ...], originalsubstring]. + +

+

Also completer can be run in async mode if it accepts two arguments: + +

+

function completer(linePartial, callback) { + callback(null, [['123'], linePartial]); + } + +

+

createInterface is commonly used with process.stdin and +process.stdout in order to accept user input: + +

+
var readline = require('readline'),
+  rl = readline.createInterface(process.stdin, process.stdout);
+

Class: Interface#

+

The class that represents a readline interface with a stdin and stdout +stream. + +

+

rl.setPrompt(prompt, length)#

+

Sets the prompt, for example when you run node on the command line, you see +> , which is node's prompt. + +

+

rl.prompt()#

+

Readies readline for input from the user, putting the current setPrompt +options on a new line, giving the user a new spot to write. + +

+

rl.question(query, callback)#

+

Prepends the prompt with query and invokes callback with the user's +response. Displays the query to the user, and then invokes callback with the +user's response after it has been typed. + +

+

Example usage: + +

+
interface.question('What is your favorite food?', function(answer) {
+  console.log('Oh, so your favorite food is ' + answer);
+});
+

rl.close()#

+

Closes tty. + +

+

rl.pause()#

+

Pauses tty. + +

+

rl.resume()#

+

Resumes tty. + +

+

rl.write()#

+

Writes to tty. + +

+

Event: 'line'#

+

function (line) {} + +

+

Emitted whenever the in stream receives a \n, usually received when the +user hits enter, or return. This is a good hook to listen for user input. + +

+

Example of listening for line: + +

+
rl.on('line', function (cmd) {
+  console.log('You just typed: '+cmd);
+});
+

Event: 'close'#

+

function () {} + +

+

Emitted whenever the in stream receives a ^C or ^D, respectively known +as SIGINT and EOT. This is a good way to know the user is finished using +your program. + +

+

Example of listening for close, and exiting the program afterward: + +

+
rl.on('close', function() {
+  console.log('goodbye!');
+  process.exit(0);
+});
+

Here's an example of how to use all these together to craft a tiny command +line interface: + +

+
var readline = require('readline'),
+  rl = readline.createInterface(process.stdin, process.stdout),
+  prefix = 'OHAI> ';
+
+rl.on('line', function(line) {
+  switch(line.trim()) {
+    case 'hello':
+      console.log('world!');
+      break;
+    default:
+      console.log('Say what? I might have heard `' + line.trim() + '`');
+      break;
+  }
+  rl.setPrompt(prefix, prefix.length);
+  rl.prompt();
+}).on('close', function() {
+  console.log('Have a great day!');
+  process.exit(0);
+});
+console.log(prefix + 'Good to see you. Try typing stuff.');
+rl.setPrompt(prefix, prefix.length);
+rl.prompt();
+

Take a look at this slightly more complicated +example, and +http-console for a real-life use +case. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/timers.html @@ -0,0 +1,127 @@ + + + + + Timers Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Timers#

+
Stability: 5 - Locked
+

All of the timer functions are globals. You do not need to require() +this module in order to use them. + +

+

setTimeout(callback, delay, [arg], [...])#

+

To schedule execution of a one-time callback after delay milliseconds. Returns a +timeoutId for possible use with clearTimeout(). Optionally you can +also pass arguments to the callback. + +

+

It is important to note that your callback will probably not be called in exactly +delay milliseconds - Node.js makes no guarantees about the exact timing of when +the callback will fire, nor of the ordering things will fire in. The callback will +be called as close as possible to the time specified. + +

+

clearTimeout(timeoutId)#

+

Prevents a timeout from triggering. + +

+

setInterval(callback, delay, [arg], [...])#

+

To schedule the repeated execution of callback every delay milliseconds. +Returns a intervalId for possible use with clearInterval(). Optionally +you can also pass arguments to the callback. + +

+

clearInterval(intervalId)#

+

Stops a interval from triggering. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/fs.json @@ -0,0 +1,1451 @@ +{ + "source": "doc/api/fs.markdown", + "modules": [ + { + "textRaw": "File System", + "name": "fs", + "stability": 3, + "stabilityText": "Stable", + "desc": "

File I/O is provided by simple wrappers around standard POSIX functions. To\nuse this module do require('fs'). All the methods have asynchronous and\nsynchronous forms.\n\n

\n

The asynchronous form always take a completion callback as its last argument.\nThe arguments passed to the completion callback depend on the method, but the\nfirst argument is always reserved for an exception. If the operation was\ncompleted successfully, then the first argument will be null or undefined.\n\n

\n

When using the synchronous form any exceptions are immediately thrown.\nYou can use try/catch to handle exceptions or allow them to bubble up.\n\n

\n

Here is an example of the asynchronous version:\n\n

\n
var fs = require('fs');\n\nfs.unlink('/tmp/hello', function (err) {\n  if (err) throw err;\n  console.log('successfully deleted /tmp/hello');\n});
\n

Here is the synchronous version:\n\n

\n
var fs = require('fs');\n\nfs.unlinkSync('/tmp/hello')\nconsole.log('successfully deleted /tmp/hello');
\n

With the asynchronous methods there is no guaranteed ordering. So the\nfollowing is prone to error:\n\n

\n
fs.rename('/tmp/hello', '/tmp/world', function (err) {\n  if (err) throw err;\n  console.log('renamed complete');\n});\nfs.stat('/tmp/world', function (err, stats) {\n  if (err) throw err;\n  console.log('stats: ' + JSON.stringify(stats));\n});
\n

It could be that fs.stat is executed before fs.rename.\nThe correct way to do this is to chain the callbacks.\n\n

\n
fs.rename('/tmp/hello', '/tmp/world', function (err) {\n  if (err) throw err;\n  fs.stat('/tmp/world', function (err, stats) {\n    if (err) throw err;\n    console.log('stats: ' + JSON.stringify(stats));\n  });\n});
\n

In busy processes, the programmer is strongly encouraged to use the\nasynchronous versions of these calls. The synchronous versions will block\nthe entire process until they complete--halting all connections.\n\n

\n

Relative path to filename can be used, remember however that this path will be relative\nto process.cwd().\n\n

\n", + "methods": [ + { + "textRaw": "fs.rename(path1, path2, [callback])", + "type": "method", + "name": "rename", + "desc": "

Asynchronous rename(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path1" + }, + { + "name": "path2" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.renameSync(path1, path2)", + "type": "method", + "name": "renameSync", + "desc": "

Synchronous rename(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path1" + }, + { + "name": "path2" + } + ] + } + ] + }, + { + "textRaw": "fs.truncate(fd, len, [callback])", + "type": "method", + "name": "truncate", + "desc": "

Asynchronous ftruncate(2). No arguments other than a possible exception are\ngiven to the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "len" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.truncateSync(fd, len)", + "type": "method", + "name": "truncateSync", + "desc": "

Synchronous ftruncate(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "len" + } + ] + } + ] + }, + { + "textRaw": "fs.chown(path, uid, gid, [callback])", + "type": "method", + "name": "chown", + "desc": "

Asynchronous chown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "uid" + }, + { + "name": "gid" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.chownSync(path, uid, gid)", + "type": "method", + "name": "chownSync", + "desc": "

Synchronous chown(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "uid" + }, + { + "name": "gid" + } + ] + } + ] + }, + { + "textRaw": "fs.fchown(fd, uid, gid, [callback])", + "type": "method", + "name": "fchown", + "desc": "

Asynchronous fchown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "uid" + }, + { + "name": "gid" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.fchownSync(fd, uid, gid)", + "type": "method", + "name": "fchownSync", + "desc": "

Synchronous fchown(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "uid" + }, + { + "name": "gid" + } + ] + } + ] + }, + { + "textRaw": "fs.lchown(path, uid, gid, [callback])", + "type": "method", + "name": "lchown", + "desc": "

Asynchronous lchown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "uid" + }, + { + "name": "gid" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.lchownSync(path, uid, gid)", + "type": "method", + "name": "lchownSync", + "desc": "

Synchronous lchown(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "uid" + }, + { + "name": "gid" + } + ] + } + ] + }, + { + "textRaw": "fs.chmod(path, mode, [callback])", + "type": "method", + "name": "chmod", + "desc": "

Asynchronous chmod(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.chmodSync(path, mode)", + "type": "method", + "name": "chmodSync", + "desc": "

Synchronous chmod(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode" + } + ] + } + ] + }, + { + "textRaw": "fs.fchmod(fd, mode, [callback])", + "type": "method", + "name": "fchmod", + "desc": "

Asynchronous fchmod(2). No arguments other than a possible exception\nare given to the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "mode" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.fchmodSync(fd, mode)", + "type": "method", + "name": "fchmodSync", + "desc": "

Synchronous fchmod(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "mode" + } + ] + } + ] + }, + { + "textRaw": "fs.lchmod(path, mode, [callback])", + "type": "method", + "name": "lchmod", + "desc": "

Asynchronous lchmod(2). No arguments other than a possible exception\nare given to the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.lchmodSync(path, mode)", + "type": "method", + "name": "lchmodSync", + "desc": "

Synchronous lchmod(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode" + } + ] + } + ] + }, + { + "textRaw": "fs.stat(path, [callback])", + "type": "method", + "name": "stat", + "desc": "

Asynchronous stat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. See the fs.Stats\nsection below for more information.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.lstat(path, [callback])", + "type": "method", + "name": "lstat", + "desc": "

Asynchronous lstat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. lstat() is identical to stat(), except that if\npath is a symbolic link, then the link itself is stat-ed, not the file that it\nrefers to.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.fstat(fd, [callback])", + "type": "method", + "name": "fstat", + "desc": "

Asynchronous fstat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. fstat() is identical to stat(), except that\nthe file to be stat-ed is specified by the file descriptor fd.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.statSync(path)", + "type": "method", + "name": "statSync", + "desc": "

Synchronous stat(2). Returns an instance of fs.Stats.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.lstatSync(path)", + "type": "method", + "name": "lstatSync", + "desc": "

Synchronous lstat(2). Returns an instance of fs.Stats.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.fstatSync(fd)", + "type": "method", + "name": "fstatSync", + "desc": "

Synchronous fstat(2). Returns an instance of fs.Stats.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + } + ] + } + ] + }, + { + "textRaw": "fs.link(srcpath, dstpath, [callback])", + "type": "method", + "name": "link", + "desc": "

Asynchronous link(2). No arguments other than a possible exception are given to\nthe completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "srcpath" + }, + { + "name": "dstpath" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.linkSync(srcpath, dstpath)", + "type": "method", + "name": "linkSync", + "desc": "

Synchronous link(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "srcpath" + }, + { + "name": "dstpath" + } + ] + } + ] + }, + { + "textRaw": "fs.symlink(linkdata, path, [type], [callback])", + "type": "method", + "name": "symlink", + "desc": "

Asynchronous symlink(2). No arguments other than a possible exception are given\nto the completion callback.\ntype argument can be either 'dir' or 'file' (default is 'file'). It is only \nused on Windows (ignored on other platforms).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "linkdata" + }, + { + "name": "path" + }, + { + "name": "type", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.symlinkSync(linkdata, path, [type])", + "type": "method", + "name": "symlinkSync", + "desc": "

Synchronous symlink(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "linkdata" + }, + { + "name": "path" + }, + { + "name": "type", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readlink(path, [callback])", + "type": "method", + "name": "readlink", + "desc": "

Asynchronous readlink(2). The callback gets two arguments (err,\nlinkString).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readlinkSync(path)", + "type": "method", + "name": "readlinkSync", + "desc": "

Synchronous readlink(2). Returns the symbolic link's string value.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.realpath(path, [callback])", + "type": "method", + "name": "realpath", + "desc": "

Asynchronous realpath(2). The callback gets two arguments (err,\nresolvedPath). May use process.cwd to resolve relative paths.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.realpathSync(path)", + "type": "method", + "name": "realpathSync", + "desc": "

Synchronous realpath(2). Returns the resolved path.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.unlink(path, [callback])", + "type": "method", + "name": "unlink", + "desc": "

Asynchronous unlink(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.unlinkSync(path)", + "type": "method", + "name": "unlinkSync", + "desc": "

Synchronous unlink(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.rmdir(path, [callback])", + "type": "method", + "name": "rmdir", + "desc": "

Asynchronous rmdir(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.rmdirSync(path)", + "type": "method", + "name": "rmdirSync", + "desc": "

Synchronous rmdir(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.mkdir(path, [mode], [callback])", + "type": "method", + "name": "mkdir", + "desc": "

Asynchronous mkdir(2). No arguments other than a possible exception are given\nto the completion callback. mode defaults to 0777.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.mkdirSync(path, [mode])", + "type": "method", + "name": "mkdirSync", + "desc": "

Synchronous mkdir(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readdir(path, [callback])", + "type": "method", + "name": "readdir", + "desc": "

Asynchronous readdir(3). Reads the contents of a directory.\nThe callback gets two arguments (err, files) where files is an array of\nthe names of the files in the directory excluding '.' and '..'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readdirSync(path)", + "type": "method", + "name": "readdirSync", + "desc": "

Synchronous readdir(3). Returns an array of filenames excluding '.' and\n'..'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.close(fd, [callback])", + "type": "method", + "name": "close", + "desc": "

Asynchronous close(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.closeSync(fd)", + "type": "method", + "name": "closeSync", + "desc": "

Synchronous close(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + } + ] + } + ] + }, + { + "textRaw": "fs.open(path, flags, [mode], [callback])", + "type": "method", + "name": "open", + "desc": "

Asynchronous file open. See open(2). flags can be:\n\n

\n
    \n

  • 'r' - Open file for reading.\nAn exception occurs if the file does not exist.

    \n
    • \n

  • 'r+' - Open file for reading and writing.\nAn exception occurs if the file does not exist.

    \n
    • \n

  • 'w' - Open file for writing.\nThe file is created (if it does not exist) or truncated (if it exists).

    \n
    • \n

  • 'w+' - Open file for reading and writing.\nThe file is created (if it does not exist) or truncated (if it exists).

    \n
    • \n

  • 'a' - Open file for appending.\nThe file is created if it does not exist.

    \n
    • \n

  • 'a+' - Open file for reading and appending.\nThe file is created if it does not exist.

    \n
    • \n
\n

mode defaults to 0666. The callback gets two arguments (err, fd).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "flags" + }, + { + "name": "mode", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.openSync(path, flags, [mode])", + "type": "method", + "name": "openSync", + "desc": "

Synchronous open(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "flags" + }, + { + "name": "mode", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.utimes(path, atime, mtime, [callback])", + "type": "method", + "name": "utimes", + "desc": "

Change file timestamps of the file referenced by the supplied path.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "atime" + }, + { + "name": "mtime" + } + ] + }, + { + "params": [ + { + "name": "path" + }, + { + "name": "atime" + }, + { + "name": "mtime" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.utimesSync(path, atime, mtime)", + "type": "method", + "name": "utimesSync", + "desc": "

Change file timestamps of the file referenced by the supplied path.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "atime" + }, + { + "name": "mtime" + } + ] + } + ] + }, + { + "textRaw": "fs.futimes(fd, atime, mtime, [callback])", + "type": "method", + "name": "futimes", + "desc": "

Change the file timestamps of a file referenced by the supplied file\ndescriptor.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "atime" + }, + { + "name": "mtime" + } + ] + }, + { + "params": [ + { + "name": "fd" + }, + { + "name": "atime" + }, + { + "name": "mtime" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.futimesSync(fd, atime, mtime)", + "type": "method", + "name": "futimesSync", + "desc": "

Change the file timestamps of a file referenced by the supplied file\ndescriptor.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "atime" + }, + { + "name": "mtime" + } + ] + } + ] + }, + { + "textRaw": "fs.fsync(fd, [callback])", + "type": "method", + "name": "fsync", + "desc": "

Asynchronous fsync(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.fsyncSync(fd)", + "type": "method", + "name": "fsyncSync", + "desc": "

Synchronous fsync(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + } + ] + } + ] + }, + { + "textRaw": "fs.write(fd, buffer, offset, length, position, [callback])", + "type": "method", + "name": "write", + "desc": "

Write buffer to the file specified by fd.\n\n

\n

offset and length determine the part of the buffer to be written.\n\n

\n

position refers to the offset from the beginning of the file where this data\nshould be written. If position is null, the data will be written at the\ncurrent position.\nSee pwrite(2).\n\n

\n

The callback will be given three arguments (err, written, buffer) where written\nspecifies how many bytes were written from buffer.\n\n

\n

Note that it is unsafe to use fs.write multiple times on the same file\nwithout waiting for the callback. For this scenario,\nfs.createWriteStream is strongly recommended.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "buffer" + }, + { + "name": "offset" + }, + { + "name": "length" + }, + { + "name": "position" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.writeSync(fd, buffer, offset, length, position)", + "type": "method", + "name": "writeSync", + "desc": "

Synchronous version of buffer-based fs.write(). Returns the number of bytes\nwritten.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "buffer" + }, + { + "name": "offset" + }, + { + "name": "length" + }, + { + "name": "position" + } + ] + } + ] + }, + { + "textRaw": "fs.writeSync(fd, str, position, [encoding])", + "type": "method", + "name": "writeSync", + "desc": "

Synchronous version of string-based fs.write(). encoding defaults to\n'utf8'. Returns the number of bytes written.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "str" + }, + { + "name": "position" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.read(fd, buffer, offset, length, position, [callback])", + "type": "method", + "name": "read", + "desc": "

Read data from the file specified by fd.\n\n

\n

buffer is the buffer that the data will be written to.\n\n

\n

offset is offset within the buffer where writing will start.\n\n

\n

length is an integer specifying the number of bytes to read.\n\n

\n

position is an integer specifying where to begin reading from in the file.\nIf position is null, data will be read from the current file position.\n\n

\n

The callback is given the three arguments, (err, bytesRead, buffer).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "buffer" + }, + { + "name": "offset" + }, + { + "name": "length" + }, + { + "name": "position" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readSync(fd, buffer, offset, length, position)", + "type": "method", + "name": "readSync", + "desc": "

Synchronous version of buffer-based fs.read. Returns the number of\nbytesRead.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "buffer" + }, + { + "name": "offset" + }, + { + "name": "length" + }, + { + "name": "position" + } + ] + } + ] + }, + { + "textRaw": "fs.readSync(fd, length, position, encoding)", + "type": "method", + "name": "readSync", + "desc": "

Synchronous version of string-based fs.read. Returns the number of\nbytesRead.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "length" + }, + { + "name": "position" + }, + { + "name": "encoding" + } + ] + } + ] + }, + { + "textRaw": "fs.readFile(filename, [encoding], [callback])", + "type": "method", + "name": "readFile", + "desc": "

Asynchronously reads the entire contents of a file. Example:\n\n

\n
fs.readFile('/etc/passwd', function (err, data) {\n  if (err) throw err;\n  console.log(data);\n});
\n

The callback is passed two arguments (err, data), where data is the\ncontents of the file.\n\n

\n

If no encoding is specified, then the raw buffer is returned.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "encoding", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readFileSync(filename, [encoding])", + "type": "method", + "name": "readFileSync", + "desc": "

Synchronous version of fs.readFile. Returns the contents of the filename.\n\n

\n

If encoding is specified then this function returns a string. Otherwise it\nreturns a buffer.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.writeFile(filename, data, [encoding], [callback])", + "type": "method", + "name": "writeFile", + "desc": "

Asynchronously writes data to a file, replacing the file if it already exists.\ndata can be a string or a buffer. The encoding argument is ignored if\ndata is a buffer. It defaults to 'utf8'.\n\n

\n

Example:\n\n

\n
fs.writeFile('message.txt', 'Hello Node', function (err) {\n  if (err) throw err;\n  console.log('It\\'s saved!');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "data" + }, + { + "name": "encoding", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.writeFileSync(filename, data, [encoding])", + "type": "method", + "name": "writeFileSync", + "desc": "

The synchronous version of fs.writeFile.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "data" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.watchFile(filename, [options], listener)", + "type": "method", + "name": "watchFile", + "stability": 2, + "stabilityText": "Unstable. Use fs.watch instead, if available.", + "desc": "

Watch for changes on filename. The callback listener will be called each\ntime the file is accessed.\n\n

\n

The second argument is optional. The options if provided should be an object\ncontaining two members a boolean, persistent, and interval. persistent\nindicates whether the process should continue to run as long as files are\nbeing watched. interval indicates how often the target should be polled,\nin milliseconds. (On Linux systems with inotify, interval is ignored.) The\ndefault is { persistent: true, interval: 0 }.\n\n

\n

The listener gets two arguments the current stat object and the previous\nstat object:\n\n

\n
fs.watchFile('message.text', function (curr, prev) {\n  console.log('the current mtime is: ' + curr.mtime);\n  console.log('the previous mtime was: ' + prev.mtime);\n});
\n

These stat objects are instances of fs.Stat.\n\n

\n

If you want to be notified when the file was modified, not just accessed\nyou need to compare curr.mtime and prev.mtime.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "options", + "optional": true + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "fs.unwatchFile(filename)", + "type": "method", + "name": "unwatchFile", + "stability": 2, + "stabilityText": "Unstable. Use fs.watch instead, if available.", + "desc": "

Stop watching for changes on filename.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + } + ] + } + ] + }, + { + "textRaw": "fs.watch(filename, [options], listener)", + "type": "method", + "name": "watch", + "stability": 2, + "stabilityText": "Unstable. Not available on all platforms.", + "desc": "

Watch for changes on filename, where filename is either a file or a\ndirectory. The returned object is a fs.FSWatcher.\n\n

\n

The second argument is optional. The options if provided should be an object\ncontaining a boolean member persistent, which indicates whether the process\nshould continue to run as long as files are being watched. The default is\n{ persistent: true }.\n\n

\n

The listener callback gets two arguments (event, filename). event is either\n'rename' or 'change', and filename is the name of the file which triggered\nthe event.\n\n

\n", + "miscs": [ + { + "textRaw": "Caveats", + "name": "Caveats", + "type": "misc", + "desc": "

The fs.watch API is not 100% consistent across platforms, and is\nunavailable in some situations.\n\n

\n", + "miscs": [ + { + "textRaw": "Availability", + "name": "Availability", + "type": "misc", + "desc": "

This feature depends on the underlying operating system providing a way\nto be notified of filesystem changes.\n\n

\n
    \n
  • On Linux systems, this uses inotify.
    • \n
  • On BSD systems (including OS X), this uses kqueue.
    • \n
  • On SunOS systems (including Solaris and SmartOS), this uses event ports.
    • \n
  • On Windows systems, this feature depends on ReadDirectoryChangesW.
    • \n
\n

If the underlying functionality is not available for some reason, then\nfs.watch will not be able to function. You can still use\nfs.watchFile, which uses stat polling, but it is slower and less\nreliable.\n\n

\n" + }, + { + "textRaw": "Filename Argument", + "name": "Filename Argument", + "type": "misc", + "desc": "

Providing filename argument in the callback is not supported\non every platform (currently it's only supported on Linux and Windows). Even\non supported platforms filename is not always guaranteed to be provided.\nTherefore, don't assume that filename argument is always provided in the\ncallback, and have some fallback logic if it is null.\n\n

\n
fs.watch('somedir', function (event, filename) {\n  console.log('event is: ' + event);\n  if (filename) {\n    console.log('filename provided: ' + filename);\n  } else {\n    console.log('filename not provided');\n  }\n});
\n" + } + ] + } + ], + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "options", + "optional": true + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "fs.createReadStream(path, [options])", + "type": "method", + "name": "createReadStream", + "desc": "

Returns a new ReadStream object (See Readable Stream).\n\n

\n

options is an object with the following defaults:\n\n

\n
{ flags: 'r',\n  encoding: null,\n  fd: null,\n  mode: 0666,\n  bufferSize: 64 * 1024\n}
\n

options can include start and end values to read a range of bytes from\nthe file instead of the entire file. Both start and end are inclusive and\nstart at 0.\n\n

\n

An example to read the last 10 bytes of a file which is 100 bytes long:\n\n

\n
fs.createReadStream('sample.txt', {start: 90, end: 99});
\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.createWriteStream(path, [options])", + "type": "method", + "name": "createWriteStream", + "desc": "

Returns a new WriteStream object (See Writable Stream).\n\n

\n

options is an object with the following defaults:\n\n

\n
{ flags: 'w',\n  encoding: null,\n  mode: 0666 }
\n

options may also include a start option to allow writing data at\nsome position past the beginning of the file. Modifying a file rather\nthan replacing it may require a flags mode of r+ rather than the\ndefault mode w.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "options", + "optional": true + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: fs.Stats", + "type": "class", + "name": "fs.Stats", + "desc": "

Objects returned from fs.stat(), fs.lstat() and fs.fstat() and their\nsynchronous counterparts are of this type.\n\n

\n
    \n
  • stats.isFile()
    • \n
  • stats.isDirectory()
    • \n
  • stats.isBlockDevice()
    • \n
  • stats.isCharacterDevice()
    • \n
  • stats.isSymbolicLink() (only valid with fs.lstat())
    • \n
  • stats.isFIFO()
    • \n
  • stats.isSocket()
    • \n
\n

For a regular file util.inspect(stats) would return a string very\nsimilar to this:\n\n

\n
{ dev: 2114,\n  ino: 48064969,\n  mode: 33188,\n  nlink: 1,\n  uid: 85,\n  gid: 100,\n  rdev: 0,\n  size: 527,\n  blksize: 4096,\n  blocks: 8,\n  atime: Mon, 10 Oct 2011 23:24:11 GMT,\n  mtime: Mon, 10 Oct 2011 23:24:11 GMT,\n  ctime: Mon, 10 Oct 2011 23:24:11 GMT }
\n

Please note that atime, mtime and ctime are instances\nof [Date][MDN-Date] object and to compare the values of\nthese objects you should use appropriate methods. For most\ngeneral uses [getTime()][MDN-Date-getTime] will return\nthe number of milliseconds elapsed since 1 January 1970\n00:00:00 UTC and this integer should be sufficient for\nany comparison, however there additional methods which can\nbe used for displaying fuzzy information. More details can\nbe found in the [MDN JavaScript Reference][MDN-Date] page.\n\n

\n" + }, + { + "textRaw": "Class: fs.ReadStream", + "type": "class", + "name": "fs.ReadStream", + "desc": "

ReadStream is a Readable Stream.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'open'", + "type": "event", + "name": "open", + "params": [], + "desc": "

Emitted when the ReadStream's file is opened.\n\n\n

\n" + } + ] + }, + { + "textRaw": "Class: fs.FSWatcher", + "type": "class", + "name": "fs.FSWatcher", + "desc": "

Objects returned from fs.watch() are of this type.\n\n

\n", + "methods": [ + { + "textRaw": "watcher.close()", + "type": "method", + "name": "close", + "desc": "

Stop watching for changes on the given fs.FSWatcher.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "events": [ + { + "textRaw": "Event: 'change'", + "type": "event", + "name": "change", + "params": [], + "desc": "

Emitted when something changes in a watched directory or file.\nSee more details in fs.watch.\n\n

\n" + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "params": [], + "desc": "

Emitted when an error occurs.\n

\n" + } + ] + } + ], + "properties": [ + { + "textRaw": "fs.WriteStream", + "name": "WriteStream", + "desc": "

WriteStream is a Writable Stream.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'open'", + "type": "event", + "name": "open", + "params": [], + "desc": "

Emitted when the WriteStream's file is opened.\n\n

\n" + } + ], + "properties": [ + { + "textRaw": "file.bytesWritten", + "name": "bytesWritten", + "desc": "

The number of bytes written so far. Does not include data that is still queued\nfor writing.\n\n

\n" + } + ] + } + ], + "type": "module", + "displayName": "fs" + } + ] +} --- /dev/null +++ b/doc/api/modules.json @@ -0,0 +1,156 @@ +{ + "source": "doc/api/modules.markdown", + "modules": [ + { + "textRaw": "Modules", + "name": "module", + "stability": 5, + "stabilityText": "Locked", + "desc": "

Node has a simple module loading system. In Node, files and modules are in\none-to-one correspondence. As an example, foo.js loads the module\ncircle.js in the same directory.\n\n

\n

The contents of foo.js:\n\n

\n
var circle = require('./circle.js');\nconsole.log( 'The area of a circle of radius 4 is '\n           + circle.area(4));
\n

The contents of circle.js:\n\n

\n
var PI = Math.PI;\n\nexports.area = function (r) {\n  return PI * r * r;\n};\n\nexports.circumference = function (r) {\n  return 2 * PI * r;\n};
\n

The module circle.js has exported the functions area() and\ncircumference(). To export an object, add to the special exports\nobject.\n\n

\n

Variables\nlocal to the module will be private. In this example the variable PI is\nprivate to circle.js.\n\n

\n

The module system is implemented in the require("module") module.\n\n

\n", + "miscs": [ + { + "textRaw": "Cycles", + "name": "Cycles", + "type": "misc", + "desc": "

When there are circular require() calls, a module might not be\ndone being executed when it is returned.\n\n

\n

Consider this situation:\n\n

\n

a.js:\n\n

\n
console.log('a starting');\nexports.done = false;\nvar b = require('./b.js');\nconsole.log('in a, b.done = %j', b.done);\nexports.done = true;\nconsole.log('a done');
\n

b.js:\n\n

\n
console.log('b starting');\nexports.done = false;\nvar a = require('./a.js');\nconsole.log('in b, a.done = %j', a.done);\nexports.done = true;\nconsole.log('b done');
\n

main.js:\n\n

\n
console.log('main starting');\nvar a = require('./a.js');\nvar b = require('./b.js');\nconsole.log('in main, a.done=%j, b.done=%j', a.done, b.done);
\n

When main.js loads a.js, then a.js in turn loads b.js. At that\npoint, b.js tries to load a.js. In order to prevent an infinite\nloop an unfinished copy of the a.js exports object is returned to the\nb.js module. b.js then finishes loading, and its exports object is\nprovided to the a.js module.\n\n

\n

By the time main.js has loaded both modules, they're both finished.\nThe output of this program would thus be:\n\n

\n
$ node main.js\nmain starting\na starting\nb starting\nin b, a.done = false\nb done\nin a, b.done = true\na done\nin main, a.done=true, b.done=true
\n

If you have cyclic module dependencies in your program, make sure to\nplan accordingly.\n\n

\n" + }, + { + "textRaw": "Core Modules", + "name": "Core Modules", + "type": "misc", + "desc": "

Node has several modules compiled into the binary. These modules are\ndescribed in greater detail elsewhere in this documentation.\n\n

\n

The core modules are defined in node's source in the lib/ folder.\n\n

\n

Core modules are always preferentially loaded if their identifier is\npassed to require(). For instance, require('http') will always\nreturn the built in HTTP module, even if there is a file by that name.\n\n

\n" + }, + { + "textRaw": "File Modules", + "name": "File Modules", + "type": "misc", + "desc": "

If the exact filename is not found, then node will attempt to load the\nrequired filename with the added extension of .js, .json, and then .node.\n\n

\n

.js files are interpreted as JavaScript text files, and .json files are\nparsed as JSON text files. .node files are interpreted as compiled addon\nmodules loaded with dlopen.\n\n

\n

A module prefixed with '/' is an absolute path to the file. For\nexample, require('/home/marco/foo.js') will load the file at\n/home/marco/foo.js.\n\n

\n

A module prefixed with './' is relative to the file calling require().\nThat is, circle.js must be in the same directory as foo.js for\nrequire('./circle') to find it.\n\n

\n

Without a leading '/' or './' to indicate a file, the module is either a\n"core module" or is loaded from a node_modules folder.\n\n

\n" + }, + { + "textRaw": "Loading from `node_modules` Folders", + "name": "Loading from `node_modules` Folders", + "type": "misc", + "desc": "

If the module identifier passed to require() is not a native module,\nand does not begin with '/', '../', or './', then node starts at the\nparent directory of the current module, and adds /node_modules, and\nattempts to load the module from that location.\n\n

\n

If it is not found there, then it moves to the parent directory, and so\non, until the root of the tree is reached.\n\n

\n

For example, if the file at '/home/ry/projects/foo.js' called\nrequire('bar.js'), then node would look in the following locations, in\nthis order:\n\n

\n
    \n
  • /home/ry/projects/node_modules/bar.js
    • \n
  • /home/ry/node_modules/bar.js
    • \n
  • /home/node_modules/bar.js
    • \n
  • /node_modules/bar.js
    • \n
\n

This allows programs to localize their dependencies, so that they do not\nclash.\n\n

\n" + }, + { + "textRaw": "Folders as Modules", + "name": "Folders as Modules", + "type": "misc", + "desc": "

It is convenient to organize programs and libraries into self-contained\ndirectories, and then provide a single entry point to that library.\nThere are three ways in which a folder may be passed to require() as\nan argument.\n\n

\n

The first is to create a package.json file in the root of the folder,\nwhich specifies a main module. An example package.json file might\nlook like this:\n\n

\n
{ "name" : "some-library",\n  "main" : "./lib/some-library.js" }
\n

If this was in a folder at ./some-library, then\nrequire('./some-library') would attempt to load\n./some-library/lib/some-library.js.\n\n

\n

This is the extent of Node's awareness of package.json files.\n\n

\n

If there is no package.json file present in the directory, then node\nwill attempt to load an index.js or index.node file out of that\ndirectory. For example, if there was no package.json file in the above\nexample, then require('./some-library') would attempt to load:\n\n

\n
    \n
  • ./some-library/index.js
    • \n
  • ./some-library/index.node
    • \n
\n" + }, + { + "textRaw": "Caching", + "name": "Caching", + "type": "misc", + "desc": "

Modules are cached after the first time they are loaded. This means\n(among other things) that every call to require('foo') will get\nexactly the same object returned, if it would resolve to the same file.\n\n

\n

Multiple calls to require('foo') may not cause the module code to be\nexecuted multiple times. This is an important feature. With it,\n"partially done" objects can be returned, thus allowing transitive\ndependencies to be loaded even when they would cause cycles.\n\n

\n

If you want to have a module execute code multiple times, then export a\nfunction, and call that function.\n\n

\n", + "miscs": [ + { + "textRaw": "Module Caching Caveats", + "name": "Module Caching Caveats", + "type": "misc", + "desc": "

Modules are cached based on their resolved filename. Since modules may\nresolve to a different filename based on the location of the calling\nmodule (loading from node_modules folders), it is not a guarantee\nthat require('foo') will always return the exact same object, if it\nwould resolve to different files.\n\n

\n" + } + ] + }, + { + "textRaw": "All Together...", + "name": "All Together...", + "type": "misc", + "desc": "

To get the exact filename that will be loaded when require() is called, use\nthe require.resolve() function.\n\n

\n

Putting together all of the above, here is the high-level algorithm\nin pseudocode of what require.resolve does:\n\n

\n
require(X) from module at path Y\n1. If X is a core module,\n   a. return the core module\n   b. STOP\n2. If X begins with './' or '/' or '../'\n   a. LOAD_AS_FILE(Y + X)\n   b. LOAD_AS_DIRECTORY(Y + X)\n3. LOAD_NODE_MODULES(X, dirname(Y))\n4. THROW "not found"\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as JavaScript text.  STOP\n2. If X.js is a file, load X.js as JavaScript text.  STOP\n3. If X.node is a file, load X.node as binary addon.  STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n   a. Parse X/package.json, and look for "main" field.\n   b. let M = X + (json main field)\n   c. LOAD_AS_FILE(M)\n2. If X/index.js is a file, load X/index.js as JavaScript text.  STOP\n3. If X/index.node is a file, load X/index.node as binary addon.  STOP\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS=NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n   a. LOAD_AS_FILE(DIR/X)\n   b. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let ROOT = index of first instance of "node_modules" in PARTS, or 0\n3. let I = count of PARTS - 1\n4. let DIRS = []\n5. while I > ROOT,\n   a. if PARTS[I] = "node_modules" CONTINUE\n   c. DIR = path join(PARTS[0 .. I] + "node_modules")\n   b. DIRS = DIRS + DIR\n   c. let I = I - 1\n6. return DIRS
\n" + }, + { + "textRaw": "Loading from the global folders", + "name": "Loading from the global folders", + "type": "misc", + "desc": "

If the NODE_PATH environment variable is set to a colon-delimited list\nof absolute paths, then node will search those paths for modules if they\nare not found elsewhere. (Note: On Windows, NODE_PATH is delimited by\nsemicolons instead of colons.)\n\n

\n

Additionally, node will search in the following locations:\n\n

\n
    \n
  • 1: $HOME/.node_modules
    • \n
  • 2: $HOME/.node_libraries
    • \n
  • 3: $PREFIX/lib/node
    • \n
\n

Where $HOME is the user's home directory, and $PREFIX is node's\nconfigured installPrefix.\n\n

\n

These are mostly for historic reasons. You are highly encouraged to\nplace your dependencies locally in node_modules folders. They will be\nloaded faster, and more reliably.\n\n

\n" + }, + { + "textRaw": "Accessing the main module", + "name": "Accessing the main module", + "type": "misc", + "desc": "

When a file is run directly from Node, require.main is set to its\nmodule. That means that you can determine whether a file has been run\ndirectly by testing\n\n

\n
require.main === module
\n

For a file foo.js, this will be true if run via node foo.js, but\nfalse if run by require('./foo').\n\n

\n

Because module provides a filename property (normally equivalent to\n__filename), the entry point of the current application can be obtained\nby checking require.main.filename.\n\n

\n" + }, + { + "textRaw": "Addenda: Package Manager Tips", + "name": "Addenda: Package Manager Tips", + "type": "misc", + "desc": "

The semantics of Node's require() function were designed to be general\nenough to support a number of sane directory structures. Package manager\nprograms such as dpkg, rpm, and npm will hopefully find it possible to\nbuild native packages from Node modules without modification.\n\n

\n

Below we give a suggested directory structure that could work:\n\n

\n

Let's say that we wanted to have the folder at\n/usr/lib/node/<some-package>/<some-version> hold the contents of a\nspecific version of a package.\n\n

\n

Packages can depend on one another. In order to install package foo, you\nmay have to install a specific version of package bar. The bar package\nmay itself have dependencies, and in some cases, these dependencies may even\ncollide or form cycles.\n\n

\n

Since Node looks up the realpath of any modules it loads (that is,\nresolves symlinks), and then looks for their dependencies in the\nnode_modules folders as described above, this situation is very simple to\nresolve with the following architecture:\n\n

\n
    \n
  • /usr/lib/node/foo/1.2.3/ - Contents of the foo package, version 1.2.3.
    • \n
  • /usr/lib/node/bar/4.3.2/ - Contents of the bar package that foo\ndepends on.
    • \n
  • /usr/lib/node/foo/1.2.3/node_modules/bar - Symbolic link to\n/usr/lib/node/bar/4.3.2/.
    • \n
  • /usr/lib/node/bar/4.3.2/node_modules/* - Symbolic links to the packages\nthat bar depends on.
    • \n
\n

Thus, even if a cycle is encountered, or if there are dependency\nconflicts, every module will be able to get a version of its dependency\nthat it can use.\n\n

\n

When the code in the foo package does require('bar'), it will get the\nversion that is symlinked into /usr/lib/node/foo/1.2.3/node_modules/bar.\nThen, when the code in the bar package calls require('quux'), it'll get\nthe version that is symlinked into\n/usr/lib/node/bar/4.3.2/node_modules/quux.\n\n

\n

Furthermore, to make the module lookup process even more optimal, rather\nthan putting packages directly in /usr/lib/node, we could put them in\n/usr/lib/node_modules/<name>/<version>. Then node will not bother\nlooking for missing dependencies in /usr/node_modules or /node_modules.\n\n

\n

In order to make modules available to the node REPL, it might be useful to\nalso add the /usr/lib/node_modules folder to the $NODE_PATH environment\nvariable. Since the module lookups using node_modules folders are all\nrelative, and based on the real path of the files making the calls to\nrequire(), the packages themselves can be anywhere.\n

\n" + } + ], + "vars": [ + { + "textRaw": "The `module` Object", + "name": "module", + "type": "var", + "desc": "

In each module, the module free variable is a reference to the object\nrepresenting the current module. In particular\nmodule.exports is the same as the exports object.\nmodule isn't actually a global but rather local to each module.\n\n

\n", + "properties": [ + { + "textRaw": "`exports` {Object} ", + "name": "exports", + "desc": "

The exports object is created by the Module system. Sometimes this is not\nacceptable, many want their module to be an instance of some class. To do this\nassign the desired export object to module.exports. For example suppose we\nwere making a module called a.js\n\n

\n
var EventEmitter = require('events').EventEmitter;\n\nmodule.exports = new EventEmitter();\n\n// Do some work, and after some time emit\n// the 'ready' event from the module itself.\nsetTimeout(function() {\n  module.exports.emit('ready');\n}, 1000);
\n

Then in another file we could do\n\n

\n
var a = require('./a');\na.on('ready', function() {\n  console.log('module a is ready');\n});
\n

Note that assignment to module.exports must be done immediately. It cannot be\ndone in any callbacks. This does not work:\n\n

\n

x.js:\n\n

\n
setTimeout(function() {\n  module.exports = { a: "hello" };\n}, 0);
\n

y.js:\n\n

\n
var x = require('./x');\nconsole.log(x.a);
\n" + }, + { + "textRaw": "`id` {String} ", + "name": "id", + "desc": "

The identifier for the module. Typically this is the fully resolved\nfilename.\n\n\n

\n" + }, + { + "textRaw": "`filename` {String} ", + "name": "filename", + "desc": "

The fully resolved filename to the module.\n\n\n

\n" + }, + { + "textRaw": "`loaded` {Boolean} ", + "name": "loaded", + "desc": "

Whether or not the module is done loading, or is in the process of\nloading.\n\n\n

\n" + }, + { + "textRaw": "`parent` {Module Object} ", + "name": "parent", + "desc": "

The module that required this one.\n\n\n

\n" + }, + { + "textRaw": "`children` {Array} ", + "name": "children", + "desc": "

The module objects required by this one.\n\n\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "module.require(id)", + "type": "method", + "name": "require", + "signatures": [ + { + "return": { + "textRaw": "Return: {Object} `exports` from the resolved module ", + "name": "return", + "type": "Object", + "desc": "`exports` from the resolved module" + }, + "params": [ + { + "textRaw": "`id` {String} ", + "name": "id", + "type": "String" + } + ] + }, + { + "params": [ + { + "name": "id" + } + ] + } + ], + "desc": "

The module.require method provides a way to load a module as if\nrequire() was called from the original module.\n\n

\n

Note that in order to do this, you must get a reference to the module\nobject. Since require() returns the exports, and the module is\ntypically only available within a specific module's code, it must be\nexplicitly exported in order to be used.\n\n\n

\n" + } + ] + } + ], + "type": "module", + "displayName": "module" + } + ] +} --- /dev/null +++ b/doc/api/path.json @@ -0,0 +1,175 @@ +{ + "source": "doc/api/path.markdown", + "modules": [ + { + "textRaw": "Path", + "name": "path", + "stability": 3, + "stabilityText": "Stable", + "desc": "

This module contains utilities for handling and transforming file\npaths. Almost all these methods perform only string transformations.\nThe file system is not consulted to check whether paths are valid.\n\n

\n

path.exists and path.existsSync are the exceptions, and should\nlogically be found in the fs module as they do access the file system.\n\n

\n

Use require('path') to use this module. The following methods are provided:\n\n

\n", + "methods": [ + { + "textRaw": "path.normalize(p)", + "type": "method", + "name": "normalize", + "desc": "

Normalize a string path, taking care of '..' and '.' parts.\n\n

\n

When multiple slashes are found, they're replaced by a single one;\nwhen the path contains a trailing slash, it is preserved.\nOn windows backslashes are used. \n\n

\n

Example:\n\n

\n
path.normalize('/foo/bar//baz/asdf/quux/..')\n// returns\n'/foo/bar/baz/asdf'
\n", + "signatures": [ + { + "params": [ + { + "name": "p" + } + ] + } + ] + }, + { + "textRaw": "path.join([path1], [path2], [...])", + "type": "method", + "name": "join", + "desc": "

Join all arguments together and normalize the resulting path.\nNon-string arguments are ignored.\n\n

\n

Example:\n\n

\n
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')\n// returns\n'/foo/bar/baz/asdf'\n\npath.join('foo', {}, 'bar')\n// returns\n'foo/bar'
\n", + "signatures": [ + { + "params": [ + { + "name": "path1", + "optional": true + }, + { + "name": "path2", + "optional": true + }, + { + "name": "...", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "path.resolve([from ...], to)", + "type": "method", + "name": "resolve", + "desc": "

Resolves to to an absolute path.\n\n

\n

If to isn't already absolute from arguments are prepended in right to left\norder, until an absolute path is found. If after using all from paths still\nno absolute path is found, the current working directory is used as well. The\nresulting path is normalized, and trailing slashes are removed unless the path \ngets resolved to the root directory. Non-string arguments are ignored.\n\n

\n

Another way to think of it is as a sequence of cd commands in a shell.\n\n

\n
path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
\n

Is similar to:\n\n

\n
cd foo/bar\ncd /tmp/file/\ncd ..\ncd a/../subfile\npwd
\n

The difference is that the different paths don't need to exist and may also be\nfiles.\n\n

\n

Examples:\n\n

\n
path.resolve('/foo/bar', './baz')\n// returns\n'/foo/bar/baz'\n\npath.resolve('/foo/bar', '/tmp/file/')\n// returns\n'/tmp/file'\n\npath.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')\n// if currently in /home/myself/node, it returns\n'/home/myself/node/wwwroot/static_files/gif/image.gif'
\n", + "signatures": [ + { + "params": [ + { + "name": "from ...", + "optional": true + }, + { + "name": "to" + } + ] + } + ] + }, + { + "textRaw": "path.relative(from, to)", + "type": "method", + "name": "relative", + "desc": "

Solve the relative path from from to to.\n\n

\n

At times we have two absolute paths, and we need to derive the relative\npath from one to the other. This is actually the reverse transform of\npath.resolve, which means we see that:\n\n

\n
path.resolve(from, path.relative(from, to)) == path.resolve(to)
\n

Examples:\n\n

\n
path.relative('C:\\\\orandea\\\\test\\\\aaa', 'C:\\\\orandea\\\\impl\\\\bbb')\n// returns\n'..\\\\..\\\\impl\\\\bbb'\n\npath.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')\n// returns\n'../../impl/bbb'
\n", + "signatures": [ + { + "params": [ + { + "name": "from" + }, + { + "name": "to" + } + ] + } + ] + }, + { + "textRaw": "path.dirname(p)", + "type": "method", + "name": "dirname", + "desc": "

Return the directory name of a path. Similar to the Unix dirname command.\n\n

\n

Example:\n\n

\n
path.dirname('/foo/bar/baz/asdf/quux')\n// returns\n'/foo/bar/baz/asdf'
\n", + "signatures": [ + { + "params": [ + { + "name": "p" + } + ] + } + ] + }, + { + "textRaw": "path.basename(p, [ext])", + "type": "method", + "name": "basename", + "desc": "

Return the last portion of a path. Similar to the Unix basename command.\n\n

\n

Example:\n\n

\n
path.basename('/foo/bar/baz/asdf/quux.html')\n// returns\n'quux.html'\n\npath.basename('/foo/bar/baz/asdf/quux.html', '.html')\n// returns\n'quux'
\n", + "signatures": [ + { + "params": [ + { + "name": "p" + }, + { + "name": "ext", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "path.extname(p)", + "type": "method", + "name": "extname", + "desc": "

Return the extension of the path, from the last '.' to end of string\nin the last portion of the path. If there is no '.' in the last portion\nof the path or the first character of it is '.', then it returns\nan empty string. Examples:\n\n

\n
path.extname('index.html')\n// returns\n'.html'\n\npath.extname('index.')\n// returns\n'.'\n\npath.extname('index')\n// returns\n''
\n", + "signatures": [ + { + "params": [ + { + "name": "p" + } + ] + } + ] + }, + { + "textRaw": "path.exists(p, [callback])", + "type": "method", + "name": "exists", + "desc": "

Test whether or not the given path exists by checking with the file system.\nThen call the callback argument with either true or false. Example:\n\n

\n
path.exists('/etc/passwd', function (exists) {\n  util.debug(exists ? "it's there" : "no passwd!");\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "p" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "path.existsSync(p)", + "type": "method", + "name": "existsSync", + "desc": "

Synchronous version of path.exists.\n

\n", + "signatures": [ + { + "params": [ + { + "name": "p" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "Path" + } + ] +} --- /dev/null +++ b/doc/api/http.html @@ -0,0 +1,1007 @@ + + + + + HTTP Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ +
+

Table of Contents

+ + +
+ +
+

HTTP#

+
Stability: 3 - Stable
+

To use the HTTP server and client one must require('http'). + +

+

The HTTP interfaces in Node are designed to support many features +of the protocol which have been traditionally difficult to use. +In particular, large, possibly chunk-encoded, messages. The interface is +careful to never buffer entire requests or responses--the +user is able to stream data. + +

+

HTTP message headers are represented by an object like this: + +

+
{ 'content-length': '123',
+  'content-type': 'text/plain',
+  'connection': 'keep-alive',
+  'accept': '*/*' }
+

Keys are lowercased. Values are not modified. + +

+

In order to support the full spectrum of possible HTTP applications, Node's +HTTP API is very low-level. It deals with stream handling and message +parsing only. It parses a message into headers and body but it does not +parse the actual headers or the body. + + +

+

http.createServer([requestListener])#

+

Returns a new web server object. + +

+

The requestListener is a function which is automatically +added to the 'request' event. + +

+

Class: http.Server#

+

This is an EventEmitter with the following events: + +

+

Event: 'request'#

+

function (request, response) { } + +

+

Emitted each time there is a request. Note that there may be multiple requests +per connection (in the case of keep-alive connections). + request is an instance of http.ServerRequest and response is + an instance of http.ServerResponse + +

+

Event: 'connection'#

+

function (socket) { } + +

+

When a new TCP stream is established. socket is an object of type + net.Socket. Usually users will not want to access this event. The + socket can also be accessed at request.connection. + +

+

Event: 'close'#

+

function () { } + +

+

Emitted when the server closes. + +

+

Event: 'checkContinue'#

+

function (request, response) { } + +

+

Emitted each time a request with an http Expect: 100-continue is received. +If this event isn't listened for, the server will automatically respond +with a 100 Continue as appropriate. + +

+

Handling this event involves calling response.writeContinue if the client +should continue to send the request body, or generating an appropriate HTTP +response (e.g., 400 Bad Request) if the client should not continue to send the +request body. + +

+

Note that when this event is emitted and handled, the request event will +not be emitted. + +

+

Event: 'upgrade'#

+

function (request, socket, head) { } + +

+

Emitted each time a client requests a http upgrade. If this event isn't +listened for, then clients requesting an upgrade will have their connections +closed. + +

+
    +
  • request is the arguments for the http request, as it is in the request event.
    • +
  • socket is the network socket between the server and client.
    • +
  • head is an instance of Buffer, the first packet of the upgraded stream, this may be empty.
    • +
+

After this event is emitted, the request's socket will not have a data +event listener, meaning you will need to bind to it in order to handle data +sent to the server on that socket. + +

+

Event: 'clientError'#

+

function (exception) { } + +

+

If a client connection emits an 'error' event - it will forwarded here. + +

+

server.listen(port, [hostname], [callback])#

+

Begin accepting connections on the specified port and hostname. If the +hostname is omitted, the server will accept connections directed to any +IPv4 address (INADDR_ANY). + +

+

To listen to a unix socket, supply a filename instead of port and hostname. + +

+

This function is asynchronous. The last parameter callback will be added as +a listener for the 'listening' event. +See also net.Server.listen(). + + +

+

server.listen(path, [callback])#

+

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

+

This function is asynchronous. The last parameter callback will be added as +a listener for the 'listening' event. +See also net.Server.listen(). + + +

+

server.close()#

+

Stops the server from accepting new connections. +See net.Server.close(). + + +

+

Class: http.ServerRequest#

+

This object is created internally by a HTTP server -- not by +the user -- and passed as the first argument to a 'request' listener. + +

+

The request implements the Readable Stream +interface. This is an EventEmitter with the following events: + +

+

Event: 'data'#

+

function (chunk) { } + +

+

Emitted when a piece of the message body is received. The chunk is a string if +an encoding has been set with request.setEncoding(), otherwise it's a +Buffer. + +

+

Note that the data will be lost if there is no listener when a +ServerRequest emits a 'data' event. + +

+

Event: 'end'#

+

function () { } + +

+

Emitted exactly once for each request. After that, no more 'data' events +will be emitted on the request. + +

+

Event: 'close'#

+

function () { } + +

+

Indicates that the underlaying connection was terminated before +response.end() was called or able to flush. + +

+

Just like 'end', this event occurs only once per request, and no more 'data' +events will fire afterwards. + +

+

Note: 'close' can fire after 'end', but not vice versa. + +

+

request.method#

+

The request method as a string. Read only. Example: +'GET', 'DELETE'. + + +

+

request.url#

+

Request URL string. This contains only the URL that is +present in the actual HTTP request. If the request is: + +

+
GET /status?name=ryan HTTP/1.1\r\n
+Accept: text/plain\r\n
+\r\n
+

Then request.url will be: + +

+
'/status?name=ryan'
+

If you would like to parse the URL into its parts, you can use +require('url').parse(request.url). Example: + +

+
node> require('url').parse('/status?name=ryan')
+{ href: '/status?name=ryan',
+  search: '?name=ryan',
+  query: 'name=ryan',
+  pathname: '/status' }
+

If you would like to extract the params from the query string, +you can use the require('querystring').parse function, or pass +true as the second argument to require('url').parse. Example: + +

+
node> require('url').parse('/status?name=ryan', true)
+{ href: '/status?name=ryan',
+  search: '?name=ryan',
+  query: { name: 'ryan' },
+  pathname: '/status' }
+

request.headers#

+

Read only. + +

+

request.trailers#

+

Read only; HTTP trailers (if present). Only populated after the 'end' event. + +

+

request.httpVersion#

+

The HTTP protocol version as a string. Read only. Examples: +'1.1', '1.0'. +Also request.httpVersionMajor is the first integer and +request.httpVersionMinor is the second. + + +

+

request.setEncoding([encoding])#

+

Set the encoding for the request body. Either 'utf8' or 'binary'. Defaults +to null, which means that the 'data' event will emit a Buffer object.. + + +

+

request.pause()#

+

Pauses request from emitting events. Useful to throttle back an upload. + + +

+

request.resume()#

+

Resumes a paused request. + +

+

request.connection#

+

The net.Socket object associated with the connection. + + +

+

With HTTPS support, use request.connection.verifyPeer() and +request.connection.getPeerCertificate() to obtain the client's +authentication details. + + + +

+

Class: http.ServerResponse#

+

This object is created internally by a HTTP server--not by the user. It is +passed as the second parameter to the 'request' event. + +

+

The response implements the Writable Stream +interface. This is an EventEmitter with the following events: + +

+

Event: 'close'#

+

function () { } + +

+

Indicates that the underlaying connection was terminated before +response.end() was called or able to flush. + +

+

response.writeContinue()#

+

Sends a HTTP/1.1 100 Continue message to the client, indicating that +the request body should be sent. See the checkContinue event on +Server. + +

+

response.writeHead(statusCode, [reasonPhrase], [headers])#

+

Sends a response header to the request. The status code is a 3-digit HTTP +status code, like 404. The last argument, headers, are the response headers. +Optionally one can give a human-readable reasonPhrase as the second +argument. + +

+

Example: + +

+
var body = 'hello world';
+response.writeHead(200, {
+  'Content-Length': body.length,
+  'Content-Type': 'text/plain' });
+

This method must only be called once on a message and it must +be called before response.end() is called. + +

+

If you call response.write() or response.end() before calling this, the +implicit/mutable headers will be calculated and call this function for you. + +

+

Note: that Content-Length is given in bytes not characters. The above example +works because the string 'hello world' contains only single byte characters. +If the body contains higher coded characters then Buffer.byteLength() +should be used to determine the number of bytes in a given encoding. +And Node does not check whether Content-Length and the length of the body +which has been transmitted are equal or not. + +

+

response.statusCode#

+

When using implicit headers (not calling response.writeHead() explicitly), this property +controls the status code that will be send to the client when the headers get +flushed. + +

+

Example: + +

+
response.statusCode = 404;
+

After response header was sent to the client, this property indicates the +status code which was sent out. + +

+

response.setHeader(name, value)#

+

Sets a single header value for implicit headers. If this header already exists +in the to-be-sent headers, its value will be replaced. Use an array of strings +here if you need to send multiple headers with the same name. + +

+

Example: + +

+
response.setHeader("Content-Type", "text/html");
+

or + +

+
response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]);
+

response.getHeader(name)#

+

Reads out a header that's already been queued but not sent to the client. Note +that the name is case insensitive. This can only be called before headers get +implicitly flushed. + +

+

Example: + +

+
var contentType = response.getHeader('content-type');
+

response.removeHeader(name)#

+

Removes a header that's queued for implicit sending. + +

+

Example: + +

+
response.removeHeader("Content-Encoding");
+

response.write(chunk, [encoding])#

+

If this method is called and response.writeHead() has not been called, it will +switch to implicit header mode and flush the implicit headers. + +

+

This sends a chunk of the response body. This method may +be called multiple times to provide successive parts of the body. + +

+

chunk can be a string or a buffer. If chunk is a string, +the second parameter specifies how to encode it into a byte stream. +By default the encoding is 'utf8'. + +

+

Note: This is the raw HTTP body and has nothing to do with +higher-level multi-part body encodings that may be used. + +

+

The first time response.write() is called, it will send the buffered +header information and the first body to the client. The second time +response.write() is called, Node assumes you're going to be streaming +data, and sends that separately. That is, the response is buffered up to the +first chunk of body. + +

+

response.addTrailers(headers)#

+

This method adds HTTP trailing headers (a header but at the end of the +message) to the response. + +

+

Trailers will only be emitted if chunked encoding is used for the +response; if it is not (e.g., if the request was HTTP/1.0), they will +be silently discarded. + +

+

Note that HTTP requires the Trailer header to be sent if you intend to +emit trailers, with a list of the header fields in its value. E.g., + +

+
response.writeHead(200, { 'Content-Type': 'text/plain',
+                          'Trailer': 'Content-MD5' });
+response.write(fileData);
+response.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});
+response.end();
+

response.end([data], [encoding])#

+

This method signals to the server that all of the response headers and body +has been sent; that server should consider this message complete. +The method, response.end(), MUST be called on each +response. + +

+

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

+

http.request(options, callback)#

+

Node maintains several connections per server to make HTTP requests. +This function allows one to transparently issue requests. options align +with url.parse(). + +

+

Options: + +

+
    +
  • host: A domain name or IP address of the server to issue the request to. +Defaults to 'localhost'.
    • +
  • hostname: To support url.parse() hostname is preferred over host
    • +
  • port: Port of remote server. Defaults to 80.
    • +
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • +
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • +
  • path: Request path. Defaults to '/'. Should include query string if any. +E.G. '/index.html?page=12'
    • +
  • headers: An object containing request headers.
    • +
  • auth: Basic authentication i.e. 'user:password' to compute an +Authorization header.
    • +
  • agent: Controls Agent behavior. When an Agent is used +request will default to Connection: keep-alive. Possible values:
      +
    • undefined (default): use global Agent for this host +and port.
      • +
    • Agent object: explicitly use the passed in Agent.
      • +
    • false: opts out of connection pooling with an Agent, defaults request to +Connection: close.
      • +
    +
    • +
+

http.request() returns an instance of the http.ClientRequest +class. The ClientRequest instance is a writable stream. If one needs to +upload a file with a POST request, then write to the ClientRequest object. + +

+

Example: + +

+
var options = {
+  host: 'www.google.com',
+  port: 80,
+  path: '/upload',
+  method: 'POST'
+};
+
+var req = http.request(options, function(res) {
+  console.log('STATUS: ' + res.statusCode);
+  console.log('HEADERS: ' + JSON.stringify(res.headers));
+  res.setEncoding('utf8');
+  res.on('data', function (chunk) {
+    console.log('BODY: ' + chunk);
+  });
+});
+
+req.on('error', function(e) {
+  console.log('problem with request: ' + e.message);
+});
+
+// write data to request body
+req.write('data\n');
+req.write('data\n');
+req.end();
+

Note that in the example req.end() was called. With http.request() one +must always call req.end() to signify that you're done with the request - +even if there is no data being written to the request body. + +

+

If any error is encountered during the request (be that with DNS resolution, +TCP level errors, or actual HTTP parse errors) an 'error' event is emitted +on the returned request object. + +

+

There are a few special headers that should be noted. + +

+
    +

  • Sending a 'Connection: keep-alive' will notify Node that the connection to +the server should be persisted until the next request.

    +
    • +

  • Sending a 'Content-length' header will disable the default chunked encoding.

    +
    • +

  • Sending an 'Expect' header will immediately send the request headers. +Usually, when sending 'Expect: 100-continue', you should both set a timeout +and listen for the continue event. See RFC2616 Section 8.2.3 for more +information.

    +
    • +

  • Sending an Authorization header will override using the auth option +to compute basic authentication.

    +
    • +
+

http.get(options, callback)#

+

Since most requests are GET requests without bodies, Node provides this +convenience method. The only difference between this method and http.request() is +that it sets the method to GET and calls req.end() automatically. + +

+

Example: + +

+
var options = {
+  host: 'www.google.com',
+  port: 80,
+  path: '/index.html'
+};
+
+http.get(options, function(res) {
+  console.log("Got response: " + res.statusCode);
+}).on('error', function(e) {
+  console.log("Got error: " + e.message);
+});
+

Class: http.Agent#

+

In node 0.5.3+ there is a new implementation of the HTTP Agent which is used +for pooling sockets used in HTTP client requests. + +

+

Previously, a single agent instance help the pool for single host+port. The +current implementation now holds sockets for any number of hosts. + +

+

The current HTTP Agent also defaults client requests to using +Connection:keep-alive. If no pending HTTP requests are waiting on a socket +to become free the socket is closed. This means that node's pool has the +benefit of keep-alive when under load but still does not require developers +to manually close the HTTP clients using keep-alive. + +

+

Sockets are removed from the agent's pool when the socket emits either a +"close" event or a special "agentRemove" event. This means that if you intend +to keep one HTTP request open for a long time and don't want it to stay in the +pool you can do something along the lines of: + +

+
http.get(options, function(res) {
+  // Do stuff
+}).on("socket", function (socket) {
+  socket.emit("agentRemove");
+});
+

Alternatively, you could just opt out of pooling entirely using agent:false: + +

+
http.get({host:'localhost', port:80, path:'/', agent:false}, function (res) {
+  // Do stuff
+})
+

agent.maxSockets#

+

By default set to 5. Determines how many concurrent sockets the agent can have +open per host. + +

+

agent.sockets#

+

An object which contains arrays of sockets currently in use by the Agent. Do not +modify. + +

+

agent.requests#

+

An object which contains queues of requests that have not yet been assigned to +sockets. Do not modify. + +

+

http.globalAgent#

+

Global instance of Agent which is used as the default for all http client +requests. + + +

+

Class: http.ClientRequest#

+

This object is created internally and returned from http.request(). It +represents an in-progress request whose header has already been queued. The +header is still mutable using the setHeader(name, value), getHeader(name), +removeHeader(name) API. The actual header will be sent along with the first +data chunk or when closing the connection. + +

+

To get the response, add a listener for 'response' to the request object. +'response' will be emitted from the request object when the response +headers have been received. The 'response' event is executed with one +argument which is an instance of http.ClientResponse. + +

+

During the 'response' event, one can add listeners to the +response object; particularly to listen for the 'data' event. Note that +the 'response' event is called before any part of the response body is received, +so there is no need to worry about racing to catch the first part of the +body. As long as a listener for 'data' is added during the 'response' +event, the entire body will be caught. + + +

+
// Good
+request.on('response', function (response) {
+  response.on('data', function (chunk) {
+    console.log('BODY: ' + chunk);
+  });
+});
+
+// Bad - misses all or part of the body
+request.on('response', function (response) {
+  setTimeout(function () {
+    response.on('data', function (chunk) {
+      console.log('BODY: ' + chunk);
+    });
+  }, 10);
+});
+

Note: Node does not check whether Content-Length and the length of the body +which has been transmitted are equal or not. + +

+

The request implements the Writable Stream +interface. This is an EventEmitter with the following events: + +

+

Event 'response'#

+

function (response) { } + +

+

Emitted when a response is received to this request. This event is emitted only once. The +response argument will be an instance of http.ClientResponse. + +

+

Options: + +

+
    +
  • host: A domain name or IP address of the server to issue the request to.
    • +
  • port: Port of remote server.
    • +
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • +
+

Event: 'socket'#

+

function (socket) { } + +

+

Emitted after a socket is assigned to this request. + +

+

Event: 'upgrade'#

+

function (response, 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. + +

+

A client server pair that show you how to listen for the upgrade event using http.getAgent: + +

+
var http = require('http');
+var net = require('net');
+
+// Create an HTTP server
+var srv = http.createServer(function (req, res) {
+  res.writeHead(200, {'Content-Type': 'text/plain'});
+  res.end('okay');
+});
+srv.on('upgrade', function(req, socket, upgradeHead) {
+  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
+               'Upgrade: WebSocket\r\n' +
+               'Connection: Upgrade\r\n' +
+               '\r\n\r\n');
+
+  socket.ondata = function(data, start, end) {
+    socket.write(data.toString('utf8', start, end), 'utf8'); // echo back
+  };
+});
+
+// now that server is running
+srv.listen(1337, '127.0.0.1', function() {
+
+  // make a request
+  var options = {
+    port: 1337,
+    host: '127.0.0.1',
+    headers: {
+      'Connection': 'Upgrade',
+      'Upgrade': 'websocket'
+    }
+  };
+
+  var req = http.request(options);
+  req.end();
+
+  req.on('upgrade', function(res, socket, upgradeHead) {
+    console.log('got upgraded!');
+    socket.end();
+    process.exit(0);
+  });
+});
+

Event: 'continue'#

+

function () { } + +

+

Emitted when the server sends a '100 Continue' HTTP response, usually because +the request contained 'Expect: 100-continue'. This is an instruction that +the client should send the request body. + +

+

request.write(chunk, [encoding])#

+

Sends a chunk of the body. By calling this method +many times, the user can stream a request body to a +server--in that case it is suggested to use the +['Transfer-Encoding', 'chunked'] header line when +creating the request. + +

+

The chunk argument should be a buffer or a string. + +

+

The encoding argument is optional and only applies when chunk is a string. +Defaults to 'utf8'. + + +

+

request.end([data], [encoding])#

+

Finishes sending the request. If any parts of the body are +unsent, it will flush them to the stream. If the request is +chunked, this will send the terminating '0\r\n\r\n'. + +

+

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

+

request.abort()#

+

Aborts a request. (New since v0.3.8.) + +

+

request.setTimeout(timeout, [callback])#

+

Once a socket is assigned to this request and is connected +socket.setTimeout(timeout, [callback]) +will be called. + +

+

request.setNoDelay([noDelay])#

+

Once a socket is assigned to this request and is connected +socket.setNoDelay(noDelay) +will be called. + +

+

request.setSocketKeepAlive([enable], [initialDelay])#

+

Once a socket is assigned to this request and is connected +socket.setKeepAlive(enable, [initialDelay]) +will be called. + +

+

http.ClientResponse#

+

This object is created when making a request with http.request(). It is +passed to the 'response' event of the request object. + +

+

The response implements the Readable Stream +interface. This is an EventEmitter with the following events: + + +

+

Event: 'data'#

+

function (chunk) { } + +

+

Emitted when a piece of the message body is received. + +

+

Note that the data will be lost if there is no listener when a +ClientResponse emits a 'data' event. + + +

+

Event: 'end'#

+

function () { } + +

+

Emitted exactly once for each message. No arguments. After +emitted no other events will be emitted on the response. + +

+

Event: 'close'#

+

function (err) { } + +

+

Indicates that the underlaying connection was terminated before +end event was emitted. +See http.ServerRequest's 'close' event for more +information. + +

+

response.statusCode#

+

The 3-digit HTTP response status code. E.G. 404. + +

+

response.httpVersion#

+

The HTTP version of the connected-to server. Probably either +'1.1' or '1.0'. +Also response.httpVersionMajor is the first integer and +response.httpVersionMinor is the second. + +

+

response.headers#

+

The response headers object. + +

+

response.trailers#

+

The response trailers object. Only populated after the 'end' event. + +

+

response.setEncoding([encoding])#

+

Set the encoding for the response body. Either 'utf8', 'ascii', or +'base64'. Defaults to null, which means that the 'data' event will emit +a Buffer object. + +

+

response.pause()#

+

Pauses response from emitting events. Useful to throttle back a download. + +

+

response.resume()#

+

Resumes a paused response. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/stream.html @@ -0,0 +1,310 @@ + + + + + Stream Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Stream#

+
Stability: 2 - Unstable
+

A stream is an abstract interface implemented by various objects in Node. +For example a request to an HTTP server is a stream, as is stdout. Streams +are readable, writable, or both. All streams are instances of EventEmitter. + +

+

You can load up the Stream base class by doing require('stream'). + +

+

Readable Stream#

+ + +

A Readable Stream has the following methods, members, and events. + +

+

Event: 'data'#

+

function (data) { } + +

+

The 'data' event emits either a Buffer (by default) or a string if +setEncoding() was used. + +

+

Note that the data will be lost if there is no listener when a +Readable Stream emits a 'data' event. + +

+

Event: 'end'#

+

function () { } + +

+

Emitted when the stream has received an EOF (FIN in TCP terminology). +Indicates that no more 'data' events will happen. If the stream is also +writable, it may be possible to continue writing. + +

+

Event: 'error'#

+

function (exception) { } + +

+

Emitted if there was an error receiving data. + +

+

Event: 'close'#

+

function () { } + +

+

Emitted when the underlying file descriptor has been closed. Not all streams +will emit this. (For example, an incoming HTTP request will not emit +'close'.) + +

+

stream.readable#

+

A boolean that is true by default, but turns false after an 'error' +occurred, the stream came to an 'end', or destroy() was called. + +

+

stream.setEncoding(encoding)#

+

Makes the data event emit a string instead of a Buffer. encoding can be +'utf8', 'ascii', or 'base64'. + +

+

stream.pause()#

+

Pauses the incoming 'data' events. + +

+

stream.resume()#

+

Resumes the incoming 'data' events after a pause(). + +

+

stream.destroy()#

+

Closes the underlying file descriptor. Stream will not emit any more events. + +

+

stream.pipe(destination, [options])#

+

This is a Stream.prototype method available on all Streams. + +

+

Connects this read stream to destination WriteStream. Incoming +data on this stream gets written to destination. The destination and source +streams are kept in sync by pausing and resuming as necessary. + +

+

This function returns the destination stream. + +

+

Emulating the Unix cat command: + +

+
process.stdin.resume();
+process.stdin.pipe(process.stdout);
+

By default end() is called on the destination when the source stream emits +end, so that destination is no longer writable. Pass { end: false } as +options to keep the destination stream open. + +

+

This keeps process.stdout open so that "Goodbye" can be written at the end. + +

+
process.stdin.resume();
+
+process.stdin.pipe(process.stdout, { end: false });
+
+process.stdin.on("end", function() {
+  process.stdout.write("Goodbye\n");
+});
+

Writable Stream#

+ + +

A Writable Stream has the following methods, members, and events. + +

+

Event: 'drain'#

+

function () { } + +

+

After a write() method returned false, this event is emitted to +indicate that it is safe to write again. + +

+

Event: 'error'#

+

function (exception) { } + +

+

Emitted on error with the exception exception. + +

+

Event: 'close'#

+

function () { } + +

+

Emitted when the underlying file descriptor has been closed. + +

+

Event: 'pipe'#

+

function (src) { } + +

+

Emitted when the stream is passed to a readable stream's pipe method. + +

+

stream.writable#

+

A boolean that is true by default, but turns false after an 'error' +occurred or end() / destroy() was called. + +

+

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)#

+

Same as the above except with a raw buffer. + +

+

stream.end()#

+

Terminates the stream with EOF or FIN. +This call will allow queued write data to be sent before closing the stream. + +

+

stream.end(string, encoding)#

+

Sends string with the given encoding and terminates the stream with EOF +or FIN. This is useful to reduce the number of packets sent. + +

+

stream.end(buffer)#

+

Same as above but with a buffer. + +

+

stream.destroy()#

+

Closes the underlying file descriptor. Stream will not emit any more events. +Any queued write data will not be sent. + +

+

stream.destroySoon()#

+

After the write queue is drained, close the file descriptor. destroySoon() +can still destroy straight away, as long as there is no data left in the queue +for writes. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/string_decoder.html @@ -0,0 +1,87 @@ + + + + + Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ +
+

Table of Contents

+ +
+ +
+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/os.json @@ -0,0 +1,137 @@ +{ + "source": "doc/api/os.markdown", + "modules": [ + { + "textRaw": "os", + "name": "os", + "stability": 4, + "stabilityText": "API Frozen", + "desc": "

Provides a few basic operating-system related utility functions.\n\n

\n

Use require('os') to access this module.\n\n

\n", + "methods": [ + { + "textRaw": "os.hostname()", + "type": "method", + "name": "hostname", + "desc": "

Returns the hostname of the operating system.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.type()", + "type": "method", + "name": "type", + "desc": "

Returns the operating system name.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.platform()", + "type": "method", + "name": "platform", + "desc": "

Returns the operating system platform.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.arch()", + "type": "method", + "name": "arch", + "desc": "

Returns the operating system CPU architecture.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.release()", + "type": "method", + "name": "release", + "desc": "

Returns the operating system release.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.uptime()", + "type": "method", + "name": "uptime", + "desc": "

Returns the system uptime in seconds.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.loadavg()", + "type": "method", + "name": "loadavg", + "desc": "

Returns an array containing the 1, 5, and 15 minute load averages.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.totalmem()", + "type": "method", + "name": "totalmem", + "desc": "

Returns the total amount of system memory in bytes.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.freemem()", + "type": "method", + "name": "freemem", + "desc": "

Returns the amount of free system memory in bytes.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.cpus()", + "type": "method", + "name": "cpus", + "desc": "

Returns an array of objects containing information about each CPU/core installed: model, speed (in MHz), and times (an object containing the number of CPU ticks spent in: user, nice, sys, idle, and irq).\n\n

\n

Example inspection of os.cpus:\n\n

\n
[ { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 252020,\n       nice: 0,\n       sys: 30340,\n       idle: 1070356870,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 306960,\n       nice: 0,\n       sys: 26980,\n       idle: 1071569080,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 248450,\n       nice: 0,\n       sys: 21750,\n       idle: 1070919370,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 256880,\n       nice: 0,\n       sys: 19430,\n       idle: 1070905480,\n       irq: 20 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 511580,\n       nice: 20,\n       sys: 40900,\n       idle: 1070842510,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 291660,\n       nice: 0,\n       sys: 34360,\n       idle: 1070888000,\n       irq: 10 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 308260,\n       nice: 0,\n       sys: 55410,\n       idle: 1071129970,\n       irq: 880 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 266450,\n       nice: 1480,\n       sys: 34920,\n       idle: 1072572010,\n       irq: 30 } } ]
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.networkInterfaces()", + "type": "method", + "name": "networkInterfaces", + "desc": "

Get a list of network interfaces:\n\n

\n
{ lo0: \n   [ { address: '::1', family: 'IPv6', internal: true },\n     { address: 'fe80::1', family: 'IPv6', internal: true },\n     { address: '127.0.0.1', family: 'IPv4', internal: true } ],\n  en1: \n   [ { address: 'fe80::cabc:c8ff:feef:f996', family: 'IPv6',\n       internal: false },\n     { address: '10.0.1.123', family: 'IPv4', internal: false } ],\n  vmnet1: [ { address: '10.99.99.254', family: 'IPv4', internal: false } ],\n  vmnet8: [ { address: '10.88.88.1', family: 'IPv4', internal: false } ],\n  ppp0: [ { address: '10.2.0.231', family: 'IPv4', internal: false } ] }
\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "type": "module", + "displayName": "os" + } + ] +} --- /dev/null +++ b/doc/api/buffer.json @@ -0,0 +1,1704 @@ +{ + "source": "doc/api/buffer.markdown", + "modules": [ + { + "textRaw": "Buffer", + "name": "buffer", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Pure Javascript is Unicode friendly but not nice to binary data. When\ndealing with TCP streams or the file system, it's necessary to handle octet\nstreams. Node has several strategies for manipulating, creating, and\nconsuming octet streams.\n\n

\n

Raw data is stored in instances of the Buffer class. A Buffer is similar\nto an array of integers but corresponds to a raw memory allocation outside\nthe V8 heap. A Buffer cannot be resized.\n\n

\n

The Buffer class is a global, making it very rare that one would need\nto ever require('buffer').\n\n

\n

Converting between Buffers and JavaScript string objects requires an explicit\nencoding method. Here are the different string encodings.\n\n

\n
    \n

  • 'ascii' - for 7 bit ASCII data only. This encoding method is very fast, and\nwill strip the high bit if set.\nNote that this encoding converts a null character ('\\0' or '\\u0000') into\n0x20 (character code of a space). If you want to convert a null character\ninto 0x00, you should use 'utf8'.

    \n
    • \n

  • 'utf8' - Multi byte encoded Unicode characters. Many web pages and other document formats use UTF-8.

    \n
    • \n

  • 'ucs2' - 2-bytes, little endian encoded Unicode characters. It can encode\nonly BMP(Basic Multilingual Plane, U+0000 - U+FFFF).

    \n
    • \n

  • 'base64' - Base64 string encoding.

    \n
    • \n

  • 'binary' - A way of encoding raw binary data into strings by using only\nthe first 8 bits of each character. This encoding method is deprecated and\nshould be avoided in favor of Buffer objects where possible. This encoding\nwill be removed in future versions of Node.

    \n
    • \n

  • 'hex' - Encode each byte as two hexidecimal characters.

    \n
    • \n
\n", + "classes": [ + { + "textRaw": "Class: Buffer", + "type": "class", + "name": "Buffer", + "desc": "

The Buffer class is a global type for dealing with binary data directly.\nIt can be constructed in a variety of ways.\n\n

\n", + "methods": [ + { + "textRaw": "buf.write(string, [offset], [length], [encoding])", + "type": "method", + "name": "write", + "signatures": [ + { + "params": [ + { + "textRaw": "`string` String - data to be written to buffer ", + "name": "string", + "desc": "String - data to be written to buffer" + }, + { + "textRaw": "`offset` Number, Optional, Default: 0 ", + "name": "offset", + "desc": "Number, Optional, Default: 0", + "optional": true + }, + { + "textRaw": "`length` Number, Optional, Default: `buffer.length - offset` ", + "name": "length", + "desc": "Number, Optional, Default: `buffer.length - offset`", + "optional": true + }, + { + "textRaw": "`encoding` String, Optional, Default: 'utf8' ", + "name": "encoding", + "desc": "String, Optional, Default: 'utf8'", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "string" + }, + { + "name": "offset", + "optional": true + }, + { + "name": "length", + "optional": true + }, + { + "name": "encoding", + "optional": true + } + ] + } + ], + "desc": "

Writes string to the buffer at offset using the given encoding.\noffset defaults to 0, encoding defaults to 'utf8'. length is\nthe number of bytes to write. Returns number of octets written. If buffer did\nnot contain enough space to fit the entire string, it will write a partial\namount of the string. length defaults to buffer.length - offset.\nThe method will not write partial characters.\n\n

\n
buf = new Buffer(256);\nlen = buf.write('\\u00bd + \\u00bc = \\u00be', 0);\nconsole.log(len + " bytes: " + buf.toString('utf8', 0, len));
\n

The number of characters written (which may be different than the number of\nbytes written) is set in Buffer._charsWritten and will be overwritten the\nnext time buf.write() is called.\n\n\n

\n" + }, + { + "textRaw": "buf.toString([encoding], [start], [end])", + "type": "method", + "name": "toString", + "signatures": [ + { + "params": [ + { + "textRaw": "`encoding` String, Optional, Default: 'utf8' ", + "name": "encoding", + "desc": "String, Optional, Default: 'utf8'", + "optional": true + }, + { + "textRaw": "`start` Number, Optional, Default: 0 ", + "name": "start", + "desc": "Number, Optional, Default: 0", + "optional": true + }, + { + "textRaw": "`end` Number, Optional, Default: `buffer.length` ", + "name": "end", + "desc": "Number, Optional, Default: `buffer.length`", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "encoding", + "optional": true + }, + { + "name": "start", + "optional": true + }, + { + "name": "end", + "optional": true + } + ] + } + ], + "desc": "

Decodes and returns a string from buffer data encoded with encoding\n(defaults to 'utf8') beginning at start (defaults to 0) and ending at\nend (defaults to buffer.length).\n\n

\n

See buffer.write() example, above.\n\n\n

\n" + }, + { + "textRaw": "buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])", + "type": "method", + "name": "copy", + "signatures": [ + { + "params": [ + { + "textRaw": "`targetBuffer` Buffer object - Buffer to copy into ", + "name": "targetBuffer", + "desc": "Buffer object - Buffer to copy into" + }, + { + "textRaw": "`targetStart` Number, Optional, Default: 0 ", + "name": "targetStart", + "desc": "Number, Optional, Default: 0", + "optional": true + }, + { + "textRaw": "`sourceStart` Number, Optional, Default: 0 ", + "name": "sourceStart", + "desc": "Number, Optional, Default: 0", + "optional": true + }, + { + "textRaw": "`sourceEnd` Number, Optional, Default: `buffer.length` ", + "name": "sourceEnd", + "desc": "Number, Optional, Default: `buffer.length`", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "targetBuffer" + }, + { + "name": "targetStart", + "optional": true + }, + { + "name": "sourceStart", + "optional": true + }, + { + "name": "sourceEnd", + "optional": true + } + ] + } + ], + "desc": "

Does copy between buffers. The source and target regions can be overlapped.\ntargetStart and sourceStart default to 0.\nsourceEnd defaults to buffer.length.\n\n

\n

Example: build two Buffers, then copy buf1 from byte 16 through byte 19\ninto buf2, starting at the 8th byte in buf2.\n\n

\n
buf1 = new Buffer(26);\nbuf2 = new Buffer(26);\n\nfor (var i = 0 ; i < 26 ; i++) {\n  buf1[i] = i + 97; // 97 is ASCII a\n  buf2[i] = 33; // ASCII !\n}\n\nbuf1.copy(buf2, 8, 16, 20);\nconsole.log(buf2.toString('ascii', 0, 25));\n\n// !!!!!!!!qrst!!!!!!!!!!!!!
\n" + }, + { + "textRaw": "buf.slice([start], [end])", + "type": "method", + "name": "slice", + "signatures": [ + { + "params": [ + { + "textRaw": "`start` Number, Optional, Default: 0 ", + "name": "start", + "desc": "Number, Optional, Default: 0", + "optional": true + }, + { + "textRaw": "`end` Number, Optional, Default: `buffer.length` ", + "name": "end", + "desc": "Number, Optional, Default: `buffer.length`", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "start", + "optional": true + }, + { + "name": "end", + "optional": true + } + ] + } + ], + "desc": "

Returns a new buffer which references the same memory as the old, but offset\nand cropped by the start (defaults to 0) and end (defaults to\nbuffer.length) indexes.\n\n

\n

Modifying the new buffer slice will modify memory in the original buffer!\n\n

\n

Example: build a Buffer with the ASCII alphabet, take a slice, then modify one\nbyte from the original Buffer.\n\n

\n
var buf1 = new Buffer(26);\n\nfor (var i = 0 ; i < 26 ; i++) {\n  buf1[i] = i + 97; // 97 is ASCII a\n}\n\nvar buf2 = buf1.slice(0, 3);\nconsole.log(buf2.toString('ascii', 0, buf2.length));\nbuf1[0] = 33;\nconsole.log(buf2.toString('ascii', 0, buf2.length));\n\n// abc\n// !bc
\n" + }, + { + "textRaw": "buf.readUInt8(offset, [noAssert])", + "type": "method", + "name": "readUInt8", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads an unsigned 8 bit integer from the buffer at the specified offset.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nfor (ii = 0; ii < buf.length; ii++) {\n  console.log(buf.readUInt8(ii));\n}\n\n// 0x3\n// 0x4\n// 0x23\n// 0x42
\n" + }, + { + "textRaw": "buf.readUInt16LE(offset, [noAssert])", + "type": "method", + "name": "readUInt16LE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads an unsigned 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt16BE(0));\nconsole.log(buf.readUInt16LE(0));\nconsole.log(buf.readUInt16BE(1));\nconsole.log(buf.readUInt16LE(1));\nconsole.log(buf.readUInt16BE(2));\nconsole.log(buf.readUInt16LE(2));\n\n// 0x0304\n// 0x0403\n// 0x0423\n// 0x2304\n// 0x2342\n// 0x4223
\n" + }, + { + "textRaw": "buf.readUInt16BE(offset, [noAssert])", + "type": "method", + "name": "readUInt16BE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads an unsigned 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt16BE(0));\nconsole.log(buf.readUInt16LE(0));\nconsole.log(buf.readUInt16BE(1));\nconsole.log(buf.readUInt16LE(1));\nconsole.log(buf.readUInt16BE(2));\nconsole.log(buf.readUInt16LE(2));\n\n// 0x0304\n// 0x0403\n// 0x0423\n// 0x2304\n// 0x2342\n// 0x4223
\n" + }, + { + "textRaw": "buf.readUInt32LE(offset, [noAssert])", + "type": "method", + "name": "readUInt32LE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads an unsigned 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt32BE(0));\nconsole.log(buf.readUInt32LE(0));\n\n// 0x03042342\n// 0x42230403
\n" + }, + { + "textRaw": "buf.readUInt32BE(offset, [noAssert])", + "type": "method", + "name": "readUInt32BE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads an unsigned 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt32BE(0));\nconsole.log(buf.readUInt32LE(0));\n\n// 0x03042342\n// 0x42230403
\n" + }, + { + "textRaw": "buf.readInt8(offset, [noAssert])", + "type": "method", + "name": "readInt8", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a signed 8 bit integer from the buffer at the specified offset.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt8, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" + }, + { + "textRaw": "buf.readInt16LE(offset, [noAssert])", + "type": "method", + "name": "readInt16LE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a signed 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt16*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" + }, + { + "textRaw": "buf.readInt16BE(offset, [noAssert])", + "type": "method", + "name": "readInt16BE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a signed 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt16*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" + }, + { + "textRaw": "buf.readInt32LE(offset, [noAssert])", + "type": "method", + "name": "readInt32LE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a signed 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt32*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" + }, + { + "textRaw": "buf.readInt32BE(offset, [noAssert])", + "type": "method", + "name": "readInt32BE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a signed 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt32*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" + }, + { + "textRaw": "buf.readFloatLE(offset, [noAssert])", + "type": "method", + "name": "readFloatLE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a 32 bit float from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x00;\nbuf[1] = 0x00;\nbuf[2] = 0x80;\nbuf[3] = 0x3f;\n\nconsole.log(buf.readFloatLE(0));\n\n// 0x01
\n" + }, + { + "textRaw": "buf.readFloatBE(offset, [noAssert])", + "type": "method", + "name": "readFloatBE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a 32 bit float from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x00;\nbuf[1] = 0x00;\nbuf[2] = 0x80;\nbuf[3] = 0x3f;\n\nconsole.log(buf.readFloatLE(0));\n\n// 0x01
\n" + }, + { + "textRaw": "buf.readDoubleLE(offset, [noAssert])", + "type": "method", + "name": "readDoubleLE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a 64 bit double from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\n\nbuf[0] = 0x55;\nbuf[1] = 0x55;\nbuf[2] = 0x55;\nbuf[3] = 0x55;\nbuf[4] = 0x55;\nbuf[5] = 0x55;\nbuf[6] = 0xd5;\nbuf[7] = 0x3f;\n\nconsole.log(buf.readDoubleLE(0));\n\n// 0.3333333333333333
\n" + }, + { + "textRaw": "buf.readDoubleBE(offset, [noAssert])", + "type": "method", + "name": "readDoubleBE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a 64 bit double from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\n\nbuf[0] = 0x55;\nbuf[1] = 0x55;\nbuf[2] = 0x55;\nbuf[3] = 0x55;\nbuf[4] = 0x55;\nbuf[5] = 0x55;\nbuf[6] = 0xd5;\nbuf[7] = 0x3f;\n\nconsole.log(buf.readDoubleLE(0));\n\n// 0.3333333333333333
\n" + }, + { + "textRaw": "buf.writeUInt8(value, offset, [noAssert])", + "type": "method", + "name": "writeUInt8", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset. Note, value must be a\nvalid unsigned 8 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt8(0x3, 0);\nbuf.writeUInt8(0x4, 1);\nbuf.writeUInt8(0x23, 2);\nbuf.writeUInt8(0x42, 3);\n\nconsole.log(buf);\n\n// <Buffer 03 04 23 42>
\n" + }, + { + "textRaw": "buf.writeUInt16LE(value, offset, [noAssert])", + "type": "method", + "name": "writeUInt16LE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt16BE(0xdead, 0);\nbuf.writeUInt16BE(0xbeef, 2);\n\nconsole.log(buf);\n\nbuf.writeUInt16LE(0xdead, 0);\nbuf.writeUInt16LE(0xbeef, 2);\n\nconsole.log(buf);\n\n// <Buffer de ad be ef>\n// <Buffer ad de ef be>
\n" + }, + { + "textRaw": "buf.writeUInt16BE(value, offset, [noAssert])", + "type": "method", + "name": "writeUInt16BE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt16BE(0xdead, 0);\nbuf.writeUInt16BE(0xbeef, 2);\n\nconsole.log(buf);\n\nbuf.writeUInt16LE(0xdead, 0);\nbuf.writeUInt16LE(0xbeef, 2);\n\nconsole.log(buf);\n\n// <Buffer de ad be ef>\n// <Buffer ad de ef be>
\n" + }, + { + "textRaw": "buf.writeUInt32LE(value, offset, [noAssert])", + "type": "method", + "name": "writeUInt32LE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt32BE(0xfeedface, 0);\n\nconsole.log(buf);\n\nbuf.writeUInt32LE(0xfeedface, 0);\n\nconsole.log(buf);\n\n// <Buffer fe ed fa ce>\n// <Buffer ce fa ed fe>
\n" + }, + { + "textRaw": "buf.writeUInt32BE(value, offset, [noAssert])", + "type": "method", + "name": "writeUInt32BE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt32BE(0xfeedface, 0);\n\nconsole.log(buf);\n\nbuf.writeUInt32LE(0xfeedface, 0);\n\nconsole.log(buf);\n\n// <Buffer fe ed fa ce>\n// <Buffer ce fa ed fe>
\n" + }, + { + "textRaw": "buf.writeInt8(value, offset, [noAssert])", + "type": "method", + "name": "writeInt8", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset. Note, value must be a\nvalid signed 8 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt8, except value is written out as a two's complement\nsigned integer into buffer.\n\n

\n" + }, + { + "textRaw": "buf.writeInt16LE(value, offset, [noAssert])", + "type": "method", + "name": "writeInt16LE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt16*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" + }, + { + "textRaw": "buf.writeInt16BE(value, offset, [noAssert])", + "type": "method", + "name": "writeInt16BE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt16*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" + }, + { + "textRaw": "buf.writeInt32LE(value, offset, [noAssert])", + "type": "method", + "name": "writeInt32LE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt32*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" + }, + { + "textRaw": "buf.writeInt32BE(value, offset, [noAssert])", + "type": "method", + "name": "writeInt32BE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt32*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" + }, + { + "textRaw": "buf.writeFloatLE(value, offset, [noAssert])", + "type": "method", + "name": "writeFloatLE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 32 bit float.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeFloatBE(0xcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeFloatLE(0xcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 4f 4a fe bb>\n// <Buffer bb fe 4a 4f>
\n" + }, + { + "textRaw": "buf.writeFloatBE(value, offset, [noAssert])", + "type": "method", + "name": "writeFloatBE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 32 bit float.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeFloatBE(0xcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeFloatLE(0xcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 4f 4a fe bb>\n// <Buffer bb fe 4a 4f>
\n" + }, + { + "textRaw": "buf.writeDoubleLE(value, offset, [noAssert])", + "type": "method", + "name": "writeDoubleLE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 64 bit double.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\nbuf.writeDoubleBE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeDoubleLE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 43 eb d5 b7 dd f9 5f d7>\n// <Buffer d7 5f f9 dd b7 d5 eb 43>
\n" + }, + { + "textRaw": "buf.writeDoubleBE(value, offset, [noAssert])", + "type": "method", + "name": "writeDoubleBE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 64 bit double.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\nbuf.writeDoubleBE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeDoubleLE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 43 eb d5 b7 dd f9 5f d7>\n// <Buffer d7 5f f9 dd b7 d5 eb 43>
\n" + }, + { + "textRaw": "buf.fill(value, [offset], [end])", + "type": "method", + "name": "fill", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` ", + "name": "value" + }, + { + "textRaw": "`offset` Number, Optional ", + "name": "offset", + "optional": true, + "desc": "Number" + }, + { + "textRaw": "`end` Number, Optional ", + "name": "end", + "optional": true, + "desc": "Number" + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset", + "optional": true + }, + { + "name": "end", + "optional": true + } + ] + } + ], + "desc": "

Fills the buffer with the specified value. If the offset (defaults to 0)\nand end (defaults to buffer.length) are not given it will fill the entire\nbuffer.\n\n

\n
var b = new Buffer(50);\nb.fill("h");
\n" + } + ], + "properties": [ + { + "textRaw": "buf[index]", + "name": "[index]", + "desc": "

Get and set the octet at index. The values refer to individual bytes,\nso the legal range is between 0x00 and 0xFF hex or 0 and 255.\n\n

\n

Example: copy an ASCII string into a buffer, one byte at a time:\n\n

\n
str = "node.js";\nbuf = new Buffer(str.length);\n\nfor (var i = 0; i < str.length ; i++) {\n  buf[i] = str.charCodeAt(i);\n}\n\nconsole.log(buf);\n\n// node.js
\n" + }, + { + "textRaw": "`length` Number ", + "name": "length", + "desc": "

The size of the buffer in bytes. Note that this is not necessarily the size\nof the contents. length refers to the amount of memory allocated for the\nbuffer object. It does not change when the contents of the buffer are changed.\n\n

\n
buf = new Buffer(1234);\n\nconsole.log(buf.length);\nbuf.write("some string", "ascii", 0);\nconsole.log(buf.length);\n\n// 1234\n// 1234
\n", + "shortDesc": "Number" + } + ], + "classMethods": [ + { + "textRaw": "Class Method: Buffer.isBuffer(obj)", + "type": "classMethod", + "name": "isBuffer", + "signatures": [ + { + "return": { + "textRaw": "Return: Boolean ", + "name": "return", + "desc": "Boolean" + }, + "params": [ + { + "textRaw": "`obj` Object ", + "name": "obj", + "desc": "Object" + } + ] + }, + { + "params": [ + { + "name": "obj" + } + ] + } + ], + "desc": "

Tests if obj is a Buffer.\n\n

\n" + }, + { + "textRaw": "Class Method: Buffer.byteLength(string, [encoding])", + "type": "classMethod", + "name": "byteLength", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`string` String ", + "name": "string", + "desc": "String" + }, + { + "textRaw": "`encoding` String, Optional, Default: 'utf8' ", + "name": "encoding", + "desc": "String, Optional, Default: 'utf8'", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "string" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ], + "desc": "

Gives the actual byte length of a string. encoding defaults to 'utf8'.\nThis is not the same as String.prototype.length since that returns the\nnumber of characters in a string.\n\n

\n

Example:\n\n

\n
str = '\\u00bd + \\u00bc = \\u00be';\n\nconsole.log(str + ": " + str.length + " characters, " +\n  Buffer.byteLength(str, 'utf8') + " bytes");\n\n// ½ + ¼ = ¾: 9 characters, 12 bytes
\n" + } + ], + "signatures": [ + { + "params": [ + { + "textRaw": "`size` Number ", + "name": "size", + "desc": "Number" + } + ], + "desc": "

Allocates a new buffer of size octets.\n\n

\n" + }, + { + "params": [ + { + "name": "size" + } + ], + "desc": "

Allocates a new buffer of size octets.\n\n

\n" + }, + { + "params": [ + { + "textRaw": "`array` Array ", + "name": "array", + "desc": "Array" + } + ], + "desc": "

Allocates a new buffer using an array of octets.\n\n

\n" + }, + { + "params": [ + { + "name": "array" + } + ], + "desc": "

Allocates a new buffer using an array of octets.\n\n

\n" + }, + { + "params": [ + { + "textRaw": "`str` String - string to encode. ", + "name": "str", + "desc": "String - string to encode." + }, + { + "textRaw": "`encoding` String - encoding to use, Optional. ", + "name": "encoding", + "desc": "String - encoding to use, Optional.", + "optional": true + } + ], + "desc": "

Allocates a new buffer containing the given str.\nencoding defaults to 'utf8'.\n\n

\n" + }, + { + "params": [ + { + "name": "str" + }, + { + "name": "encoding", + "optional": true + } + ], + "desc": "

Allocates a new buffer containing the given str.\nencoding defaults to 'utf8'.\n\n

\n" + } + ] + }, + { + "textRaw": "Class: SlowBuffer", + "type": "class", + "name": "SlowBuffer", + "desc": "

This class is primarily for internal use. JavaScript programs should\nuse Buffer instead of using SlowBuffer.\n\n

\n

In order to avoid the overhead of allocating many C++ Buffer objects for\nsmall blocks of memory in the lifetime of a server, Node allocates memory\nin 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it\nwill be backed by a parent SlowBuffer object. If it is larger than this,\nthen Node will allocate a SlowBuffer slab for it directly.\n

\n" + } + ], + "properties": [ + { + "textRaw": "`INSPECT_MAX_BYTES` Number, Default: 50 ", + "name": "INSPECT_MAX_BYTES", + "desc": "

How many bytes will be returned when buffer.inspect() is called. This can\nbe overridden by user modules.\n\n

\n

Note that this is a property on the buffer module returned by\nrequire('buffer'), not on the Buffer global, or a buffer instance.\n\n

\n", + "shortDesc": "Number, Default: 50" + } + ], + "type": "module", + "displayName": "Buffer" + } + ] +} --- /dev/null +++ b/doc/api/querystring.html @@ -0,0 +1,141 @@ + + + + + Query String Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Query String#

+
Stability: 3 - Stable
+ + +

This module provides utilities for dealing with query strings. +It provides the following methods: + +

+

querystring.stringify(obj, [sep], [eq])#

+

Serialize an object to a query string. +Optionally override the default separator ('&') and assignment ('=') +characters. + +

+

Example: + +

+
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })
+// returns
+'foo=bar&baz=qux&baz=quux&corge='
+
+querystring.stringify({foo: 'bar', baz: 'qux'}, ';', ':')
+// returns
+'foo:bar;baz:qux'
+

querystring.parse(str, [sep], [eq])#

+

Deserialize a query string to an object. +Optionally override the default separator ('&') and assignment ('=') +characters. + +

+

Example: + +

+
querystring.parse('foo=bar&baz=qux&baz=quux&corge')
+// returns
+{ foo: 'bar', baz: ['qux', 'quux'], corge: '' }
+

querystring.escape#

+

The escape function used by querystring.stringify, +provided so that it could be overridden if necessary. + +

+

querystring.unescape#

+

The unescape function used by querystring.parse, +provided so that it could be overridden if necessary. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/index.json @@ -0,0 +1,382 @@ +{ + "source": "doc/api/index.markdown", + "desc": [ + { + "type": "list_start", + "ordered": false + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[About these Docs](documentation.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Synopsis](synopsis.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Globals](globals.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[STDIO](stdio.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Timers](timers.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Modules](modules.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[C/C++ Addons](addons.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Process](process.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Utilities](util.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Events](events.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Buffer](buffer.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Stream](stream.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Crypto](crypto.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[TLS/SSL](tls.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[String Decoder](string_decoder.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[File System](fs.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Path](path.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Net](net.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[UDP/Datagram](dgram.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[DNS](dns.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[HTTP](http.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[HTTPS](https.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[URL](url.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Query Strings](querystring.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Readline](readline.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[REPL](repl.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[VM](vm.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Child Processes](child_process.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Assertion Testing](assert.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[TTY](tty.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[ZLIB](zlib.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[OS](os.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Debugger](debugger.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Cluster](cluster.html)" + }, + { + "type": "list_item_end" + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "Appendixes" + }, + { + "type": "list_start", + "ordered": false + }, + { + "type": "list_item_start" + }, + { + "type": "text", + "text": "[Appendix 1: Recommended Third-party Modules](appendix_1.html)" + }, + { + "type": "space" + }, + { + "type": "list_item_end" + }, + { + "type": "list_end" + }, + { + "type": "list_item_end" + }, + { + "type": "list_end" + } + ] +} --- /dev/null +++ b/doc/api/assert.html @@ -0,0 +1,186 @@ + + + + + Assert Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Assert#

+
Stability: 5 - Locked
+

This module is used for writing unit tests for your applications, you can +access it with require('assert'). + +

+

assert.fail(actual, expected, message, operator)#

+

Throws an exception that displays the values for actual and expected separated by the provided operator. + +

+

assert(value, message), assert.ok(value, [message])#

+

Tests if value is a true value, it is equivalent to assert.equal(true, value, message); + +

+

assert.equal(actual, expected, [message])#

+

Tests shallow, coercive equality with the equal comparison operator ( == ). + +

+

assert.notEqual(actual, expected, [message])#

+

Tests shallow, coercive non-equality with the not equal comparison operator ( != ). + +

+

assert.deepEqual(actual, expected, [message])#

+

Tests for deep equality. + +

+

assert.notDeepEqual(actual, expected, [message])#

+

Tests for any deep inequality. + +

+

assert.strictEqual(actual, expected, [message])#

+

Tests strict equality, as determined by the strict equality operator ( === ) + +

+

assert.notStrictEqual(actual, expected, [message])#

+

Tests strict non-equality, as determined by the strict not equal operator ( !== ) + +

+

assert.throws(block, [error], [message])#

+

Expects block to throw an error. error can be constructor, regexp or +validation function. + +

+

Validate instanceof using constructor: + +

+
assert.throws(
+  function() {
+    throw new Error("Wrong value");
+  },
+  Error
+);
+

Validate error message using RegExp: + +

+
assert.throws(
+  function() {
+    throw new Error("Wrong value");
+  },
+  /value/
+);
+

Custom error validation: + +

+
assert.throws(
+  function() {
+    throw new Error("Wrong value");
+  },
+  function(err) {
+    if ( (err instanceof Error) && /value/.test(err) ) {
+      return true;
+    }
+  },
+  "unexpected error"
+);
+

assert.doesNotThrow(block, [error], [message])#

+

Expects block not to throw an error, see assert.throws for details. + +

+

assert.ifError(value)#

+

Tests if value is not a false value, throws if it is a true value. Useful when +testing the first argument, error in callbacks. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/cluster.html @@ -0,0 +1,192 @@ + + + + + Cluster Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Cluster#

+
Stability: 1 Experimental - Drastic changes in future versions
+

A single instance of Node runs in a single thread. To take advantage of +multi-core systems the user will sometimes want to launch a cluster of Node +processes to handle the load. + +

+

The cluster module allows you to easily create a network of processes that +all share server ports. + +

+
var cluster = require('cluster');
+var http = require('http');
+var numCPUs = require('os').cpus().length;
+
+if (cluster.isMaster) {
+  // Fork workers.
+  for (var i = 0; i < numCPUs; i++) {
+    cluster.fork();
+  }
+
+  cluster.on('death', function(worker) {
+    console.log('worker ' + worker.pid + ' died');
+  });
+} else {
+  // Worker processes have a http server.
+  http.Server(function(req, res) {
+    res.writeHead(200);
+    res.end("hello world\n");
+  }).listen(8000);
+}
+

Running node will now share port 8000 between the workers: + +

+
% node server.js
+Worker 2438 online
+Worker 2437 online
+

The difference between cluster.fork() and child_process.fork() is simply +that cluster allows TCP servers to be shared between workers. cluster.fork +is implemented on top of child_process.fork. The message passing API that +is available with child_process.fork is available with cluster as well. +As an example, here is a cluster which keeps count of the number of requests +in the master process via message passing: + +

+
var cluster = require('cluster');
+var http = require('http');
+var numReqs = 0;
+
+if (cluster.isMaster) {
+  // Fork workers.
+  for (var i = 0; i < 2; i++) {
+    var worker = cluster.fork();
+
+    worker.on('message', function(msg) {
+      if (msg.cmd && msg.cmd == 'notifyRequest') {
+        numReqs++;
+      }
+    });
+  }
+
+  setInterval(function() {
+    console.log("numReqs =", numReqs);
+  }, 1000);
+} else {
+  // Worker processes have a http server.
+  http.Server(function(req, res) {
+    res.writeHead(200);
+    res.end("hello world\n");
+    // Send message to master process
+    process.send({ cmd: 'notifyRequest' });
+  }).listen(8000);
+}
+

cluster.fork()#

+

Spawn a new worker process. This can only be called from the master process. + +

+

cluster.isMaster#

+

cluster.isWorker#

+

Boolean flags to determine if the current process is a master or a worker +process in a cluster. A process isMaster if process.env.NODE_WORKER_ID +is undefined. + +

+

Event: 'death'#

+

When any of the workers die the cluster module will emit the 'death' event. +This can be used to restart the worker by calling fork() again. + +

+
cluster.on('death', function(worker) {
+  console.log('worker ' + worker.pid + ' died. restart...');
+  cluster.fork();
+});
+

Different techniques can be used to restart the worker depending on the +application. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/all.json @@ -0,0 +1,9953 @@ +{ + "source": "doc/api/all.markdown", + "miscs": [ + { + "textRaw": "About this Documentation", + "name": "About this Documentation", + "type": "misc", + "desc": "

The goal of this documentation is to comprehensively explain the Node.js\nAPI, both from a reference as well as a conceptual point of view. Each\nsection describes a built-in module or high-level concept.\n\n

\n

Where appropriate, property types, method arguments, and the arguments\nprovided to event handlers are detailed in a list underneath the topic\nheading.\n\n

\n

Every .html document has a corresponding .json document presenting\nthe same information in a structured manner. This feature is\nexperimental, and added for the benefit of IDEs and other utilities that\nwish to do programmatic things with the documentation.\n\n

\n

Every .html and .json file is generated based on the corresponding\n.markdown file in the doc/api/ folder in node's source tree. The\ndocumentation is generated using the tools/doc/generate.js program.\nThe HTML template is located at doc/template.html.\n\n

\n", + "miscs": [ + { + "textRaw": "Stability Index", + "name": "Stability Index", + "type": "misc", + "desc": "

Throughout the documentation, you will see indications of a section's\nstability. The Node.js API is still somewhat changing, and as it\nmatures, certain parts are more reliable than others. Some are so\nproven, and so relied upon, that they are unlikely to ever change at\nall. Others are brand new and experimental, or known to be hazardous\nand in the process of being redesigned.\n\n

\n

The notices look like this:\n\n

\n
Stability: 1 Experimental
\n

The stability indices are as follows:\n\n

\n
    \n
  • 0 - Deprecated This feature is known to be problematic, and changes are\nplanned. Do not rely on it. Use of the feature may cause warnings. Backwards\ncompatibility should not be expected.
    • \n
\n
    \n
  • 1 - Experimental This feature was introduced recently, and may change\nor be removed in future versions. Please try it out and provide feedback.\nIf it addresses a use-case that is important to you, tell the node core team.
    • \n
\n
    \n
  • 2 - Unstable The API is in the process of settling, but has not yet had\nsufficient real-world testing to be considered stable. Backwards-compatibility\nwill be maintained if reasonable.
    • \n
\n
    \n
  • 3 - Stable The API has proven satisfactory, but cleanup in the underlying\ncode may cause minor changes. Backwards-compatibility is guaranteed.
    • \n
\n
    \n
  • 4 - API Frozen This API has been tested extensively in production and is\nunlikely to ever have to change.
    • \n
\n
    \n
  • 5 - Locked Unless serious bugs are found, this code will not ever\nchange. Please do not suggest changes in this area; they will be refused.
    • \n
\n" + }, + { + "textRaw": "JSON Output", + "name": "json_output", + "stability": 1, + "stabilityText": "Experimental", + "desc": "

Every HTML file in the markdown has a corresponding JSON file with the\nsame data.\n\n

\n

This feature is new as of node v0.6.12. It is experimental.\n\n

\n", + "type": "misc", + "displayName": "JSON Output" + } + ] + }, + { + "textRaw": "Synopsis", + "name": "Synopsis", + "type": "misc", + "desc": "

An example of a web server written with Node which responds with 'Hello\nWorld':\n\n

\n
var http = require('http');\n\nhttp.createServer(function (request, response) {\n  response.writeHead(200, {'Content-Type': 'text/plain'});\n  response.end('Hello World\\n');\n}).listen(8124);\n\nconsole.log('Server running at http://127.0.0.1:8124/');
\n

To run the server, put the code into a file called example.js and execute\nit with the node program\n\n

\n
> node example.js\nServer running at http://127.0.0.1:8124/
\n

All of the examples in the documentation can be run similarly.\n\n

\n" + }, + { + "textRaw": "Global Objects", + "name": "Global Objects", + "type": "misc", + "desc": "

These objects are available in all modules. Some of these objects aren't\nactually in the global scope but in the module scope - this will be noted.\n\n

\n", + "globals": [ + { + "textRaw": "global", + "name": "global", + "type": "global", + "desc": "

In browsers, the top-level scope is the global scope. That means that in\nbrowsers if you're in the global scope var something will define a global\nvariable. In Node this is different. The top-level scope is not the global\nscope; var something inside a Node module will be local to that module.\n\n

\n" + }, + { + "textRaw": "process", + "name": "process", + "type": "global", + "desc": "

The process object. See the process object section.\n\n

\n" + }, + { + "textRaw": "console", + "name": "console", + "type": "global", + "desc": "

Used to print to stdout and stderr. See the stdio section.\n\n

\n" + }, + { + "textRaw": "Buffer", + "name": "Buffer", + "type": "global", + "desc": "

Used to handle binary data. See the buffer section.\n\n

\n" + }, + { + "textRaw": "clearInterval(t)", + "type": "global", + "name": "clearInterval", + "desc": "

The timer functions are global variables. See the timers section.\n\n

\n" + }, + { + "textRaw": "console", + "name": "console", + "stability": 4, + "stabilityText": "API Frozen", + "type": "global", + "desc": "

For printing to stdout and stderr. Similar to the console object functions\nprovided by most web browsers, here the output is sent to stdout or stderr.\n\n\n

\n", + "methods": [ + { + "textRaw": "console.log()", + "type": "method", + "name": "log", + "desc": "

Prints to stdout with newline. This function can take multiple arguments in a\nprintf()-like way. Example:\n\n

\n
console.log('count: %d', count);
\n

If formatting elements are not found in the first string then util.inspect\nis used on each argument.\nSee util.format() for more information.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.info()", + "type": "method", + "name": "info", + "desc": "

Same as console.log.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.warn()", + "type": "method", + "name": "warn", + "desc": "

Same as console.log but prints to stderr.\n\n

\n", + "signatures": [ + { + "params": [] + }, + { + "params": [] + } + ] + }, + { + "textRaw": "console.error()", + "type": "method", + "name": "error", + "desc": "

Same as console.log but prints to stderr.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.dir(obj)", + "type": "method", + "name": "dir", + "desc": "

Uses util.inspect on obj and prints resulting string to stderr.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "obj" + } + ] + } + ] + }, + { + "textRaw": "console.time(label)", + "type": "method", + "name": "time", + "desc": "

Mark a time.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "label" + } + ] + } + ] + }, + { + "textRaw": "console.timeEnd(label)", + "type": "method", + "name": "timeEnd", + "desc": "

Finish timer, record output. Example\n\n

\n
console.time('100-elements');\nfor (var i = 0; i < 100; i++) {\n  ;\n}\nconsole.timeEnd('100-elements');
\n", + "signatures": [ + { + "params": [ + { + "name": "label" + } + ] + } + ] + }, + { + "textRaw": "console.trace()", + "type": "method", + "name": "trace", + "desc": "

Print a stack trace to stderr of the current position.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.assert()", + "type": "method", + "name": "assert", + "desc": "

Same as assert.ok().\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + }, + { + "textRaw": "process", + "name": "process", + "type": "global", + "desc": "

The process object is a global object and can be accessed from anywhere.\nIt is an instance of EventEmitter.\n\n\n

\n", + "events": [ + { + "textRaw": "Event: 'exit'", + "type": "event", + "name": "exit", + "desc": "

Emitted when the process is about to exit. This is a good hook to perform\nconstant time checks of the module's state (like for unit tests). The main\nevent loop will no longer be run after the 'exit' callback finishes, so\ntimers may not be scheduled.\n\n

\n

Example of listening for exit:\n\n

\n
process.on('exit', function () {\n  process.nextTick(function () {\n   console.log('This will not run');\n  });\n  console.log('About to exit.');\n});
\n", + "params": [] + }, + { + "textRaw": "Event: 'uncaughtException'", + "type": "event", + "name": "uncaughtException", + "desc": "

Emitted when an exception bubbles all the way back to the event loop. If a\nlistener is added for this exception, the default action (which is to print\na stack trace and exit) will not occur.\n\n

\n

Example of listening for uncaughtException:\n\n

\n
process.on('uncaughtException', function (err) {\n  console.log('Caught exception: ' + err);\n});\n\nsetTimeout(function () {\n  console.log('This will still run.');\n}, 500);\n\n// Intentionally cause an exception, but don't catch it.\nnonexistentFunc();\nconsole.log('This will not run.');
\n

Note that uncaughtException is a very crude mechanism for exception\nhandling. Using try / catch in your program will give you more control over\nyour program's flow. Especially for server programs that are designed to\nstay running forever, uncaughtException can be a useful safety mechanism.\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Signal Events", + "name": "SIGINT, SIGUSR1, etc.", + "type": "event", + "desc": "

Emitted when the processes receives a signal. See sigaction(2) for a list of\nstandard POSIX signal names such as SIGINT, SIGUSR1, etc.\n\n

\n

Example of listening for SIGINT:\n\n

\n
// Start reading from stdin so we don't exit.\nprocess.stdin.resume();\n\nprocess.on('SIGINT', function () {\n  console.log('Got SIGINT.  Press Control-D to exit.');\n});
\n

An easy way to send the SIGINT signal is with Control-C in most terminal\nprograms.\n\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "process.stdout", + "name": "stdout", + "desc": "

A Writable Stream to stdout.\n\n

\n

Example: the definition of console.log\n\n

\n
console.log = function (d) {\n  process.stdout.write(d + '\\n');\n};
\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" + }, + { + "textRaw": "process.stderr", + "name": "stderr", + "desc": "

A writable stream to stderr.\n\n

\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" + }, + { + "textRaw": "process.stdin", + "name": "stdin", + "desc": "

A Readable Stream for stdin. The stdin stream is paused by default, so one\nmust call process.stdin.resume() to read from it.\n\n

\n

Example of opening standard input and listening for both events:\n\n

\n
process.stdin.resume();\nprocess.stdin.setEncoding('utf8');\n\nprocess.stdin.on('data', function (chunk) {\n  process.stdout.write('data: ' + chunk);\n});\n\nprocess.stdin.on('end', function () {\n  process.stdout.write('end');\n});
\n" + }, + { + "textRaw": "process.argv", + "name": "argv", + "desc": "

An array containing the command line arguments. The first element will be\n'node', the second element will be the name of the JavaScript file. The\nnext elements will be any additional command line arguments.\n\n

\n
// print process.argv\nprocess.argv.forEach(function (val, index, array) {\n  console.log(index + ': ' + val);\n});
\n

This will generate:\n\n

\n
$ node process-2.js one two=three four\n0: node\n1: /Users/mjr/work/node/process-2.js\n2: one\n3: two=three\n4: four
\n" + }, + { + "textRaw": "process.execPath", + "name": "execPath", + "desc": "

This is the absolute pathname of the executable that started the process.\n\n

\n

Example:\n\n

\n
/usr/local/bin/node
\n" + }, + { + "textRaw": "process.env", + "name": "env", + "desc": "

An object containing the user environment. See environ(7).\n\n\n

\n" + }, + { + "textRaw": "process.version", + "name": "version", + "desc": "

A compiled-in property that exposes NODE_VERSION.\n\n

\n
console.log('Version: ' + process.version);
\n" + }, + { + "textRaw": "process.versions", + "name": "versions", + "desc": "

A property exposing version strings of node and its dependencies.\n\n

\n
console.log(process.versions);
\n

Will output:\n\n

\n
{ node: '0.4.12',\n  v8: '3.1.8.26',\n  ares: '1.7.4',\n  ev: '4.4',\n  openssl: '1.0.0e-fips' }
\n" + }, + { + "textRaw": "process.installPrefix", + "name": "installPrefix", + "desc": "

A compiled-in property that exposes NODE_PREFIX.\n\n

\n
console.log('Prefix: ' + process.installPrefix);
\n" + }, + { + "textRaw": "process.pid", + "name": "pid", + "desc": "

The PID of the process.\n\n

\n
console.log('This process is pid ' + process.pid);
\n" + }, + { + "textRaw": "process.title", + "name": "title", + "desc": "

Getter/setter to set what is displayed in 'ps'.\n\n\n

\n" + }, + { + "textRaw": "process.arch", + "name": "arch", + "desc": "

What processor architecture you're running on: 'arm', 'ia32', or 'x64'.\n\n

\n
console.log('This processor architecture is ' + process.arch);
\n" + }, + { + "textRaw": "process.platform", + "name": "platform", + "desc": "

What platform you're running on. 'linux2', 'darwin', etc.\n\n

\n
console.log('This platform is ' + process.platform);
\n" + } + ], + "methods": [ + { + "textRaw": "process.chdir(directory)", + "type": "method", + "name": "chdir", + "desc": "

Changes the current working directory of the process or throws an exception if that fails.\n\n

\n
console.log('Starting directory: ' + process.cwd());\ntry {\n  process.chdir('/tmp');\n  console.log('New directory: ' + process.cwd());\n}\ncatch (err) {\n  console.log('chdir: ' + err);\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "directory" + } + ] + } + ] + }, + { + "textRaw": "process.cwd()", + "type": "method", + "name": "cwd", + "desc": "

Returns the current working directory of the process.\n\n

\n
console.log('Current directory: ' + process.cwd());
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.exit([code])", + "type": "method", + "name": "exit", + "desc": "

Ends the process with the specified code. If omitted, exit uses the\n'success' code 0.\n\n

\n

To exit with a 'failure' code:\n\n

\n
process.exit(1);
\n

The shell that executed node should see the exit code as 1.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "process.getgid()", + "type": "method", + "name": "getgid", + "desc": "

Gets the group identity of the process. (See getgid(2).)\nThis is the numerical group id, not the group name.\n\n

\n
console.log('Current gid: ' + process.getgid());
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.setgid(id)", + "type": "method", + "name": "setgid", + "desc": "

Sets the group identity of the process. (See setgid(2).) This accepts either\na numerical ID or a groupname string. If a groupname is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current gid: ' + process.getgid());\ntry {\n  process.setgid(501);\n  console.log('New gid: ' + process.getgid());\n}\ncatch (err) {\n  console.log('Failed to set gid: ' + err);\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "id" + } + ] + } + ] + }, + { + "textRaw": "process.getuid()", + "type": "method", + "name": "getuid", + "desc": "

Gets the user identity of the process. (See getuid(2).)\nThis is the numerical userid, not the username.\n\n

\n
console.log('Current uid: ' + process.getuid());
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.setuid(id)", + "type": "method", + "name": "setuid", + "desc": "

Sets the user identity of the process. (See setuid(2).) This accepts either\na numerical ID or a username string. If a username is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current uid: ' + process.getuid());\ntry {\n  process.setuid(501);\n  console.log('New uid: ' + process.getuid());\n}\ncatch (err) {\n  console.log('Failed to set uid: ' + err);\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "id" + } + ] + } + ] + }, + { + "textRaw": "process.kill(pid, [signal])", + "type": "method", + "name": "kill", + "desc": "

Send a signal to a process. pid is the process id and signal is the\nstring describing the signal to send. Signal names are strings like\n'SIGINT' or 'SIGUSR1'. If omitted, the signal will be 'SIGTERM'.\nSee kill(2) for more information.\n\n

\n

Note that just because the name of this function is process.kill, it is\nreally just a signal sender, like the kill system call. The signal sent\nmay do something other than kill the target process.\n\n

\n

Example of sending a signal to yourself:\n\n

\n
process.on('SIGHUP', function () {\n  console.log('Got SIGHUP signal.');\n});\n\nsetTimeout(function () {\n  console.log('Exiting.');\n  process.exit(0);\n}, 100);\n\nprocess.kill(process.pid, 'SIGHUP');
\n", + "signatures": [ + { + "params": [ + { + "name": "pid" + }, + { + "name": "signal", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "process.memoryUsage()", + "type": "method", + "name": "memoryUsage", + "desc": "

Returns an object describing the memory usage of the Node process\nmeasured in bytes.\n\n

\n
var util = require('util');\n\nconsole.log(util.inspect(process.memoryUsage()));
\n

This will generate:\n\n

\n
{ rss: 4935680,\n  heapTotal: 1826816,\n  heapUsed: 650472 }
\n

heapTotal and heapUsed refer to V8's memory usage.\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.nextTick(callback)", + "type": "method", + "name": "nextTick", + "desc": "

On the next loop around the event loop call this callback.\nThis is not a simple alias to setTimeout(fn, 0), it's much more\nefficient.\n\n

\n
process.nextTick(function () {\n  console.log('nextTick callback');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "process.umask([mask])", + "type": "method", + "name": "umask", + "desc": "

Sets or reads the process's file mode creation mask. Child processes inherit\nthe mask from the parent process. Returns the old mask if mask argument is\ngiven, otherwise returns the current mask.\n\n

\n
var oldmask, newmask = 0644;\n\noldmask = process.umask(newmask);\nconsole.log('Changed umask from: ' + oldmask.toString(8) +\n            ' to ' + newmask.toString(8));
\n", + "signatures": [ + { + "params": [ + { + "name": "mask", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "process.uptime()", + "type": "method", + "name": "uptime", + "desc": "

Number of seconds Node has been running.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + } + ], + "vars": [ + { + "textRaw": "require()", + "type": "var", + "name": "require", + "desc": "

To require modules. See the Modules section.\nrequire isn't actually a global but rather local to each module.\n\n\n

\n", + "methods": [ + { + "textRaw": "require.resolve()", + "type": "method", + "name": "resolve", + "desc": "

Use the internal require() machinery to look up the location of a module,\nbut rather than loading the module, just return the resolved filename.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "properties": [ + { + "textRaw": "`cache` {Object} ", + "name": "cache", + "desc": "

Modules are cached in this object when they are required. By deleting a key\nvalue from this object, the next require will reload the module.\n\n

\n" + } + ] + }, + { + "textRaw": "__filename", + "name": "__filename", + "type": "var", + "desc": "

The filename of the code being executed. This is the resolved absolute path\nof this code file. For a main program this is not necessarily the same\nfilename used in the command line. The value inside a module is the path\nto that module file.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__filename);\n// /Users/mjr/example.js
\n

__filename isn't actually a global but rather local to each module.\n\n

\n" + }, + { + "textRaw": "__dirname", + "name": "__dirname", + "type": "var", + "desc": "

The name of the directory that the currently executing script resides in.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__dirname);\n// /Users/mjr
\n

__dirname isn't actually a global but rather local to each module.\n\n\n

\n" + }, + { + "textRaw": "module", + "name": "module", + "type": "var", + "desc": "

A reference to the current module. In particular\nmodule.exports is the same as the exports object. See src/node.js\nfor more information.\nmodule isn't actually a global but rather local to each module.\n\n\n

\n" + }, + { + "textRaw": "exports", + "name": "exports", + "type": "var", + "desc": "

An object which is shared between all instances of the current module and\nmade accessible through require().\nexports is the same as the module.exports object. See src/node.js\nfor more information.\nexports isn't actually a global but rather local to each module.\n\n

\n

See the module system documentation for more\ninformation.\n\n

\n

See the module section for more information.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "setInterval(cb, ms)", + "type": "method", + "name": "setInterval", + "desc": "

The timer functions are global variables. See the timers section.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "cb" + }, + { + "name": "ms" + } + ] + } + ] + } + ] + }, + { + "textRaw": "Debugger", + "name": "Debugger", + "stability": 3, + "stabilityText": "Stable", + "type": "misc", + "desc": "

V8 comes with an extensive debugger which is accessible out-of-process via a\nsimple TCP protocol.\nNode has a built-in client for this debugger. To use this, start Node with the\ndebug argument; a prompt will appear:\n\n

\n
% node debug myscript.js\n< debugger listening on port 5858\nconnecting... ok\nbreak in /home/indutny/Code/git/indutny/myscript.js:1\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\ndebug>
\n

Node's debugger client doesn't support the full range of commands, but\nsimple step and inspection is possible. By putting the statement debugger;\ninto the source code of your script, you will enable a breakpoint.\n\n

\n

For example, suppose myscript.js looked like this:\n\n

\n
// myscript.js\nx = 5;\nsetTimeout(function () {\n  debugger;\n  console.log("world");\n}, 1000);\nconsole.log("hello");
\n

Then once the debugger is run, it will break on line 4.\n\n

\n
% node debug myscript.js\n< debugger listening on port 5858\nconnecting... ok\nbreak in /home/indutny/Code/git/indutny/myscript.js:1\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\ndebug> cont\n< hello\nbreak in /home/indutny/Code/git/indutny/myscript.js:3\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\ndebug> next\nbreak in /home/indutny/Code/git/indutny/myscript.js:4\n  2 setTimeout(function () {\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\n  6 console.log("hello");\ndebug> repl\nPress Ctrl + C to leave debug repl\n> x\n5\n> 2+2\n4\ndebug> next\n< world\nbreak in /home/indutny/Code/git/indutny/myscript.js:5\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\n  6 console.log("hello");\n  7\ndebug> quit\n%
\n

The repl command allows you to evaluate code remotely. The next command\nsteps over to the next line. There are a few other commands available and more\nto come. Type help to see others.\n\n

\n", + "miscs": [ + { + "textRaw": "Watchers", + "name": "watchers", + "desc": "

You can watch expression and variable values while debugging your code.\nOn every breakpoint each expression from the watchers list will be evaluated\nin the current context and displayed just before the breakpoint's source code\nlisting.\n\n

\n

To start watching an expression, type watch("my_expression"). watchers\nprints the active watchers. To remove a watcher, type\nunwatch("my_expression").\n\n

\n", + "type": "misc", + "displayName": "Watchers" + }, + { + "textRaw": "Commands reference", + "name": "commands_reference", + "modules": [ + { + "textRaw": "Execution control", + "name": "Execution control", + "type": "module", + "displayName": "Various" + }, + { + "textRaw": "Various", + "name": "various", + "type": "module", + "displayName": "Various" + } + ], + "type": "misc", + "displayName": "Commands reference" + }, + { + "textRaw": "Advanced Usage", + "name": "advanced_usage", + "desc": "

The V8 debugger can be enabled and accessed either by starting Node with\nthe --debug command-line flag or by signaling an existing Node process\nwith SIGUSR1.\n\n

\n", + "type": "misc", + "displayName": "Advanced Usage" + } + ] + } + ], + "globals": [ + { + "textRaw": "global", + "name": "global", + "type": "global", + "desc": "

In browsers, the top-level scope is the global scope. That means that in\nbrowsers if you're in the global scope var something will define a global\nvariable. In Node this is different. The top-level scope is not the global\nscope; var something inside a Node module will be local to that module.\n\n

\n" + }, + { + "textRaw": "process", + "name": "process", + "type": "global", + "desc": "

The process object. See the process object section.\n\n

\n" + }, + { + "textRaw": "console", + "name": "console", + "type": "global", + "desc": "

Used to print to stdout and stderr. See the stdio section.\n\n

\n" + }, + { + "textRaw": "Buffer", + "name": "Buffer", + "type": "global", + "desc": "

Used to handle binary data. See the buffer section.\n\n

\n" + }, + { + "textRaw": "clearInterval(t)", + "type": "global", + "name": "clearInterval", + "desc": "

The timer functions are global variables. See the timers section.\n\n

\n" + }, + { + "textRaw": "console", + "name": "console", + "stability": 4, + "stabilityText": "API Frozen", + "type": "global", + "desc": "

For printing to stdout and stderr. Similar to the console object functions\nprovided by most web browsers, here the output is sent to stdout or stderr.\n\n\n

\n", + "methods": [ + { + "textRaw": "console.log()", + "type": "method", + "name": "log", + "desc": "

Prints to stdout with newline. This function can take multiple arguments in a\nprintf()-like way. Example:\n\n

\n
console.log('count: %d', count);
\n

If formatting elements are not found in the first string then util.inspect\nis used on each argument.\nSee util.format() for more information.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.info()", + "type": "method", + "name": "info", + "desc": "

Same as console.log.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.warn()", + "type": "method", + "name": "warn", + "desc": "

Same as console.log but prints to stderr.\n\n

\n", + "signatures": [ + { + "params": [] + }, + { + "params": [] + } + ] + }, + { + "textRaw": "console.error()", + "type": "method", + "name": "error", + "desc": "

Same as console.log but prints to stderr.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.dir(obj)", + "type": "method", + "name": "dir", + "desc": "

Uses util.inspect on obj and prints resulting string to stderr.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "obj" + } + ] + } + ] + }, + { + "textRaw": "console.time(label)", + "type": "method", + "name": "time", + "desc": "

Mark a time.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "label" + } + ] + } + ] + }, + { + "textRaw": "console.timeEnd(label)", + "type": "method", + "name": "timeEnd", + "desc": "

Finish timer, record output. Example\n\n

\n
console.time('100-elements');\nfor (var i = 0; i < 100; i++) {\n  ;\n}\nconsole.timeEnd('100-elements');
\n", + "signatures": [ + { + "params": [ + { + "name": "label" + } + ] + } + ] + }, + { + "textRaw": "console.trace()", + "type": "method", + "name": "trace", + "desc": "

Print a stack trace to stderr of the current position.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.assert()", + "type": "method", + "name": "assert", + "desc": "

Same as assert.ok().\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + }, + { + "textRaw": "process", + "name": "process", + "type": "global", + "desc": "

The process object is a global object and can be accessed from anywhere.\nIt is an instance of EventEmitter.\n\n\n

\n", + "events": [ + { + "textRaw": "Event: 'exit'", + "type": "event", + "name": "exit", + "desc": "

Emitted when the process is about to exit. This is a good hook to perform\nconstant time checks of the module's state (like for unit tests). The main\nevent loop will no longer be run after the 'exit' callback finishes, so\ntimers may not be scheduled.\n\n

\n

Example of listening for exit:\n\n

\n
process.on('exit', function () {\n  process.nextTick(function () {\n   console.log('This will not run');\n  });\n  console.log('About to exit.');\n});
\n", + "params": [] + }, + { + "textRaw": "Event: 'uncaughtException'", + "type": "event", + "name": "uncaughtException", + "desc": "

Emitted when an exception bubbles all the way back to the event loop. If a\nlistener is added for this exception, the default action (which is to print\na stack trace and exit) will not occur.\n\n

\n

Example of listening for uncaughtException:\n\n

\n
process.on('uncaughtException', function (err) {\n  console.log('Caught exception: ' + err);\n});\n\nsetTimeout(function () {\n  console.log('This will still run.');\n}, 500);\n\n// Intentionally cause an exception, but don't catch it.\nnonexistentFunc();\nconsole.log('This will not run.');
\n

Note that uncaughtException is a very crude mechanism for exception\nhandling. Using try / catch in your program will give you more control over\nyour program's flow. Especially for server programs that are designed to\nstay running forever, uncaughtException can be a useful safety mechanism.\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Signal Events", + "name": "SIGINT, SIGUSR1, etc.", + "type": "event", + "desc": "

Emitted when the processes receives a signal. See sigaction(2) for a list of\nstandard POSIX signal names such as SIGINT, SIGUSR1, etc.\n\n

\n

Example of listening for SIGINT:\n\n

\n
// Start reading from stdin so we don't exit.\nprocess.stdin.resume();\n\nprocess.on('SIGINT', function () {\n  console.log('Got SIGINT.  Press Control-D to exit.');\n});
\n

An easy way to send the SIGINT signal is with Control-C in most terminal\nprograms.\n\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "process.stdout", + "name": "stdout", + "desc": "

A Writable Stream to stdout.\n\n

\n

Example: the definition of console.log\n\n

\n
console.log = function (d) {\n  process.stdout.write(d + '\\n');\n};
\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" + }, + { + "textRaw": "process.stderr", + "name": "stderr", + "desc": "

A writable stream to stderr.\n\n

\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" + }, + { + "textRaw": "process.stdin", + "name": "stdin", + "desc": "

A Readable Stream for stdin. The stdin stream is paused by default, so one\nmust call process.stdin.resume() to read from it.\n\n

\n

Example of opening standard input and listening for both events:\n\n

\n
process.stdin.resume();\nprocess.stdin.setEncoding('utf8');\n\nprocess.stdin.on('data', function (chunk) {\n  process.stdout.write('data: ' + chunk);\n});\n\nprocess.stdin.on('end', function () {\n  process.stdout.write('end');\n});
\n" + }, + { + "textRaw": "process.argv", + "name": "argv", + "desc": "

An array containing the command line arguments. The first element will be\n'node', the second element will be the name of the JavaScript file. The\nnext elements will be any additional command line arguments.\n\n

\n
// print process.argv\nprocess.argv.forEach(function (val, index, array) {\n  console.log(index + ': ' + val);\n});
\n

This will generate:\n\n

\n
$ node process-2.js one two=three four\n0: node\n1: /Users/mjr/work/node/process-2.js\n2: one\n3: two=three\n4: four
\n" + }, + { + "textRaw": "process.execPath", + "name": "execPath", + "desc": "

This is the absolute pathname of the executable that started the process.\n\n

\n

Example:\n\n

\n
/usr/local/bin/node
\n" + }, + { + "textRaw": "process.env", + "name": "env", + "desc": "

An object containing the user environment. See environ(7).\n\n\n

\n" + }, + { + "textRaw": "process.version", + "name": "version", + "desc": "

A compiled-in property that exposes NODE_VERSION.\n\n

\n
console.log('Version: ' + process.version);
\n" + }, + { + "textRaw": "process.versions", + "name": "versions", + "desc": "

A property exposing version strings of node and its dependencies.\n\n

\n
console.log(process.versions);
\n

Will output:\n\n

\n
{ node: '0.4.12',\n  v8: '3.1.8.26',\n  ares: '1.7.4',\n  ev: '4.4',\n  openssl: '1.0.0e-fips' }
\n" + }, + { + "textRaw": "process.installPrefix", + "name": "installPrefix", + "desc": "

A compiled-in property that exposes NODE_PREFIX.\n\n

\n
console.log('Prefix: ' + process.installPrefix);
\n" + }, + { + "textRaw": "process.pid", + "name": "pid", + "desc": "

The PID of the process.\n\n

\n
console.log('This process is pid ' + process.pid);
\n" + }, + { + "textRaw": "process.title", + "name": "title", + "desc": "

Getter/setter to set what is displayed in 'ps'.\n\n\n

\n" + }, + { + "textRaw": "process.arch", + "name": "arch", + "desc": "

What processor architecture you're running on: 'arm', 'ia32', or 'x64'.\n\n

\n
console.log('This processor architecture is ' + process.arch);
\n" + }, + { + "textRaw": "process.platform", + "name": "platform", + "desc": "

What platform you're running on. 'linux2', 'darwin', etc.\n\n

\n
console.log('This platform is ' + process.platform);
\n" + } + ], + "methods": [ + { + "textRaw": "process.chdir(directory)", + "type": "method", + "name": "chdir", + "desc": "

Changes the current working directory of the process or throws an exception if that fails.\n\n

\n
console.log('Starting directory: ' + process.cwd());\ntry {\n  process.chdir('/tmp');\n  console.log('New directory: ' + process.cwd());\n}\ncatch (err) {\n  console.log('chdir: ' + err);\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "directory" + } + ] + } + ] + }, + { + "textRaw": "process.cwd()", + "type": "method", + "name": "cwd", + "desc": "

Returns the current working directory of the process.\n\n

\n
console.log('Current directory: ' + process.cwd());
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.exit([code])", + "type": "method", + "name": "exit", + "desc": "

Ends the process with the specified code. If omitted, exit uses the\n'success' code 0.\n\n

\n

To exit with a 'failure' code:\n\n

\n
process.exit(1);
\n

The shell that executed node should see the exit code as 1.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "process.getgid()", + "type": "method", + "name": "getgid", + "desc": "

Gets the group identity of the process. (See getgid(2).)\nThis is the numerical group id, not the group name.\n\n

\n
console.log('Current gid: ' + process.getgid());
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.setgid(id)", + "type": "method", + "name": "setgid", + "desc": "

Sets the group identity of the process. (See setgid(2).) This accepts either\na numerical ID or a groupname string. If a groupname is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current gid: ' + process.getgid());\ntry {\n  process.setgid(501);\n  console.log('New gid: ' + process.getgid());\n}\ncatch (err) {\n  console.log('Failed to set gid: ' + err);\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "id" + } + ] + } + ] + }, + { + "textRaw": "process.getuid()", + "type": "method", + "name": "getuid", + "desc": "

Gets the user identity of the process. (See getuid(2).)\nThis is the numerical userid, not the username.\n\n

\n
console.log('Current uid: ' + process.getuid());
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.setuid(id)", + "type": "method", + "name": "setuid", + "desc": "

Sets the user identity of the process. (See setuid(2).) This accepts either\na numerical ID or a username string. If a username is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current uid: ' + process.getuid());\ntry {\n  process.setuid(501);\n  console.log('New uid: ' + process.getuid());\n}\ncatch (err) {\n  console.log('Failed to set uid: ' + err);\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "id" + } + ] + } + ] + }, + { + "textRaw": "process.kill(pid, [signal])", + "type": "method", + "name": "kill", + "desc": "

Send a signal to a process. pid is the process id and signal is the\nstring describing the signal to send. Signal names are strings like\n'SIGINT' or 'SIGUSR1'. If omitted, the signal will be 'SIGTERM'.\nSee kill(2) for more information.\n\n

\n

Note that just because the name of this function is process.kill, it is\nreally just a signal sender, like the kill system call. The signal sent\nmay do something other than kill the target process.\n\n

\n

Example of sending a signal to yourself:\n\n

\n
process.on('SIGHUP', function () {\n  console.log('Got SIGHUP signal.');\n});\n\nsetTimeout(function () {\n  console.log('Exiting.');\n  process.exit(0);\n}, 100);\n\nprocess.kill(process.pid, 'SIGHUP');
\n", + "signatures": [ + { + "params": [ + { + "name": "pid" + }, + { + "name": "signal", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "process.memoryUsage()", + "type": "method", + "name": "memoryUsage", + "desc": "

Returns an object describing the memory usage of the Node process\nmeasured in bytes.\n\n

\n
var util = require('util');\n\nconsole.log(util.inspect(process.memoryUsage()));
\n

This will generate:\n\n

\n
{ rss: 4935680,\n  heapTotal: 1826816,\n  heapUsed: 650472 }
\n

heapTotal and heapUsed refer to V8's memory usage.\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "process.nextTick(callback)", + "type": "method", + "name": "nextTick", + "desc": "

On the next loop around the event loop call this callback.\nThis is not a simple alias to setTimeout(fn, 0), it's much more\nefficient.\n\n

\n
process.nextTick(function () {\n  console.log('nextTick callback');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "process.umask([mask])", + "type": "method", + "name": "umask", + "desc": "

Sets or reads the process's file mode creation mask. Child processes inherit\nthe mask from the parent process. Returns the old mask if mask argument is\ngiven, otherwise returns the current mask.\n\n

\n
var oldmask, newmask = 0644;\n\noldmask = process.umask(newmask);\nconsole.log('Changed umask from: ' + oldmask.toString(8) +\n            ' to ' + newmask.toString(8));
\n", + "signatures": [ + { + "params": [ + { + "name": "mask", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "process.uptime()", + "type": "method", + "name": "uptime", + "desc": "

Number of seconds Node has been running.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + } + ], + "vars": [ + { + "textRaw": "require()", + "type": "var", + "name": "require", + "desc": "

To require modules. See the Modules section.\nrequire isn't actually a global but rather local to each module.\n\n\n

\n", + "methods": [ + { + "textRaw": "require.resolve()", + "type": "method", + "name": "resolve", + "desc": "

Use the internal require() machinery to look up the location of a module,\nbut rather than loading the module, just return the resolved filename.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "properties": [ + { + "textRaw": "`cache` {Object} ", + "name": "cache", + "desc": "

Modules are cached in this object when they are required. By deleting a key\nvalue from this object, the next require will reload the module.\n\n

\n" + } + ] + }, + { + "textRaw": "__filename", + "name": "__filename", + "type": "var", + "desc": "

The filename of the code being executed. This is the resolved absolute path\nof this code file. For a main program this is not necessarily the same\nfilename used in the command line. The value inside a module is the path\nto that module file.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__filename);\n// /Users/mjr/example.js
\n

__filename isn't actually a global but rather local to each module.\n\n

\n" + }, + { + "textRaw": "__dirname", + "name": "__dirname", + "type": "var", + "desc": "

The name of the directory that the currently executing script resides in.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__dirname);\n// /Users/mjr
\n

__dirname isn't actually a global but rather local to each module.\n\n\n

\n" + }, + { + "textRaw": "module", + "name": "module", + "type": "var", + "desc": "

A reference to the current module. In particular\nmodule.exports is the same as the exports object. See src/node.js\nfor more information.\nmodule isn't actually a global but rather local to each module.\n\n\n

\n" + }, + { + "textRaw": "exports", + "name": "exports", + "type": "var", + "desc": "

An object which is shared between all instances of the current module and\nmade accessible through require().\nexports is the same as the module.exports object. See src/node.js\nfor more information.\nexports isn't actually a global but rather local to each module.\n\n

\n

See the module system documentation for more\ninformation.\n\n

\n

See the module section for more information.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "setInterval(cb, ms)", + "type": "method", + "name": "setInterval", + "desc": "

The timer functions are global variables. See the timers section.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "cb" + }, + { + "name": "ms" + } + ] + } + ] + } + ], + "modules": [ + { + "textRaw": "Timers", + "name": "timers", + "stability": 5, + "stabilityText": "Locked", + "desc": "

All of the timer functions are globals. You do not need to require()\nthis module in order to use them.\n\n

\n", + "methods": [ + { + "textRaw": "setTimeout(callback, delay, [arg], [...])", + "type": "method", + "name": "setTimeout", + "desc": "

To schedule execution of a one-time callback after delay milliseconds. Returns a\ntimeoutId for possible use with clearTimeout(). Optionally you can\nalso pass arguments to the callback.\n\n

\n

It is important to note that your callback will probably not be called in exactly\ndelay milliseconds - Node.js makes no guarantees about the exact timing of when\nthe callback will fire, nor of the ordering things will fire in. The callback will\nbe called as close as possible to the time specified.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "callback" + }, + { + "name": "delay" + }, + { + "name": "arg", + "optional": true + }, + { + "name": "...", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "clearTimeout(timeoutId)", + "type": "method", + "name": "clearTimeout", + "desc": "

Prevents a timeout from triggering.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "timeoutId" + } + ] + } + ] + }, + { + "textRaw": "setInterval(callback, delay, [arg], [...])", + "type": "method", + "name": "setInterval", + "desc": "

To schedule the repeated execution of callback every delay milliseconds.\nReturns a intervalId for possible use with clearInterval(). Optionally\nyou can also pass arguments to the callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "callback" + }, + { + "name": "delay" + }, + { + "name": "arg", + "optional": true + }, + { + "name": "...", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "clearInterval(intervalId)", + "type": "method", + "name": "clearInterval", + "desc": "

Stops a interval from triggering.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "intervalId" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "Timers" + }, + { + "textRaw": "Modules", + "name": "module", + "stability": 5, + "stabilityText": "Locked", + "desc": "

Node has a simple module loading system. In Node, files and modules are in\none-to-one correspondence. As an example, foo.js loads the module\ncircle.js in the same directory.\n\n

\n

The contents of foo.js:\n\n

\n
var circle = require('./circle.js');\nconsole.log( 'The area of a circle of radius 4 is '\n           + circle.area(4));
\n

The contents of circle.js:\n\n

\n
var PI = Math.PI;\n\nexports.area = function (r) {\n  return PI * r * r;\n};\n\nexports.circumference = function (r) {\n  return 2 * PI * r;\n};
\n

The module circle.js has exported the functions area() and\ncircumference(). To export an object, add to the special exports\nobject.\n\n

\n

Variables\nlocal to the module will be private. In this example the variable PI is\nprivate to circle.js.\n\n

\n

The module system is implemented in the require("module") module.\n\n

\n", + "miscs": [ + { + "textRaw": "Cycles", + "name": "Cycles", + "type": "misc", + "desc": "

When there are circular require() calls, a module might not be\ndone being executed when it is returned.\n\n

\n

Consider this situation:\n\n

\n

a.js:\n\n

\n
console.log('a starting');\nexports.done = false;\nvar b = require('./b.js');\nconsole.log('in a, b.done = %j', b.done);\nexports.done = true;\nconsole.log('a done');
\n

b.js:\n\n

\n
console.log('b starting');\nexports.done = false;\nvar a = require('./a.js');\nconsole.log('in b, a.done = %j', a.done);\nexports.done = true;\nconsole.log('b done');
\n

main.js:\n\n

\n
console.log('main starting');\nvar a = require('./a.js');\nvar b = require('./b.js');\nconsole.log('in main, a.done=%j, b.done=%j', a.done, b.done);
\n

When main.js loads a.js, then a.js in turn loads b.js. At that\npoint, b.js tries to load a.js. In order to prevent an infinite\nloop an unfinished copy of the a.js exports object is returned to the\nb.js module. b.js then finishes loading, and its exports object is\nprovided to the a.js module.\n\n

\n

By the time main.js has loaded both modules, they're both finished.\nThe output of this program would thus be:\n\n

\n
$ node main.js\nmain starting\na starting\nb starting\nin b, a.done = false\nb done\nin a, b.done = true\na done\nin main, a.done=true, b.done=true
\n

If you have cyclic module dependencies in your program, make sure to\nplan accordingly.\n\n

\n" + }, + { + "textRaw": "Core Modules", + "name": "Core Modules", + "type": "misc", + "desc": "

Node has several modules compiled into the binary. These modules are\ndescribed in greater detail elsewhere in this documentation.\n\n

\n

The core modules are defined in node's source in the lib/ folder.\n\n

\n

Core modules are always preferentially loaded if their identifier is\npassed to require(). For instance, require('http') will always\nreturn the built in HTTP module, even if there is a file by that name.\n\n

\n" + }, + { + "textRaw": "File Modules", + "name": "File Modules", + "type": "misc", + "desc": "

If the exact filename is not found, then node will attempt to load the\nrequired filename with the added extension of .js, .json, and then .node.\n\n

\n

.js files are interpreted as JavaScript text files, and .json files are\nparsed as JSON text files. .node files are interpreted as compiled addon\nmodules loaded with dlopen.\n\n

\n

A module prefixed with '/' is an absolute path to the file. For\nexample, require('/home/marco/foo.js') will load the file at\n/home/marco/foo.js.\n\n

\n

A module prefixed with './' is relative to the file calling require().\nThat is, circle.js must be in the same directory as foo.js for\nrequire('./circle') to find it.\n\n

\n

Without a leading '/' or './' to indicate a file, the module is either a\n"core module" or is loaded from a node_modules folder.\n\n

\n" + }, + { + "textRaw": "Loading from `node_modules` Folders", + "name": "Loading from `node_modules` Folders", + "type": "misc", + "desc": "

If the module identifier passed to require() is not a native module,\nand does not begin with '/', '../', or './', then node starts at the\nparent directory of the current module, and adds /node_modules, and\nattempts to load the module from that location.\n\n

\n

If it is not found there, then it moves to the parent directory, and so\non, until the root of the tree is reached.\n\n

\n

For example, if the file at '/home/ry/projects/foo.js' called\nrequire('bar.js'), then node would look in the following locations, in\nthis order:\n\n

\n
    \n
  • /home/ry/projects/node_modules/bar.js
    • \n
  • /home/ry/node_modules/bar.js
    • \n
  • /home/node_modules/bar.js
    • \n
  • /node_modules/bar.js
    • \n
\n

This allows programs to localize their dependencies, so that they do not\nclash.\n\n

\n" + }, + { + "textRaw": "Folders as Modules", + "name": "Folders as Modules", + "type": "misc", + "desc": "

It is convenient to organize programs and libraries into self-contained\ndirectories, and then provide a single entry point to that library.\nThere are three ways in which a folder may be passed to require() as\nan argument.\n\n

\n

The first is to create a package.json file in the root of the folder,\nwhich specifies a main module. An example package.json file might\nlook like this:\n\n

\n
{ "name" : "some-library",\n  "main" : "./lib/some-library.js" }
\n

If this was in a folder at ./some-library, then\nrequire('./some-library') would attempt to load\n./some-library/lib/some-library.js.\n\n

\n

This is the extent of Node's awareness of package.json files.\n\n

\n

If there is no package.json file present in the directory, then node\nwill attempt to load an index.js or index.node file out of that\ndirectory. For example, if there was no package.json file in the above\nexample, then require('./some-library') would attempt to load:\n\n

\n
    \n
  • ./some-library/index.js
    • \n
  • ./some-library/index.node
    • \n
\n" + }, + { + "textRaw": "Caching", + "name": "Caching", + "type": "misc", + "desc": "

Modules are cached after the first time they are loaded. This means\n(among other things) that every call to require('foo') will get\nexactly the same object returned, if it would resolve to the same file.\n\n

\n

Multiple calls to require('foo') may not cause the module code to be\nexecuted multiple times. This is an important feature. With it,\n"partially done" objects can be returned, thus allowing transitive\ndependencies to be loaded even when they would cause cycles.\n\n

\n

If you want to have a module execute code multiple times, then export a\nfunction, and call that function.\n\n

\n", + "miscs": [ + { + "textRaw": "Module Caching Caveats", + "name": "Module Caching Caveats", + "type": "misc", + "desc": "

Modules are cached based on their resolved filename. Since modules may\nresolve to a different filename based on the location of the calling\nmodule (loading from node_modules folders), it is not a guarantee\nthat require('foo') will always return the exact same object, if it\nwould resolve to different files.\n\n

\n" + } + ] + }, + { + "textRaw": "All Together...", + "name": "All Together...", + "type": "misc", + "desc": "

To get the exact filename that will be loaded when require() is called, use\nthe require.resolve() function.\n\n

\n

Putting together all of the above, here is the high-level algorithm\nin pseudocode of what require.resolve does:\n\n

\n
require(X) from module at path Y\n1. If X is a core module,\n   a. return the core module\n   b. STOP\n2. If X begins with './' or '/' or '../'\n   a. LOAD_AS_FILE(Y + X)\n   b. LOAD_AS_DIRECTORY(Y + X)\n3. LOAD_NODE_MODULES(X, dirname(Y))\n4. THROW "not found"\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as JavaScript text.  STOP\n2. If X.js is a file, load X.js as JavaScript text.  STOP\n3. If X.node is a file, load X.node as binary addon.  STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n   a. Parse X/package.json, and look for "main" field.\n   b. let M = X + (json main field)\n   c. LOAD_AS_FILE(M)\n2. If X/index.js is a file, load X/index.js as JavaScript text.  STOP\n3. If X/index.node is a file, load X/index.node as binary addon.  STOP\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS=NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n   a. LOAD_AS_FILE(DIR/X)\n   b. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let ROOT = index of first instance of "node_modules" in PARTS, or 0\n3. let I = count of PARTS - 1\n4. let DIRS = []\n5. while I > ROOT,\n   a. if PARTS[I] = "node_modules" CONTINUE\n   c. DIR = path join(PARTS[0 .. I] + "node_modules")\n   b. DIRS = DIRS + DIR\n   c. let I = I - 1\n6. return DIRS
\n" + }, + { + "textRaw": "Loading from the global folders", + "name": "Loading from the global folders", + "type": "misc", + "desc": "

If the NODE_PATH environment variable is set to a colon-delimited list\nof absolute paths, then node will search those paths for modules if they\nare not found elsewhere. (Note: On Windows, NODE_PATH is delimited by\nsemicolons instead of colons.)\n\n

\n

Additionally, node will search in the following locations:\n\n

\n
    \n
  • 1: $HOME/.node_modules
    • \n
  • 2: $HOME/.node_libraries
    • \n
  • 3: $PREFIX/lib/node
    • \n
\n

Where $HOME is the user's home directory, and $PREFIX is node's\nconfigured installPrefix.\n\n

\n

These are mostly for historic reasons. You are highly encouraged to\nplace your dependencies locally in node_modules folders. They will be\nloaded faster, and more reliably.\n\n

\n" + }, + { + "textRaw": "Accessing the main module", + "name": "Accessing the main module", + "type": "misc", + "desc": "

When a file is run directly from Node, require.main is set to its\nmodule. That means that you can determine whether a file has been run\ndirectly by testing\n\n

\n
require.main === module
\n

For a file foo.js, this will be true if run via node foo.js, but\nfalse if run by require('./foo').\n\n

\n

Because module provides a filename property (normally equivalent to\n__filename), the entry point of the current application can be obtained\nby checking require.main.filename.\n\n

\n" + }, + { + "textRaw": "Addenda: Package Manager Tips", + "name": "Addenda: Package Manager Tips", + "type": "misc", + "desc": "

The semantics of Node's require() function were designed to be general\nenough to support a number of sane directory structures. Package manager\nprograms such as dpkg, rpm, and npm will hopefully find it possible to\nbuild native packages from Node modules without modification.\n\n

\n

Below we give a suggested directory structure that could work:\n\n

\n

Let's say that we wanted to have the folder at\n/usr/lib/node/<some-package>/<some-version> hold the contents of a\nspecific version of a package.\n\n

\n

Packages can depend on one another. In order to install package foo, you\nmay have to install a specific version of package bar. The bar package\nmay itself have dependencies, and in some cases, these dependencies may even\ncollide or form cycles.\n\n

\n

Since Node looks up the realpath of any modules it loads (that is,\nresolves symlinks), and then looks for their dependencies in the\nnode_modules folders as described above, this situation is very simple to\nresolve with the following architecture:\n\n

\n
    \n
  • /usr/lib/node/foo/1.2.3/ - Contents of the foo package, version 1.2.3.
    • \n
  • /usr/lib/node/bar/4.3.2/ - Contents of the bar package that foo\ndepends on.
    • \n
  • /usr/lib/node/foo/1.2.3/node_modules/bar - Symbolic link to\n/usr/lib/node/bar/4.3.2/.
    • \n
  • /usr/lib/node/bar/4.3.2/node_modules/* - Symbolic links to the packages\nthat bar depends on.
    • \n
\n

Thus, even if a cycle is encountered, or if there are dependency\nconflicts, every module will be able to get a version of its dependency\nthat it can use.\n\n

\n

When the code in the foo package does require('bar'), it will get the\nversion that is symlinked into /usr/lib/node/foo/1.2.3/node_modules/bar.\nThen, when the code in the bar package calls require('quux'), it'll get\nthe version that is symlinked into\n/usr/lib/node/bar/4.3.2/node_modules/quux.\n\n

\n

Furthermore, to make the module lookup process even more optimal, rather\nthan putting packages directly in /usr/lib/node, we could put them in\n/usr/lib/node_modules/<name>/<version>. Then node will not bother\nlooking for missing dependencies in /usr/node_modules or /node_modules.\n\n

\n

In order to make modules available to the node REPL, it might be useful to\nalso add the /usr/lib/node_modules folder to the $NODE_PATH environment\nvariable. Since the module lookups using node_modules folders are all\nrelative, and based on the real path of the files making the calls to\nrequire(), the packages themselves can be anywhere.\n\n

\n" + } + ], + "vars": [ + { + "textRaw": "The `module` Object", + "name": "module", + "type": "var", + "desc": "

In each module, the module free variable is a reference to the object\nrepresenting the current module. In particular\nmodule.exports is the same as the exports object.\nmodule isn't actually a global but rather local to each module.\n\n

\n", + "properties": [ + { + "textRaw": "`exports` {Object} ", + "name": "exports", + "desc": "

The exports object is created by the Module system. Sometimes this is not\nacceptable, many want their module to be an instance of some class. To do this\nassign the desired export object to module.exports. For example suppose we\nwere making a module called a.js\n\n

\n
var EventEmitter = require('events').EventEmitter;\n\nmodule.exports = new EventEmitter();\n\n// Do some work, and after some time emit\n// the 'ready' event from the module itself.\nsetTimeout(function() {\n  module.exports.emit('ready');\n}, 1000);
\n

Then in another file we could do\n\n

\n
var a = require('./a');\na.on('ready', function() {\n  console.log('module a is ready');\n});
\n

Note that assignment to module.exports must be done immediately. It cannot be\ndone in any callbacks. This does not work:\n\n

\n

x.js:\n\n

\n
setTimeout(function() {\n  module.exports = { a: "hello" };\n}, 0);
\n

y.js:\n\n

\n
var x = require('./x');\nconsole.log(x.a);
\n" + }, + { + "textRaw": "`id` {String} ", + "name": "id", + "desc": "

The identifier for the module. Typically this is the fully resolved\nfilename.\n\n\n

\n" + }, + { + "textRaw": "`filename` {String} ", + "name": "filename", + "desc": "

The fully resolved filename to the module.\n\n\n

\n" + }, + { + "textRaw": "`loaded` {Boolean} ", + "name": "loaded", + "desc": "

Whether or not the module is done loading, or is in the process of\nloading.\n\n\n

\n" + }, + { + "textRaw": "`parent` {Module Object} ", + "name": "parent", + "desc": "

The module that required this one.\n\n\n

\n" + }, + { + "textRaw": "`children` {Array} ", + "name": "children", + "desc": "

The module objects required by this one.\n\n\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "module.require(id)", + "type": "method", + "name": "require", + "signatures": [ + { + "return": { + "textRaw": "Return: {Object} `exports` from the resolved module ", + "name": "return", + "type": "Object", + "desc": "`exports` from the resolved module" + }, + "params": [ + { + "textRaw": "`id` {String} ", + "name": "id", + "type": "String" + } + ] + }, + { + "params": [ + { + "name": "id" + } + ] + } + ], + "desc": "

The module.require method provides a way to load a module as if\nrequire() was called from the original module.\n\n

\n

Note that in order to do this, you must get a reference to the module\nobject. Since require() returns the exports, and the module is\ntypically only available within a specific module's code, it must be\nexplicitly exported in order to be used.\n\n\n

\n" + } + ] + } + ], + "type": "module", + "displayName": "module" + }, + { + "textRaw": "Addons", + "name": "addons", + "desc": "

Addons are dynamically linked shared objects. They can provide glue to C and\nC++ libraries. The API (at the moment) is rather complex, involving\nknowledge of several libraries:\n\n

\n
    \n

  • V8 JavaScript, a C++ library. Used for interfacing with JavaScript:\ncreating objects, calling functions, etc. Documented mostly in the\nv8.h header file (deps/v8/include/v8.h in the Node source tree),\nwhich is also available online.

    \n
    • \n

  • libuv, C event loop library. Anytime one\nneeds to wait for a file descriptor to become readable, wait for a timer, or\nwait for a signal to received one will need to interface with libuv. That is,\nif you perform any I/O, libuv will need to be used.

    \n
    • \n

  • Internal Node libraries. Most importantly is the node::ObjectWrap\nclass which you will likely want to derive from.

    \n
    • \n

  • Others. Look in deps/ for what else is available.

    \n
    • \n
\n

Node statically compiles all its dependencies into the executable. When\ncompiling your module, you don't need to worry about linking to any of these\nlibraries.\n\n\n

\n", + "modules": [ + { + "textRaw": "Hello world", + "name": "hello_world", + "desc": "

To get started let's make a small Addon which is the C++ equivalent of\nthe following Javascript code:\n\n

\n
exports.hello = function() { return 'world'; };
\n

First we create a file hello.cc:\n\n

\n
#include <node.h>\n#include <v8.h>\n\nusing namespace v8;\n\nHandle<Value> Method(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(String::New("world"));\n}\n\nvoid init(Handle<Object> target) {\n  target->Set(String::NewSymbol("hello"),\n      FunctionTemplate::New(Method)->GetFunction());\n}\nNODE_MODULE(hello, init)
\n

Note that all Node addons must export an initialization function:\n\n

\n
void Initialize (Handle<Object> target);\nNODE_MODULE(module_name, Initialize)
\n

There is no semi-colon after NODE_MODULE as it's not a function (see node.h).\n\n

\n

The module_name needs to match the filename of the final binary (minus the\n.node suffix).\n\n

\n

The source code needs to be built into hello.node, the binary Addon. To\ndo this we create a file called wscript which is python code and looks\nlike this:\n\n

\n
srcdir = '.'\nblddir = 'build'\nVERSION = '0.0.1'\n\ndef set_options(opt):\n  opt.tool_options('compiler_cxx')\n\ndef configure(conf):\n  conf.check_tool('compiler_cxx')\n  conf.check_tool('node_addon')\n\ndef build(bld):\n  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')\n  obj.target = 'hello'\n  obj.source = 'hello.cc'
\n

Running node-waf configure build will create a file\nbuild/default/hello.node which is our Addon.\n\n

\n

node-waf is just WAF, the python-based build system. node-waf is\nprovided for the ease of users.\n\n

\n

You can now use the binary addon in a Node project hello.js by pointing require to\nthe recently built module:\n\n

\n
var addon = require('./build/Release/hello');\n\nconsole.log(addon.hello()); // 'world'
\n

Please see patterns below for further information or\n

\n

https://github.com/pietern/hiredis-node for an example in production.\n\n\n

\n", + "type": "module", + "displayName": "Hello world" + }, + { + "textRaw": "Addon patterns", + "name": "addon_patterns", + "desc": "

Below are some addon patterns to help you get started. Consult the online\nv8 reference for help with the various v8\ncalls, and v8's Embedder's Guide\nfor an explanation of several concepts used such as handles, scopes,\nfunction templates, etc.\n\n

\n

To compile these examples, create the wscript file below and run\nnode-waf configure build:\n\n

\n
srcdir = '.'\nblddir = 'build'\nVERSION = '0.0.1'\n\ndef set_options(opt):\n  opt.tool_options('compiler_cxx')\n\ndef configure(conf):\n  conf.check_tool('compiler_cxx')\n  conf.check_tool('node_addon')\n\ndef build(bld):\n  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')\n  obj.target = 'addon'\n  obj.source = ['addon.cc']
\n

In cases where there is more than one .cc file, simply add the file name to the\nobj.source array, e.g.:\n\n

\n
obj.source = ['addon.cc', 'myexample.cc']
\n", + "modules": [ + { + "textRaw": "Function arguments", + "name": "function_arguments", + "desc": "

The following pattern illustrates how to read arguments from JavaScript\nfunction calls and return a result. This is the main and only needed source\naddon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> Add(const Arguments& args) {\n  HandleScope scope;\n\n  if (args.Length() < 2) {\n    ThrowException(Exception::TypeError(String::New("Wrong number of arguments")));\n    return scope.Close(Undefined());\n  }\n\n  if (!args[0]->IsNumber() || !args[1]->IsNumber()) {\n    ThrowException(Exception::TypeError(String::New("Wrong arguments")));\n    return scope.Close(Undefined());\n  }\n\n  Local<Number> num = Number::New(args[0]->NumberValue() +\n      args[1]->NumberValue());\n  return scope.Close(num);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("add"),\n      FunctionTemplate::New(Add)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

You can test it with the following JavaScript snippet:\n\n

\n
var addon = require('./build/Release/addon');\n\nconsole.log( 'This should be eight:', addon.add(3,5) );
\n", + "type": "module", + "displayName": "Function arguments" + }, + { + "textRaw": "Callbacks", + "name": "callbacks", + "desc": "

You can pass JavaScript functions to a C++ function and execute them from\nthere. Here's addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> RunCallback(const Arguments& args) {\n  HandleScope scope;\n\n  Local<Function> cb = Local<Function>::Cast(args[0]);\n  const unsigned argc = 1;\n  Local<Value> argv[argc] = { Local<Value>::New(String::New("hello world")) };\n  cb->Call(Context::GetCurrent()->Global(), argc, argv);\n\n  return scope.Close(Undefined());\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("runCallback"),\n      FunctionTemplate::New(RunCallback)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test it run the following JavaScript snippet:\n\n

\n
var addon = require('./build/Release/addon');\n\naddon.runCallback(function(msg){\n  console.log(msg); // 'hello world'\n});
\n", + "type": "module", + "displayName": "Callbacks" + }, + { + "textRaw": "Object factory", + "name": "object_factory", + "desc": "

You can create and return new objects from within a C++ function with this\naddon.cc pattern, which returns an object with property msg that echoes\nthe string passed to createObject():\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n\n  Local<Object> obj = Object::New();\n  obj->Set(String::NewSymbol("msg"), args[0]->ToString());\n\n  return scope.Close(obj);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test it in JavaScript:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj1 = addon.createObject('hello');\nvar obj2 = addon.createObject('world');\nconsole.log(obj1.msg+' '+obj2.msg); // 'hello world'
\n", + "type": "module", + "displayName": "Object factory" + }, + { + "textRaw": "Function factory", + "name": "function_factory", + "desc": "

This pattern illustrates how to create and return a JavaScript function that\nwraps a C++ function:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> MyFunction(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(String::New("hello world"));\n}\n\nHandle<Value> CreateFunction(const Arguments& args) {\n  HandleScope scope;\n\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(MyFunction);\n  Local<Function> fn = tpl->GetFunction();\n  fn->SetName(String::NewSymbol("theFunction")); // omit this to make it anonymous\n\n  return scope.Close(fn);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("createFunction"),\n      FunctionTemplate::New(CreateFunction)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar fn = addon.createFunction();\nconsole.log(fn()); // 'hello world'
\n", + "type": "module", + "displayName": "Function factory" + }, + { + "textRaw": "Wrapping C++ objects", + "name": "wrapping_c++_objects", + "desc": "

Here we will create a wrapper for a C++ object/class MyObject that can be\ninstantiated in JavaScript through the new operator. First prepare the main\nmodule addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init(target);\n}\n\nNODE_MODULE(addon, InitAll)
\n

Then in myobject.h make your wrapper inherit from node::ObjectWrap:\n\n

\n
#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init(v8::Handle<v8::Object> target);\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);\n  double counter_;\n};\n\n#endif
\n

And in myobject.cc implement the various methods that you want to expose.\nHere we expose the method plusOne by adding it to the constructor's\nprototype:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nvoid MyObject::Init(Handle<Object> target) {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n  // Prototype\n  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),\n      FunctionTemplate::New(PlusOne)->GetFunction());\n\n  Persistent<Function> constructor = Persistent<Function>::New(tpl->GetFunction());\n  target->Set(String::NewSymbol("MyObject"), constructor);\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::PlusOne(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n  obj->counter_ += 1;\n\n  return scope.Close(Number::New(obj->counter_));\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj = new addon.MyObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13
\n", + "type": "module", + "displayName": "Wrapping C++ objects" + }, + { + "textRaw": "Factory of wrapped objects", + "name": "factory_of_wrapped_objects", + "desc": "

This is useful when you want to be able to create native objects without\nexplicitly instantiating them with the new operator in JavaScript, e.g.\n\n

\n
var obj = addon.createObject();\n// instead of:\n// var obj = new addon.Object();
\n

Let's register our createObject method in addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(MyObject::NewInstance(args));\n}\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init();\n\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n}\n\nNODE_MODULE(addon, InitAll)
\n

In myobject.h we now introduce the static method NewInstance that takes\ncare of instantiating the object (i.e. it does the job of new in JavaScript):\n\n

\n
#define BUILDING_NODE_EXTENSION\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init();\n  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Persistent<v8::Function> constructor;\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);\n  double counter_;\n};\n\n#endif
\n

The implementation is similar to the above in myobject.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nPersistent<Function> MyObject::constructor;\n\nvoid MyObject::Init() {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n  // Prototype\n  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),\n      FunctionTemplate::New(PlusOne)->GetFunction());\n\n  constructor = Persistent<Function>::New(tpl->GetFunction());\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::NewInstance(const Arguments& args) {\n  HandleScope scope;\n\n  const unsigned argc = 1;\n  Handle<Value> argv[argc] = { args[0] };\n  Local<Object> instance = constructor->NewInstance(argc, argv);\n\n  return scope.Close(instance);\n}\n\nHandle<Value> MyObject::PlusOne(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n  obj->counter_ += 1;\n\n  return scope.Close(Number::New(obj->counter_));\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj = addon.createObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13\n\nvar obj2 = addon.createObject(20);\nconsole.log( obj2.plusOne() ); // 21\nconsole.log( obj2.plusOne() ); // 22\nconsole.log( obj2.plusOne() ); // 23
\n", + "type": "module", + "displayName": "Factory of wrapped objects" + }, + { + "textRaw": "Passing wrapped objects around", + "name": "passing_wrapped_objects_around", + "desc": "

In addition to wrapping and returning C++ objects, you can pass them around\nby unwrapping them with Node's node::ObjectWrap::Unwrap helper function.\nIn the following addon.cc we introduce a function add() that can take on two\nMyObject objects:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(MyObject::NewInstance(args));\n}\n\nHandle<Value> Add(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(\n      args[0]->ToObject());\n  MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(\n      args[1]->ToObject());\n\n  double sum = obj1->Val() + obj2->Val();\n  return scope.Close(Number::New(sum));\n}\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init();\n\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n\n  target->Set(String::NewSymbol("add"),\n      FunctionTemplate::New(Add)->GetFunction());\n}\n\nNODE_MODULE(addon, InitAll)
\n

To make things interesting we introduce a public method in myobject.h so we\ncan probe private values after unwrapping the object:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init();\n  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);\n  double Val() const { return val_; }\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Persistent<v8::Function> constructor;\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  double val_;\n};\n\n#endif
\n

The implementation of myobject.cc is similar as before:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nPersistent<Function> MyObject::constructor;\n\nvoid MyObject::Init() {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n\n  constructor = Persistent<Function>::New(tpl->GetFunction());\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->val_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::NewInstance(const Arguments& args) {\n  HandleScope scope;\n\n  const unsigned argc = 1;\n  Handle<Value> argv[argc] = { args[0] };\n  Local<Object> instance = constructor->NewInstance(argc, argv);\n\n  return scope.Close(instance);\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj1 = addon.createObject(10);\nvar obj2 = addon.createObject(20);\nvar result = addon.add(obj1, obj2);\n\nconsole.log(result); // 30
\n", + "type": "module", + "displayName": "Passing wrapped objects around" + } + ], + "type": "module", + "displayName": "Addon patterns" + } + ], + "type": "module", + "displayName": "Addons" + }, + { + "textRaw": "util", + "name": "util", + "stability": 5, + "stabilityText": "Locked", + "desc": "

These functions are in the module 'util'. Use require('util') to access\nthem.\n\n\n

\n", + "methods": [ + { + "textRaw": "util.format()", + "type": "method", + "name": "format", + "desc": "

Returns a formatted string using the first argument as a printf-like format.\n\n

\n

The first argument is a string that contains zero or more placeholders.\nEach placeholder is replaced with the converted value from its corresponding\nargument. Supported placeholders are:\n\n

\n
    \n
  • %s - String.
    • \n
  • %d - Number (both integer and float).
    • \n
  • %j - JSON.
    • \n
  • %% - single percent sign ('%'). This does not consume an argument.
    • \n
\n

If the placeholder does not have a corresponding argument, the placeholder is\nnot replaced.\n\n

\n
util.format('%s:%s', 'foo'); // 'foo:%s'
\n

If there are more arguments than placeholders, the extra arguments are\nconverted to strings with util.inspect() and these strings are concatenated,\ndelimited by a space.\n\n

\n
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
\n

If the first argument is not a format string then util.format() returns\na string that is the concatenation of all its arguments separated by spaces.\nEach argument is converted to a string with util.inspect().\n\n

\n
util.format(1, 2, 3); // '1 2 3'
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "util.debug(string)", + "type": "method", + "name": "debug", + "desc": "

A synchronous output function. Will block the process and\noutput string immediately to stderr.\n\n

\n
require('util').debug('message on stderr');
\n", + "signatures": [ + { + "params": [ + { + "name": "string" + } + ] + } + ] + }, + { + "textRaw": "util.log(string)", + "type": "method", + "name": "log", + "desc": "

Output with timestamp on stdout.\n\n

\n
require('util').log('Timestamped message.');
\n", + "signatures": [ + { + "params": [ + { + "name": "string" + } + ] + } + ] + }, + { + "textRaw": "util.inspect(object, [showHidden], [depth], [colors])", + "type": "method", + "name": "inspect", + "desc": "

Return a string representation of object, which is useful for debugging.\n\n

\n

If showHidden is true, then the object's non-enumerable properties will be\nshown too. Defaults to false.\n\n

\n

If depth is provided, it tells inspect how many times to recurse while\nformatting the object. This is useful for inspecting large complicated objects.\n\n

\n

The default is to only recurse twice. To make it recurse indefinitely, pass\nin null for depth.\n\n

\n

If colors is true, the output will be styled with ANSI color codes.\nDefaults to false.\n\n

\n

Example of inspecting all properties of the util object:\n\n

\n
var util = require('util');\n\nconsole.log(util.inspect(util, true, null));
\n", + "signatures": [ + { + "params": [ + { + "name": "object" + }, + { + "name": "showHidden", + "optional": true + }, + { + "name": "depth", + "optional": true + }, + { + "name": "colors", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "util.isArray(object)", + "type": "method", + "name": "isArray", + "desc": "

Returns true if the given "object" is an Array. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isArray([])\n  // true\nutil.isArray(new Array)\n  // true\nutil.isArray({})\n  // false
\n", + "signatures": [ + { + "params": [ + { + "name": "object" + } + ] + } + ] + }, + { + "textRaw": "util.isRegExp(object)", + "type": "method", + "name": "isRegExp", + "desc": "

Returns true if the given "object" is a RegExp. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isRegExp(/some regexp/)\n  // true\nutil.isRegExp(new RegExp('another regexp'))\n  // true\nutil.isRegExp({})\n  // false
\n", + "signatures": [ + { + "params": [ + { + "name": "object" + } + ] + } + ] + }, + { + "textRaw": "util.isDate(object)", + "type": "method", + "name": "isDate", + "desc": "

Returns true if the given "object" is a Date. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isDate(new Date())\n  // true\nutil.isDate(Date())\n  // false (without 'new' returns a String)\nutil.isDate({})\n  // false
\n", + "signatures": [ + { + "params": [ + { + "name": "object" + } + ] + } + ] + }, + { + "textRaw": "util.isError(object)", + "type": "method", + "name": "isError", + "desc": "

Returns true if the given "object" is an Error. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isError(new Error())\n  // true\nutil.isError(new TypeError())\n  // true\nutil.isError({ name: 'Error', message: 'an error occurred' })\n  // false
\n", + "signatures": [ + { + "params": [ + { + "name": "object" + } + ] + } + ] + }, + { + "textRaw": "util.pump(readableStream, writableStream, [callback])", + "type": "method", + "name": "pump", + "desc": "

Experimental\n\n

\n

Read the data from readableStream and send it to the writableStream.\nWhen writableStream.write(data) returns false readableStream will be\npaused until the drain event occurs on the writableStream. callback gets\nan error as its only argument and is called when writableStream is closed or\nwhen an error occurs.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "readableStream" + }, + { + "name": "writableStream" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "util.inherits(constructor, superConstructor)", + "type": "method", + "name": "inherits", + "desc": "

Inherit the prototype methods from one\nconstructor\ninto another. The prototype of constructor will be set to a new\nobject created from superConstructor.\n\n

\n

As an additional convenience, superConstructor will be accessible\nthrough the constructor.super_ property.\n\n

\n
var util = require("util");\nvar events = require("events");\n\nfunction MyStream() {\n    events.EventEmitter.call(this);\n}\n\nutil.inherits(MyStream, events.EventEmitter);\n\nMyStream.prototype.write = function(data) {\n    this.emit("data", data);\n}\n\nvar stream = new MyStream();\n\nconsole.log(stream instanceof events.EventEmitter); // true\nconsole.log(MyStream.super_ === events.EventEmitter); // true\n\nstream.on("data", function(data) {\n    console.log('Received data: "' + data + '"');\n})\nstream.write("It works!"); // Received data: "It works!"
\n", + "signatures": [ + { + "params": [ + { + "name": "constructor" + }, + { + "name": "superConstructor" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "util" + }, + { + "textRaw": "Events", + "name": "Events", + "stability": 4, + "stabilityText": "API Frozen", + "type": "module", + "desc": "

Many objects in Node emit events: a net.Server emits an event each time\na peer connects to it, a fs.readStream emits an event when the file is\nopened. All objects which emit events are instances of events.EventEmitter.\nYou can access this module by doing: require("events");\n\n

\n

Typically, event names are represented by a camel-cased string, however,\nthere aren't any strict restrictions on that, as any string will be accepted.\n\n

\n

Functions can then be attached to objects, to be executed when an event\nis emitted. These functions are called listeners.\n\n\n

\n", + "classes": [ + { + "textRaw": "Class: events.EventEmitter", + "type": "class", + "name": "events.EventEmitter", + "desc": "

To access the EventEmitter class, require('events').EventEmitter.\n\n

\n

When an EventEmitter instance experiences an error, the typical action is\nto emit an 'error' event. Error events are treated as a special case in node.\nIf there is no listener for it, then the default action is to print a stack\ntrace and exit the program.\n\n

\n

All EventEmitters emit the event 'newListener' when new listeners are\nadded.\n\n

\n", + "methods": [ + { + "textRaw": "emitter.addListener(event, listener)", + "type": "method", + "name": "addListener", + "desc": "

Adds a listener to the end of the listeners array for the specified event.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "event" + }, + { + "name": "listener" + } + ] + }, + { + "params": [ + { + "name": "event" + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "emitter.on(event, listener)", + "type": "method", + "name": "on", + "desc": "

Adds a listener to the end of the listeners array for the specified event.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "event" + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "emitter.once(event, listener)", + "type": "method", + "name": "once", + "desc": "

Adds a one time listener for the event. This listener is\ninvoked only the next time the event is fired, after which\nit is removed.\n\n

\n
server.once('connection', function (stream) {\n  console.log('Ah, we have our first user!');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "event" + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "emitter.removeListener(event, listener)", + "type": "method", + "name": "removeListener", + "desc": "

Remove a listener from the listener array for the specified event.\nCaution: changes array indices in the listener array behind the listener.\n\n

\n
var callback = function(stream) {\n  console.log('someone connected!');\n};\nserver.on('connection', callback);\n// ...\nserver.removeListener('connection', callback);
\n", + "signatures": [ + { + "params": [ + { + "name": "event" + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "emitter.removeAllListeners([event])", + "type": "method", + "name": "removeAllListeners", + "desc": "

Removes all listeners, or those of the specified event.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "event", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "emitter.setMaxListeners(n)", + "type": "method", + "name": "setMaxListeners", + "desc": "

By default EventEmitters will print a warning if more than 10 listeners are\nadded for a particular event. This is a useful default which helps finding memory leaks.\nObviously not all Emitters should be limited to 10. This function allows\nthat to be increased. Set to zero for unlimited.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "n" + } + ] + } + ] + }, + { + "textRaw": "emitter.listeners(event)", + "type": "method", + "name": "listeners", + "desc": "

Returns an array of listeners for the specified event. This array can be\nmanipulated, e.g. to remove listeners.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});\nconsole.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
\n", + "signatures": [ + { + "params": [ + { + "name": "event" + } + ] + } + ] + }, + { + "textRaw": "emitter.emit(event, [arg1], [arg2], [...])", + "type": "method", + "name": "emit", + "desc": "

Execute each of the listeners in order with the supplied arguments.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "event" + }, + { + "name": "arg1", + "optional": true + }, + { + "name": "arg2", + "optional": true + }, + { + "name": "...", + "optional": true + } + ] + } + ] + } + ], + "events": [ + { + "textRaw": "Event: 'newListener'", + "type": "event", + "name": "newListener", + "params": [], + "desc": "

This event is emitted any time someone adds a new listener.\n\n

\n" + } + ] + } + ] + }, + { + "textRaw": "Buffer", + "name": "buffer", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Pure Javascript is Unicode friendly but not nice to binary data. When\ndealing with TCP streams or the file system, it's necessary to handle octet\nstreams. Node has several strategies for manipulating, creating, and\nconsuming octet streams.\n\n

\n

Raw data is stored in instances of the Buffer class. A Buffer is similar\nto an array of integers but corresponds to a raw memory allocation outside\nthe V8 heap. A Buffer cannot be resized.\n\n

\n

The Buffer class is a global, making it very rare that one would need\nto ever require('buffer').\n\n

\n

Converting between Buffers and JavaScript string objects requires an explicit\nencoding method. Here are the different string encodings.\n\n

\n
    \n

  • 'ascii' - for 7 bit ASCII data only. This encoding method is very fast, and\nwill strip the high bit if set.\nNote that this encoding converts a null character ('\\0' or '\\u0000') into\n0x20 (character code of a space). If you want to convert a null character\ninto 0x00, you should use 'utf8'.

    \n
    • \n

  • 'utf8' - Multi byte encoded Unicode characters. Many web pages and other document formats use UTF-8.

    \n
    • \n

  • 'ucs2' - 2-bytes, little endian encoded Unicode characters. It can encode\nonly BMP(Basic Multilingual Plane, U+0000 - U+FFFF).

    \n
    • \n

  • 'base64' - Base64 string encoding.

    \n
    • \n

  • 'binary' - A way of encoding raw binary data into strings by using only\nthe first 8 bits of each character. This encoding method is deprecated and\nshould be avoided in favor of Buffer objects where possible. This encoding\nwill be removed in future versions of Node.

    \n
    • \n

  • 'hex' - Encode each byte as two hexidecimal characters.

    \n
    • \n
\n", + "classes": [ + { + "textRaw": "Class: Buffer", + "type": "class", + "name": "Buffer", + "desc": "

The Buffer class is a global type for dealing with binary data directly.\nIt can be constructed in a variety of ways.\n\n

\n", + "methods": [ + { + "textRaw": "buf.write(string, [offset], [length], [encoding])", + "type": "method", + "name": "write", + "signatures": [ + { + "params": [ + { + "textRaw": "`string` String - data to be written to buffer ", + "name": "string", + "desc": "String - data to be written to buffer" + }, + { + "textRaw": "`offset` Number, Optional, Default: 0 ", + "name": "offset", + "desc": "Number, Optional, Default: 0", + "optional": true + }, + { + "textRaw": "`length` Number, Optional, Default: `buffer.length - offset` ", + "name": "length", + "desc": "Number, Optional, Default: `buffer.length - offset`", + "optional": true + }, + { + "textRaw": "`encoding` String, Optional, Default: 'utf8' ", + "name": "encoding", + "desc": "String, Optional, Default: 'utf8'", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "string" + }, + { + "name": "offset", + "optional": true + }, + { + "name": "length", + "optional": true + }, + { + "name": "encoding", + "optional": true + } + ] + } + ], + "desc": "

Writes string to the buffer at offset using the given encoding.\noffset defaults to 0, encoding defaults to 'utf8'. length is\nthe number of bytes to write. Returns number of octets written. If buffer did\nnot contain enough space to fit the entire string, it will write a partial\namount of the string. length defaults to buffer.length - offset.\nThe method will not write partial characters.\n\n

\n
buf = new Buffer(256);\nlen = buf.write('\\u00bd + \\u00bc = \\u00be', 0);\nconsole.log(len + " bytes: " + buf.toString('utf8', 0, len));
\n

The number of characters written (which may be different than the number of\nbytes written) is set in Buffer._charsWritten and will be overwritten the\nnext time buf.write() is called.\n\n\n

\n" + }, + { + "textRaw": "buf.toString([encoding], [start], [end])", + "type": "method", + "name": "toString", + "signatures": [ + { + "params": [ + { + "textRaw": "`encoding` String, Optional, Default: 'utf8' ", + "name": "encoding", + "desc": "String, Optional, Default: 'utf8'", + "optional": true + }, + { + "textRaw": "`start` Number, Optional, Default: 0 ", + "name": "start", + "desc": "Number, Optional, Default: 0", + "optional": true + }, + { + "textRaw": "`end` Number, Optional, Default: `buffer.length` ", + "name": "end", + "desc": "Number, Optional, Default: `buffer.length`", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "encoding", + "optional": true + }, + { + "name": "start", + "optional": true + }, + { + "name": "end", + "optional": true + } + ] + } + ], + "desc": "

Decodes and returns a string from buffer data encoded with encoding\n(defaults to 'utf8') beginning at start (defaults to 0) and ending at\nend (defaults to buffer.length).\n\n

\n

See buffer.write() example, above.\n\n\n

\n" + }, + { + "textRaw": "buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])", + "type": "method", + "name": "copy", + "signatures": [ + { + "params": [ + { + "textRaw": "`targetBuffer` Buffer object - Buffer to copy into ", + "name": "targetBuffer", + "desc": "Buffer object - Buffer to copy into" + }, + { + "textRaw": "`targetStart` Number, Optional, Default: 0 ", + "name": "targetStart", + "desc": "Number, Optional, Default: 0", + "optional": true + }, + { + "textRaw": "`sourceStart` Number, Optional, Default: 0 ", + "name": "sourceStart", + "desc": "Number, Optional, Default: 0", + "optional": true + }, + { + "textRaw": "`sourceEnd` Number, Optional, Default: `buffer.length` ", + "name": "sourceEnd", + "desc": "Number, Optional, Default: `buffer.length`", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "targetBuffer" + }, + { + "name": "targetStart", + "optional": true + }, + { + "name": "sourceStart", + "optional": true + }, + { + "name": "sourceEnd", + "optional": true + } + ] + } + ], + "desc": "

Does copy between buffers. The source and target regions can be overlapped.\ntargetStart and sourceStart default to 0.\nsourceEnd defaults to buffer.length.\n\n

\n

Example: build two Buffers, then copy buf1 from byte 16 through byte 19\ninto buf2, starting at the 8th byte in buf2.\n\n

\n
buf1 = new Buffer(26);\nbuf2 = new Buffer(26);\n\nfor (var i = 0 ; i < 26 ; i++) {\n  buf1[i] = i + 97; // 97 is ASCII a\n  buf2[i] = 33; // ASCII !\n}\n\nbuf1.copy(buf2, 8, 16, 20);\nconsole.log(buf2.toString('ascii', 0, 25));\n\n// !!!!!!!!qrst!!!!!!!!!!!!!
\n" + }, + { + "textRaw": "buf.slice([start], [end])", + "type": "method", + "name": "slice", + "signatures": [ + { + "params": [ + { + "textRaw": "`start` Number, Optional, Default: 0 ", + "name": "start", + "desc": "Number, Optional, Default: 0", + "optional": true + }, + { + "textRaw": "`end` Number, Optional, Default: `buffer.length` ", + "name": "end", + "desc": "Number, Optional, Default: `buffer.length`", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "start", + "optional": true + }, + { + "name": "end", + "optional": true + } + ] + } + ], + "desc": "

Returns a new buffer which references the same memory as the old, but offset\nand cropped by the start (defaults to 0) and end (defaults to\nbuffer.length) indexes.\n\n

\n

Modifying the new buffer slice will modify memory in the original buffer!\n\n

\n

Example: build a Buffer with the ASCII alphabet, take a slice, then modify one\nbyte from the original Buffer.\n\n

\n
var buf1 = new Buffer(26);\n\nfor (var i = 0 ; i < 26 ; i++) {\n  buf1[i] = i + 97; // 97 is ASCII a\n}\n\nvar buf2 = buf1.slice(0, 3);\nconsole.log(buf2.toString('ascii', 0, buf2.length));\nbuf1[0] = 33;\nconsole.log(buf2.toString('ascii', 0, buf2.length));\n\n// abc\n// !bc
\n" + }, + { + "textRaw": "buf.readUInt8(offset, [noAssert])", + "type": "method", + "name": "readUInt8", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads an unsigned 8 bit integer from the buffer at the specified offset.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nfor (ii = 0; ii < buf.length; ii++) {\n  console.log(buf.readUInt8(ii));\n}\n\n// 0x3\n// 0x4\n// 0x23\n// 0x42
\n" + }, + { + "textRaw": "buf.readUInt16LE(offset, [noAssert])", + "type": "method", + "name": "readUInt16LE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads an unsigned 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt16BE(0));\nconsole.log(buf.readUInt16LE(0));\nconsole.log(buf.readUInt16BE(1));\nconsole.log(buf.readUInt16LE(1));\nconsole.log(buf.readUInt16BE(2));\nconsole.log(buf.readUInt16LE(2));\n\n// 0x0304\n// 0x0403\n// 0x0423\n// 0x2304\n// 0x2342\n// 0x4223
\n" + }, + { + "textRaw": "buf.readUInt16BE(offset, [noAssert])", + "type": "method", + "name": "readUInt16BE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads an unsigned 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt16BE(0));\nconsole.log(buf.readUInt16LE(0));\nconsole.log(buf.readUInt16BE(1));\nconsole.log(buf.readUInt16LE(1));\nconsole.log(buf.readUInt16BE(2));\nconsole.log(buf.readUInt16LE(2));\n\n// 0x0304\n// 0x0403\n// 0x0423\n// 0x2304\n// 0x2342\n// 0x4223
\n" + }, + { + "textRaw": "buf.readUInt32LE(offset, [noAssert])", + "type": "method", + "name": "readUInt32LE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads an unsigned 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt32BE(0));\nconsole.log(buf.readUInt32LE(0));\n\n// 0x03042342\n// 0x42230403
\n" + }, + { + "textRaw": "buf.readUInt32BE(offset, [noAssert])", + "type": "method", + "name": "readUInt32BE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads an unsigned 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt32BE(0));\nconsole.log(buf.readUInt32LE(0));\n\n// 0x03042342\n// 0x42230403
\n" + }, + { + "textRaw": "buf.readInt8(offset, [noAssert])", + "type": "method", + "name": "readInt8", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a signed 8 bit integer from the buffer at the specified offset.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt8, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" + }, + { + "textRaw": "buf.readInt16LE(offset, [noAssert])", + "type": "method", + "name": "readInt16LE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a signed 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt16*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" + }, + { + "textRaw": "buf.readInt16BE(offset, [noAssert])", + "type": "method", + "name": "readInt16BE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a signed 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt16*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" + }, + { + "textRaw": "buf.readInt32LE(offset, [noAssert])", + "type": "method", + "name": "readInt32LE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a signed 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt32*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" + }, + { + "textRaw": "buf.readInt32BE(offset, [noAssert])", + "type": "method", + "name": "readInt32BE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a signed 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt32*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" + }, + { + "textRaw": "buf.readFloatLE(offset, [noAssert])", + "type": "method", + "name": "readFloatLE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a 32 bit float from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x00;\nbuf[1] = 0x00;\nbuf[2] = 0x80;\nbuf[3] = 0x3f;\n\nconsole.log(buf.readFloatLE(0));\n\n// 0x01
\n" + }, + { + "textRaw": "buf.readFloatBE(offset, [noAssert])", + "type": "method", + "name": "readFloatBE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a 32 bit float from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x00;\nbuf[1] = 0x00;\nbuf[2] = 0x80;\nbuf[3] = 0x3f;\n\nconsole.log(buf.readFloatLE(0));\n\n// 0x01
\n" + }, + { + "textRaw": "buf.readDoubleLE(offset, [noAssert])", + "type": "method", + "name": "readDoubleLE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a 64 bit double from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\n\nbuf[0] = 0x55;\nbuf[1] = 0x55;\nbuf[2] = 0x55;\nbuf[3] = 0x55;\nbuf[4] = 0x55;\nbuf[5] = 0x55;\nbuf[6] = 0xd5;\nbuf[7] = 0x3f;\n\nconsole.log(buf.readDoubleLE(0));\n\n// 0.3333333333333333
\n" + }, + { + "textRaw": "buf.readDoubleBE(offset, [noAssert])", + "type": "method", + "name": "readDoubleBE", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Reads a 64 bit double from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\n\nbuf[0] = 0x55;\nbuf[1] = 0x55;\nbuf[2] = 0x55;\nbuf[3] = 0x55;\nbuf[4] = 0x55;\nbuf[5] = 0x55;\nbuf[6] = 0xd5;\nbuf[7] = 0x3f;\n\nconsole.log(buf.readDoubleLE(0));\n\n// 0.3333333333333333
\n" + }, + { + "textRaw": "buf.writeUInt8(value, offset, [noAssert])", + "type": "method", + "name": "writeUInt8", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset. Note, value must be a\nvalid unsigned 8 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt8(0x3, 0);\nbuf.writeUInt8(0x4, 1);\nbuf.writeUInt8(0x23, 2);\nbuf.writeUInt8(0x42, 3);\n\nconsole.log(buf);\n\n// <Buffer 03 04 23 42>
\n" + }, + { + "textRaw": "buf.writeUInt16LE(value, offset, [noAssert])", + "type": "method", + "name": "writeUInt16LE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt16BE(0xdead, 0);\nbuf.writeUInt16BE(0xbeef, 2);\n\nconsole.log(buf);\n\nbuf.writeUInt16LE(0xdead, 0);\nbuf.writeUInt16LE(0xbeef, 2);\n\nconsole.log(buf);\n\n// <Buffer de ad be ef>\n// <Buffer ad de ef be>
\n" + }, + { + "textRaw": "buf.writeUInt16BE(value, offset, [noAssert])", + "type": "method", + "name": "writeUInt16BE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt16BE(0xdead, 0);\nbuf.writeUInt16BE(0xbeef, 2);\n\nconsole.log(buf);\n\nbuf.writeUInt16LE(0xdead, 0);\nbuf.writeUInt16LE(0xbeef, 2);\n\nconsole.log(buf);\n\n// <Buffer de ad be ef>\n// <Buffer ad de ef be>
\n" + }, + { + "textRaw": "buf.writeUInt32LE(value, offset, [noAssert])", + "type": "method", + "name": "writeUInt32LE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt32BE(0xfeedface, 0);\n\nconsole.log(buf);\n\nbuf.writeUInt32LE(0xfeedface, 0);\n\nconsole.log(buf);\n\n// <Buffer fe ed fa ce>\n// <Buffer ce fa ed fe>
\n" + }, + { + "textRaw": "buf.writeUInt32BE(value, offset, [noAssert])", + "type": "method", + "name": "writeUInt32BE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt32BE(0xfeedface, 0);\n\nconsole.log(buf);\n\nbuf.writeUInt32LE(0xfeedface, 0);\n\nconsole.log(buf);\n\n// <Buffer fe ed fa ce>\n// <Buffer ce fa ed fe>
\n" + }, + { + "textRaw": "buf.writeInt8(value, offset, [noAssert])", + "type": "method", + "name": "writeInt8", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset. Note, value must be a\nvalid signed 8 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt8, except value is written out as a two's complement\nsigned integer into buffer.\n\n

\n" + }, + { + "textRaw": "buf.writeInt16LE(value, offset, [noAssert])", + "type": "method", + "name": "writeInt16LE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt16*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" + }, + { + "textRaw": "buf.writeInt16BE(value, offset, [noAssert])", + "type": "method", + "name": "writeInt16BE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt16*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" + }, + { + "textRaw": "buf.writeInt32LE(value, offset, [noAssert])", + "type": "method", + "name": "writeInt32LE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt32*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" + }, + { + "textRaw": "buf.writeInt32BE(value, offset, [noAssert])", + "type": "method", + "name": "writeInt32BE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt32*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" + }, + { + "textRaw": "buf.writeFloatLE(value, offset, [noAssert])", + "type": "method", + "name": "writeFloatLE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 32 bit float.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeFloatBE(0xcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeFloatLE(0xcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 4f 4a fe bb>\n// <Buffer bb fe 4a 4f>
\n" + }, + { + "textRaw": "buf.writeFloatBE(value, offset, [noAssert])", + "type": "method", + "name": "writeFloatBE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 32 bit float.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeFloatBE(0xcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeFloatLE(0xcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 4f 4a fe bb>\n// <Buffer bb fe 4a 4f>
\n" + }, + { + "textRaw": "buf.writeDoubleLE(value, offset, [noAssert])", + "type": "method", + "name": "writeDoubleLE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 64 bit double.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\nbuf.writeDoubleBE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeDoubleLE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 43 eb d5 b7 dd f9 5f d7>\n// <Buffer d7 5f f9 dd b7 d5 eb 43>
\n" + }, + { + "textRaw": "buf.writeDoubleBE(value, offset, [noAssert])", + "type": "method", + "name": "writeDoubleBE", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` Number ", + "name": "value", + "desc": "Number" + }, + { + "textRaw": "`offset` Number ", + "name": "offset", + "desc": "Number" + }, + { + "textRaw": "`noAssert` Boolean, Optional, Default: false ", + "name": "noAssert", + "desc": "Boolean, Optional, Default: false", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset" + }, + { + "name": "noAssert", + "optional": true + } + ] + } + ], + "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 64 bit double.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\nbuf.writeDoubleBE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeDoubleLE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 43 eb d5 b7 dd f9 5f d7>\n// <Buffer d7 5f f9 dd b7 d5 eb 43>
\n" + }, + { + "textRaw": "buf.fill(value, [offset], [end])", + "type": "method", + "name": "fill", + "signatures": [ + { + "params": [ + { + "textRaw": "`value` ", + "name": "value" + }, + { + "textRaw": "`offset` Number, Optional ", + "name": "offset", + "optional": true, + "desc": "Number" + }, + { + "textRaw": "`end` Number, Optional ", + "name": "end", + "optional": true, + "desc": "Number" + } + ] + }, + { + "params": [ + { + "name": "value" + }, + { + "name": "offset", + "optional": true + }, + { + "name": "end", + "optional": true + } + ] + } + ], + "desc": "

Fills the buffer with the specified value. If the offset (defaults to 0)\nand end (defaults to buffer.length) are not given it will fill the entire\nbuffer.\n\n

\n
var b = new Buffer(50);\nb.fill("h");
\n" + } + ], + "properties": [ + { + "textRaw": "buf[index]", + "name": "[index]", + "desc": "

Get and set the octet at index. The values refer to individual bytes,\nso the legal range is between 0x00 and 0xFF hex or 0 and 255.\n\n

\n

Example: copy an ASCII string into a buffer, one byte at a time:\n\n

\n
str = "node.js";\nbuf = new Buffer(str.length);\n\nfor (var i = 0; i < str.length ; i++) {\n  buf[i] = str.charCodeAt(i);\n}\n\nconsole.log(buf);\n\n// node.js
\n" + }, + { + "textRaw": "`length` Number ", + "name": "length", + "desc": "

The size of the buffer in bytes. Note that this is not necessarily the size\nof the contents. length refers to the amount of memory allocated for the\nbuffer object. It does not change when the contents of the buffer are changed.\n\n

\n
buf = new Buffer(1234);\n\nconsole.log(buf.length);\nbuf.write("some string", "ascii", 0);\nconsole.log(buf.length);\n\n// 1234\n// 1234
\n", + "shortDesc": "Number" + } + ], + "classMethods": [ + { + "textRaw": "Class Method: Buffer.isBuffer(obj)", + "type": "classMethod", + "name": "isBuffer", + "signatures": [ + { + "return": { + "textRaw": "Return: Boolean ", + "name": "return", + "desc": "Boolean" + }, + "params": [ + { + "textRaw": "`obj` Object ", + "name": "obj", + "desc": "Object" + } + ] + }, + { + "params": [ + { + "name": "obj" + } + ] + } + ], + "desc": "

Tests if obj is a Buffer.\n\n

\n" + }, + { + "textRaw": "Class Method: Buffer.byteLength(string, [encoding])", + "type": "classMethod", + "name": "byteLength", + "signatures": [ + { + "return": { + "textRaw": "Return: Number ", + "name": "return", + "desc": "Number" + }, + "params": [ + { + "textRaw": "`string` String ", + "name": "string", + "desc": "String" + }, + { + "textRaw": "`encoding` String, Optional, Default: 'utf8' ", + "name": "encoding", + "desc": "String, Optional, Default: 'utf8'", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "string" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ], + "desc": "

Gives the actual byte length of a string. encoding defaults to 'utf8'.\nThis is not the same as String.prototype.length since that returns the\nnumber of characters in a string.\n\n

\n

Example:\n\n

\n
str = '\\u00bd + \\u00bc = \\u00be';\n\nconsole.log(str + ": " + str.length + " characters, " +\n  Buffer.byteLength(str, 'utf8') + " bytes");\n\n// ½ + ¼ = ¾: 9 characters, 12 bytes
\n" + } + ], + "signatures": [ + { + "params": [ + { + "textRaw": "`size` Number ", + "name": "size", + "desc": "Number" + } + ], + "desc": "

Allocates a new buffer of size octets.\n\n

\n" + }, + { + "params": [ + { + "name": "size" + } + ], + "desc": "

Allocates a new buffer of size octets.\n\n

\n" + }, + { + "params": [ + { + "textRaw": "`array` Array ", + "name": "array", + "desc": "Array" + } + ], + "desc": "

Allocates a new buffer using an array of octets.\n\n

\n" + }, + { + "params": [ + { + "name": "array" + } + ], + "desc": "

Allocates a new buffer using an array of octets.\n\n

\n" + }, + { + "params": [ + { + "textRaw": "`str` String - string to encode. ", + "name": "str", + "desc": "String - string to encode." + }, + { + "textRaw": "`encoding` String - encoding to use, Optional. ", + "name": "encoding", + "desc": "String - encoding to use, Optional.", + "optional": true + } + ], + "desc": "

Allocates a new buffer containing the given str.\nencoding defaults to 'utf8'.\n\n

\n" + }, + { + "params": [ + { + "name": "str" + }, + { + "name": "encoding", + "optional": true + } + ], + "desc": "

Allocates a new buffer containing the given str.\nencoding defaults to 'utf8'.\n\n

\n" + } + ] + }, + { + "textRaw": "Class: SlowBuffer", + "type": "class", + "name": "SlowBuffer", + "desc": "

This class is primarily for internal use. JavaScript programs should\nuse Buffer instead of using SlowBuffer.\n\n

\n

In order to avoid the overhead of allocating many C++ Buffer objects for\nsmall blocks of memory in the lifetime of a server, Node allocates memory\nin 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it\nwill be backed by a parent SlowBuffer object. If it is larger than this,\nthen Node will allocate a SlowBuffer slab for it directly.\n\n

\n" + } + ], + "properties": [ + { + "textRaw": "`INSPECT_MAX_BYTES` Number, Default: 50 ", + "name": "INSPECT_MAX_BYTES", + "desc": "

How many bytes will be returned when buffer.inspect() is called. This can\nbe overridden by user modules.\n\n

\n

Note that this is a property on the buffer module returned by\nrequire('buffer'), not on the Buffer global, or a buffer instance.\n\n

\n", + "shortDesc": "Number, Default: 50" + } + ], + "type": "module", + "displayName": "Buffer" + }, + { + "textRaw": "Stream", + "name": "stream", + "stability": 2, + "stabilityText": "Unstable", + "desc": "

A stream is an abstract interface implemented by various objects in Node.\nFor example a request to an HTTP server is a stream, as is stdout. Streams\nare readable, writable, or both. All streams are instances of EventEmitter.\n\n

\n

You can load up the Stream base class by doing require('stream').\n\n

\n", + "classes": [ + { + "textRaw": "Readable Stream", + "name": "Readable Stream", + "type": "class", + "desc": "

A Readable Stream has the following methods, members, and events.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'data'", + "type": "event", + "name": "data", + "desc": "

function (data) { }\n\n

\n

The 'data' event emits either a Buffer (by default) or a string if\nsetEncoding() was used.\n\n

\n

Note that the data will be lost if there is no listener when a\nReadable Stream emits a 'data' event.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'end'", + "type": "event", + "name": "end", + "desc": "

function () { }\n\n

\n

Emitted when the stream has received an EOF (FIN in TCP terminology).\nIndicates that no more 'data' events will happen. If the stream is also\nwritable, it may be possible to continue writing.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "desc": "

function (exception) { }\n\n

\n

Emitted if there was an error receiving data.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () { }\n\n

\n

Emitted when the underlying file descriptor has been closed. Not all streams\nwill emit this. (For example, an incoming HTTP request will not emit\n'close'.)\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "stream.readable", + "name": "readable", + "desc": "

A boolean that is true by default, but turns false after an 'error'\noccurred, the stream came to an 'end', or destroy() was called.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "stream.setEncoding(encoding)", + "type": "method", + "name": "setEncoding", + "desc": "

Makes the data event emit a string instead of a Buffer. encoding can be\n'utf8', 'ascii', or 'base64'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding" + } + ] + } + ] + }, + { + "textRaw": "stream.pause()", + "type": "method", + "name": "pause", + "desc": "

Pauses the incoming 'data' events.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "stream.resume()", + "type": "method", + "name": "resume", + "desc": "

Resumes the incoming 'data' events after a pause().\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "stream.destroy()", + "type": "method", + "name": "destroy", + "desc": "

Closes the underlying file descriptor. Stream will not emit any more events.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "stream.pipe(destination, [options])", + "type": "method", + "name": "pipe", + "desc": "

This is a Stream.prototype method available on all Streams.\n\n

\n

Connects this read stream to destination WriteStream. Incoming\ndata on this stream gets written to destination. The destination and source\nstreams are kept in sync by pausing and resuming as necessary.\n\n

\n

This function returns the destination stream.\n\n

\n

Emulating the Unix cat command:\n\n

\n
process.stdin.resume();\nprocess.stdin.pipe(process.stdout);
\n

By default end() is called on the destination when the source stream emits\nend, so that destination is no longer writable. Pass { end: false } as\noptions to keep the destination stream open.\n\n

\n

This keeps process.stdout open so that "Goodbye" can be written at the end.\n\n

\n
process.stdin.resume();\n\nprocess.stdin.pipe(process.stdout, { end: false });\n\nprocess.stdin.on("end", function() {\n  process.stdout.write("Goodbye\\n");\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "destination" + }, + { + "name": "options", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Writable Stream", + "name": "Writable Stream", + "type": "class", + "desc": "

A Writable Stream has the following methods, members, and events.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'drain'", + "type": "event", + "name": "drain", + "desc": "

function () { }\n\n

\n

After a write() method returned false, this event is emitted to\nindicate that it is safe to write again.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "desc": "

function (exception) { }\n\n

\n

Emitted on error with the exception exception.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () { }\n\n

\n

Emitted when the underlying file descriptor has been closed.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'pipe'", + "type": "event", + "name": "pipe", + "desc": "

function (src) { }\n\n

\n

Emitted when the stream is passed to a readable stream's pipe method.\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "stream.writable", + "name": "writable", + "desc": "

A boolean that is true by default, but turns false after an 'error'\noccurred or end() / destroy() was called.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "stream.write(string, [encoding], [fd])", + "type": "method", + "name": "write", + "desc": "

Writes string with the given encoding to the stream. Returns true if\nthe string has been flushed to the kernel buffer. Returns false to\nindicate that the kernel buffer is full, and the data will be sent out in\nthe future. The 'drain' event will indicate when the kernel buffer is\nempty again. The encoding defaults to 'utf8'.\n\n

\n

If the optional fd parameter is specified, it is interpreted as an integral\nfile descriptor to be sent over the stream. This is only supported for UNIX\nstreams, and is silently ignored otherwise. When writing a file descriptor in\nthis manner, closing the descriptor before the stream drains risks sending an\ninvalid (closed) FD.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "string" + }, + { + "name": "encoding", + "optional": true + }, + { + "name": "fd", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "stream.write(buffer)", + "type": "method", + "name": "write", + "desc": "

Same as the above except with a raw buffer.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buffer" + } + ] + } + ] + }, + { + "textRaw": "stream.end()", + "type": "method", + "name": "end", + "desc": "

Terminates the stream with EOF or FIN.\nThis call will allow queued write data to be sent before closing the stream.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "stream.end(string, encoding)", + "type": "method", + "name": "end", + "desc": "

Sends string with the given encoding and terminates the stream with EOF\nor FIN. This is useful to reduce the number of packets sent.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "string" + }, + { + "name": "encoding" + } + ] + } + ] + }, + { + "textRaw": "stream.end(buffer)", + "type": "method", + "name": "end", + "desc": "

Same as above but with a buffer.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buffer" + } + ] + } + ] + }, + { + "textRaw": "stream.destroy()", + "type": "method", + "name": "destroy", + "desc": "

Closes the underlying file descriptor. Stream will not emit any more events.\nAny queued write data will not be sent.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "stream.destroySoon()", + "type": "method", + "name": "destroySoon", + "desc": "

After the write queue is drained, close the file descriptor. destroySoon()\ncan still destroy straight away, as long as there is no data left in the queue\nfor writes.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + } + ], + "type": "module", + "displayName": "Stream" + }, + { + "textRaw": "Crypto", + "name": "crypto", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Use require('crypto') to access this module.\n\n

\n

The crypto module requires OpenSSL to be available on the underlying platform.\nIt offers a way of encapsulating secure credentials to be used as part\nof a secure HTTPS net or http connection.\n\n

\n

It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods.\n\n

\n", + "methods": [ + { + "textRaw": "crypto.createCredentials(details)", + "type": "method", + "name": "createCredentials", + "desc": "

Creates a credentials object, with the optional details being a dictionary with keys:\n\n

\n
    \n
  • pfx : A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
    • \n
  • key : a string holding the PEM encoded private key
    • \n
  • cert : a string holding the PEM encoded certificate
    • \n
  • passphrase : A string of passphrase for the private key or pfx
    • \n
  • ca : either a string or list of strings of PEM encoded CA certificates to trust.
    • \n
  • ciphers: a string describing the ciphers to use or exclude. Consult\nhttp://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details\non the format.
    • \n
\n

If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in\n

\n

http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "details" + } + ] + } + ] + }, + { + "textRaw": "crypto.createHash(algorithm)", + "type": "method", + "name": "createHash", + "desc": "

Creates and returns a hash object, a cryptographic hash with the given algorithm\nwhich can be used to generate hash digests.\n\n

\n

algorithm is dependent on the available algorithms supported by the version\nof OpenSSL on the platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', etc.\nOn recent releases, openssl list-message-digest-algorithms will display the available digest algorithms.\n\n

\n

Example: this program that takes the sha1 sum of a file\n\n

\n
var filename = process.argv[2];\nvar crypto = require('crypto');\nvar fs = require('fs');\n\nvar shasum = crypto.createHash('sha1');\n\nvar s = fs.ReadStream(filename);\ns.on('data', function(d) {\n  shasum.update(d);\n});\n\ns.on('end', function() {\n  var d = shasum.digest('hex');\n  console.log(d + '  ' + filename);\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + } + ] + } + ] + }, + { + "textRaw": "crypto.createHmac(algorithm, key)", + "type": "method", + "name": "createHmac", + "desc": "

Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key.\n\n

\n

algorithm is dependent on the available algorithms supported by OpenSSL - see createHash above.\nkey is the hmac key to be used.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + }, + { + "name": "key" + } + ] + } + ] + }, + { + "textRaw": "crypto.createCipher(algorithm, password)", + "type": "method", + "name": "createCipher", + "desc": "

Creates and returns a cipher object, with the given algorithm and password.\n\n

\n

algorithm is dependent on OpenSSL, examples are 'aes192', etc.\nOn recent releases, openssl list-cipher-algorithms will display the\navailable cipher algorithms.\npassword is used to derive key and IV, which must be 'binary' encoded\nstring (See the Buffer section for more information).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + }, + { + "name": "password" + } + ] + } + ] + }, + { + "textRaw": "crypto.createCipheriv(algorithm, key, iv)", + "type": "method", + "name": "createCipheriv", + "desc": "

Creates and returns a cipher object, with the given algorithm, key and iv.\n\n

\n

algorithm is the same as the createCipher(). key is a raw key used in\nalgorithm. iv is an Initialization vector. key and iv must be 'binary'\nencoded string (See the Buffer section for more information).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + }, + { + "name": "key" + }, + { + "name": "iv" + } + ] + } + ] + }, + { + "textRaw": "crypto.createDecipher(algorithm, password)", + "type": "method", + "name": "createDecipher", + "desc": "

Creates and returns a decipher object, with the given algorithm and key.\nThis is the mirror of the createCipher() above.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + }, + { + "name": "password" + } + ] + } + ] + }, + { + "textRaw": "crypto.createDecipheriv(algorithm, key, iv)", + "type": "method", + "name": "createDecipheriv", + "desc": "

Creates and returns a decipher object, with the given algorithm, key and iv.\nThis is the mirror of the createCipheriv() above.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + }, + { + "name": "key" + }, + { + "name": "iv" + } + ] + } + ] + }, + { + "textRaw": "crypto.createSign(algorithm)", + "type": "method", + "name": "createSign", + "desc": "

Creates and returns a signing object, with the given algorithm.\nOn recent OpenSSL releases, openssl list-public-key-algorithms will display\nthe available signing algorithms. Examples are 'RSA-SHA256'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + } + ] + } + ] + }, + { + "textRaw": "crypto.createVerify(algorithm)", + "type": "method", + "name": "createVerify", + "desc": "

Creates and returns a verification object, with the given algorithm.\nThis is the mirror of the signing object above.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + } + ] + } + ] + }, + { + "textRaw": "crypto.createDiffieHellman(prime_length)", + "type": "method", + "name": "createDiffieHellman", + "desc": "

Creates a Diffie-Hellman key exchange object and generates a prime of the\ngiven bit length. The generator used is 2.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "prime_length" + } + ] + } + ] + }, + { + "textRaw": "crypto.createDiffieHellman(prime, [encoding])", + "type": "method", + "name": "createDiffieHellman", + "desc": "

Creates a Diffie-Hellman key exchange object using the supplied prime. The\ngenerator used is 2. Encoding can be 'binary', 'hex', or 'base64'.\nDefaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "prime" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "crypto.pbkdf2(password, salt, iterations, keylen, callback)", + "type": "method", + "name": "pbkdf2", + "desc": "

Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive\na key of given length from the given password, salt and iterations.\nThe callback gets two arguments (err, derivedKey).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "password" + }, + { + "name": "salt" + }, + { + "name": "iterations" + }, + { + "name": "keylen" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "crypto.randomBytes(size, [callback])", + "type": "method", + "name": "randomBytes", + "desc": "

Generates cryptographically strong pseudo-random data. Usage:\n\n

\n
// async\ncrypto.randomBytes(256, function(ex, buf) {\n  if (ex) throw ex;\n  console.log('Have %d bytes of random data: %s', buf.length, buf);\n});\n\n// sync\ntry {\n  var buf = crypto.randomBytes(256);\n  console.log('Have %d bytes of random data: %s', buf.length, buf);\n} catch (ex) {\n  // handle error\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "size" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: Hash", + "type": "class", + "name": "Hash", + "desc": "

The class for creating hash digests of data.\n\n

\n

Returned by crypto.createHash.\n\n

\n", + "methods": [ + { + "textRaw": "hash.update(data, [input_encoding])", + "type": "method", + "name": "update", + "desc": "

Updates the hash content with the given data, the encoding of which is given\nin input_encoding and can be 'utf8', 'ascii' or 'binary'.\nDefaults to 'binary'.\nThis can be called many times with new data as it is streamed.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + }, + { + "name": "input_encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "hash.digest([encoding])", + "type": "method", + "name": "digest", + "desc": "

Calculates the digest of all of the passed data to be hashed.\nThe encoding can be 'hex', 'binary' or 'base64'.\nDefaults to 'binary'.\n\n

\n

Note: hash object can not be used after digest() method been called.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: Hmac", + "type": "class", + "name": "Hmac", + "desc": "

Class for creating cryptographic hmac content.\n\n

\n

Returned by crypto.createHmac.\n\n

\n", + "methods": [ + { + "textRaw": "hmac.update(data)", + "type": "method", + "name": "update", + "desc": "

Update the hmac content with the given data.\nThis can be called many times with new data as it is streamed.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + } + ] + } + ] + }, + { + "textRaw": "hmac.digest([encoding])", + "type": "method", + "name": "digest", + "desc": "

Calculates the digest of all of the passed data to the hmac.\nThe encoding can be 'hex', 'binary' or 'base64'.\nDefaults to 'binary'.\n\n

\n

Note: hmac object can not be used after digest() method been called.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: Cipher", + "type": "class", + "name": "Cipher", + "desc": "

Class for encrypting data.\n\n

\n

Returned by crypto.createCipher and crypto.createCipheriv.\n\n

\n", + "methods": [ + { + "textRaw": "cipher.update(data, [input_encoding], [output_encoding])", + "type": "method", + "name": "update", + "desc": "

Updates the cipher with data, the encoding of which is given in\ninput_encoding and can be 'utf8', 'ascii' or 'binary'.\nDefaults to 'binary'.\n\n

\n

The output_encoding specifies the output format of the enciphered data,\nand can be 'binary', 'base64' or 'hex'. Defaults to 'binary'.\n\n

\n

Returns the enciphered contents, and can be called many times with new data as it is streamed.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + }, + { + "name": "input_encoding", + "optional": true + }, + { + "name": "output_encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "cipher.final([output_encoding])", + "type": "method", + "name": "final", + "desc": "

Returns any remaining enciphered contents, with output_encoding being one of:\n'binary', 'base64' or 'hex'. Defaults to 'binary'.\n\n

\n

Note: cipher object can not be used after final() method been called.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "output_encoding", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: Decipher", + "type": "class", + "name": "Decipher", + "desc": "

Class for decrypting data.\n\n

\n

Returned by crypto.createDecipher and crypto.createDecipheriv.\n\n

\n", + "methods": [ + { + "textRaw": "decipher.update(data, [input_encoding], [output_encoding])", + "type": "method", + "name": "update", + "desc": "

Updates the decipher with data, which is encoded in 'binary', 'base64'\nor 'hex'. Defaults to 'binary'.\n\n

\n

The output_decoding specifies in what format to return the deciphered\nplaintext: 'binary', 'ascii' or 'utf8'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + }, + { + "name": "input_encoding", + "optional": true + }, + { + "name": "output_encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "decipher.final([output_encoding])", + "type": "method", + "name": "final", + "desc": "

Returns any remaining plaintext which is deciphered,\nwith output_encoding being one of: 'binary', 'ascii' or 'utf8'.\nDefaults to 'binary'.\n\n

\n

Note: decipher object can not be used after final() method been called.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "output_encoding", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: Signer", + "type": "class", + "name": "Signer", + "desc": "

Class for generating signatures.\n\n

\n

Returned by crypto.createSign.\n\n

\n", + "methods": [ + { + "textRaw": "signer.update(data)", + "type": "method", + "name": "update", + "desc": "

Updates the signer object with data.\nThis can be called many times with new data as it is streamed.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + } + ] + } + ] + }, + { + "textRaw": "signer.sign(private_key, [output_format])", + "type": "method", + "name": "sign", + "desc": "

Calculates the signature on all the updated data passed through the signer.\nprivate_key is a string containing the PEM encoded private key for signing.\n\n

\n

Returns the signature in output_format which can be 'binary', 'hex' or\n'base64'. Defaults to 'binary'.\n\n

\n

Note: signer object can not be used after sign() method been called.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "private_key" + }, + { + "name": "output_format", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: Verify", + "type": "class", + "name": "Verify", + "desc": "

Class for verifying signatures.\n\n

\n

Returned by crypto.createVerify.\n\n

\n", + "methods": [ + { + "textRaw": "verifier.update(data)", + "type": "method", + "name": "update", + "desc": "

Updates the verifier object with data.\nThis can be called many times with new data as it is streamed.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + } + ] + } + ] + }, + { + "textRaw": "verifier.verify(object, signature, [signature_format])", + "type": "method", + "name": "verify", + "desc": "

Verifies the signed data by using the object and signature. object is a\nstring containing a PEM encoded object, which can be one of RSA public key,\nDSA public key, or X.509 certificate. signature is the previously calculated\nsignature for the data, in the signature_format which can be 'binary',\n'hex' or 'base64'. Defaults to 'binary'.\n\n

\n

Returns true or false depending on the validity of the signature for the data and public key.\n\n

\n

Note: verifier object can not be used after verify() method been called.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "object" + }, + { + "name": "signature" + }, + { + "name": "signature_format", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: DiffieHellman", + "type": "class", + "name": "DiffieHellman", + "desc": "

The class for creating Diffie-Hellman key exchanges.\n\n

\n

Returned by crypto.createDiffieHellman.\n\n

\n", + "methods": [ + { + "textRaw": "diffieHellman.generateKeys([encoding])", + "type": "method", + "name": "generateKeys", + "desc": "

Generates private and public Diffie-Hellman key values, and returns the\npublic key in the specified encoding. This key should be transferred to the\nother party. Encoding can be 'binary', 'hex', or 'base64'.\nDefaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])", + "type": "method", + "name": "computeSecret", + "desc": "

Computes the shared secret using other_public_key as the other party's\npublic key and returns the computed shared secret. Supplied key is\ninterpreted using specified input_encoding, and secret is encoded using\nspecified output_encoding. Encodings can be 'binary', 'hex', or\n'base64'. The input encoding defaults to 'binary'.\nIf no output encoding is given, the input encoding is used as output encoding.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "other_public_key" + }, + { + "name": "input_encoding", + "optional": true + }, + { + "name": "output_encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.getPrime([encoding])", + "type": "method", + "name": "getPrime", + "desc": "

Returns the Diffie-Hellman prime in the specified encoding, which can be\n'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.getGenerator([encoding])", + "type": "method", + "name": "getGenerator", + "desc": "

Returns the Diffie-Hellman prime in the specified encoding, which can be\n'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.getPublicKey([encoding])", + "type": "method", + "name": "getPublicKey", + "desc": "

Returns the Diffie-Hellman public key in the specified encoding, which can\nbe 'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.getPrivateKey([encoding])", + "type": "method", + "name": "getPrivateKey", + "desc": "

Returns the Diffie-Hellman private key in the specified encoding, which can\nbe 'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.setPublicKey(public_key, [encoding])", + "type": "method", + "name": "setPublicKey", + "desc": "

Sets the Diffie-Hellman public key. Key encoding can be 'binary', 'hex',\nor 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "public_key" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.setPrivateKey(public_key, [encoding])", + "type": "method", + "name": "setPrivateKey", + "desc": "

Sets the Diffie-Hellman private key. Key encoding can be 'binary', 'hex',\nor 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "public_key" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + } + ] + } + ], + "type": "module", + "displayName": "Crypto" + }, + { + "textRaw": "TLS (SSL)", + "name": "tls_(ssl)", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Use require('tls') to access this module.\n\n

\n

The tls module uses OpenSSL to provide Transport Layer Security and/or\nSecure Socket Layer: encrypted stream communication.\n\n

\n

TLS/SSL is a public/private key infrastructure. Each client and each\nserver must have a private key. A private key is created like this\n\n

\n
openssl genrsa -out ryans-key.pem 1024
\n

All severs and some clients need to have a certificate. Certificates are public\nkeys signed by a Certificate Authority or self-signed. The first step to\ngetting a certificate is to create a "Certificate Signing Request" (CSR)\nfile. This is done with:\n\n

\n
openssl req -new -key ryans-key.pem -out ryans-csr.pem
\n

To create a self-signed certificate with the CSR, do this:\n\n

\n
openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem
\n

Alternatively you can send the CSR to a Certificate Authority for signing.\n\n

\n

(TODO: docs on creating a CA, for now interested users should just look at\ntest/fixtures/keys/Makefile in the Node source code)\n\n

\n

To create .pfx or .p12, do this:\n\n

\n
openssl pkcs12 -export -in agent5-cert.pem -inkey agent5-key.pem \\\n    -certfile ca-cert.pem -out agent5.pfx
\n
    \n
  • in: certificate
    • \n
  • inkey: private key
    • \n
  • certfile: all CA certs concatenated in one file like\ncat ca1-cert.pem ca2-cert.pem > ca-cert.pem
    • \n
\n", + "miscs": [ + { + "textRaw": "Client-initiated renegotiation attack mitigation", + "name": "Client-initiated renegotiation attack mitigation", + "type": "misc", + "desc": "

The TLS protocol lets the client renegotiate certain aspects of the TLS session.\nUnfortunately, session renegotiation requires a disproportional amount of\nserver-side resources, which makes it a potential vector for denial-of-service\nattacks.\n\n

\n

To mitigate this, renegotiations are limited to three times every 10 minutes. An\nerror is emitted on the CleartextStream instance when\nthe threshold is exceeded. The limits are configurable:\n\n

\n
    \n

  • tls.CLIENT_RENEG_LIMIT: renegotiation limit, default is 3.

    \n
    • \n

  • tls.CLIENT_RENEG_WINDOW: renegotiation window in seconds, default is

    \n
                           10 minutes.
    \n
    • \n
\n

Don't change the defaults unless you know what you are doing.\n\n

\n

To test your server, connect to it with openssl s_client -connect address:port\nand tap R<CR> (that's the letter R followed by a carriage return) a few\ntimes.\n\n\n

\n" + }, + { + "textRaw": "NPN and SNI", + "name": "NPN and SNI", + "type": "misc", + "desc": "

NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS\nhandshake extensions allowing you:\n\n

\n
    \n
  • NPN - to use one TLS server for multiple protocols (HTTP, SPDY)
    • \n
  • SNI - to use one TLS server for multiple hostnames with different SSL\ncertificates.
    • \n
\n" + } + ], + "methods": [ + { + "textRaw": "tls.createServer(options, [secureConnectionListener])", + "type": "method", + "name": "createServer", + "desc": "

Creates a new tls.Server.\nThe connectionListener argument is automatically set as a listener for the\nsecureConnection event.\nThe options object has these possibilities:\n\n

\n
    \n

  • pfx: A string or Buffer containing the private key, certificate and\nCA certs of the server in PFX or PKCS12 format. (Mutually exclusive with\nthe key, cert and ca options.)

    \n
    • \n

  • key: A string or Buffer containing the private key of the server in\nPEM format. (Required)

    \n
    • \n

  • passphrase: A string of passphrase for the private key or pfx.

    \n
    • \n

  • cert: A string or Buffer containing the certificate key of the server in\nPEM format. (Required)

    \n
    • \n

  • ca: An array of strings or Buffers of trusted certificates. If this is\nomitted several well known "root" CAs will be used, like VeriSign.\nThese are used to authorize connections.

    \n
    • \n

  • ciphers: A string describing the ciphers to use or exclude. Consult\nhttp://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for\ndetails on the format.

    \n
    • \n

  • requestCert: If true the server will request a certificate from\nclients that connect and attempt to verify that certificate. Default:\nfalse.

    \n
    • \n

  • rejectUnauthorized: If true the server will reject any connection\nwhich is not authorized with the list of supplied CAs. This option only\nhas an effect if requestCert is true. Default: false.

    \n
    • \n

  • NPNProtocols: An array or Buffer of possible NPN protocols. (Protocols\nshould be ordered by their priority).

    \n
    • \n

  • SNICallback: A function that will be called if client supports SNI TLS\nextension. Only one argument will be passed to it: servername. And\nSNICallback should return SecureContext instance.\n(You can use crypto.createCredentials(...).context to get proper\nSecureContext). If SNICallback wasn't provided - default callback with\nhigh-level API will be used (see below).

    \n
    • \n

  • sessionIdContext: A string containing a opaque identifier for session\nresumption. If requestCert is true, the default is MD5 hash value\ngenerated from command-line. Otherwise, the default is not provided.

    \n
    • \n
\n

Here is a simple example echo server:\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  key: fs.readFileSync('server-key.pem'),\n  cert: fs.readFileSync('server-cert.pem'),\n\n  // This is necessary only if using the client certificate authentication.\n  requestCert: true,\n\n  // This is necessary only if the client uses the self-signed certificate.\n  ca: [ fs.readFileSync('client-cert.pem') ]\n};\n\nvar server = tls.createServer(options, function(cleartextStream) {\n  console.log('server connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  cleartextStream.write("welcome!\\n");\n  cleartextStream.setEncoding('utf8');\n  cleartextStream.pipe(cleartextStream);\n});\nserver.listen(8000, function() {\n  console.log('server bound');\n});
\n

Or\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('server.pfx'),\n\n  // This is necessary only if using the client certificate authentication.\n  requestCert: true,\n\n};\n\nvar server = tls.createServer(options, function(cleartextStream) {\n  console.log('server connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  cleartextStream.write("welcome!\\n");\n  cleartextStream.setEncoding('utf8');\n  cleartextStream.pipe(cleartextStream);\n});\nserver.listen(8000, function() {\n  console.log('server bound');\n});
\n

You can test this server by connecting to it with openssl s_client:\n\n\n

\n
openssl s_client -connect 127.0.0.1:8000
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "secureConnectionListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "tls.connect(port, [host], [options], [secureConnectListener])", + "type": "method", + "name": "connect", + "desc": "

Creates a new client connection to the given port and host. (If host\ndefaults to localhost.) options should be an object which specifies\n\n

\n
    \n

  • pfx: A string or Buffer containing the private key, certificate and\nCA certs of the server in PFX or PKCS12 format.

    \n
    • \n

  • key: A string or Buffer containing the private key of the client in\nPEM format.

    \n
    • \n

  • passphrase: A string of passphrase for the private key or pfx.

    \n
    • \n

  • cert: A string or Buffer containing the certificate key of the client in\nPEM format.

    \n
    • \n

  • ca: An array of strings or Buffers of trusted certificates. If this is\nomitted several well known "root" CAs will be used, like VeriSign.\nThese are used to authorize connections.

    \n
    • \n

  • NPNProtocols: An array of string or Buffer containing supported NPN\nprotocols. Buffer should have following format: 0x05hello0x05world,\nwhere first byte is next protocol name's length. (Passing array should\nusually be much simpler: ['hello', 'world'].)

    \n
    • \n

  • servername: Servername for SNI (Server Name Indication) TLS extension.

    \n
    • \n

  • socket: Establish secure connection on a given socket rather than\ncreating a new socket. If this option is specified, host and port\nare ignored. This is intended FOR INTERNAL USE ONLY. As with all\nundocumented APIs in Node, they should not be used.

    \n
    • \n
\n

The secureConnectListener parameter will be added as a listener for the\n'secureConnect' event.\n\n

\n

tls.connect() returns a CleartextStream object.\n\n

\n

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

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  // These are necessary only if using the client certificate authentication\n  key: fs.readFileSync('client-key.pem'),\n  cert: fs.readFileSync('client-cert.pem'),\n\n  // This is necessary only if the server uses the self-signed certificate\n  ca: [ fs.readFileSync('server-cert.pem') ]\n};\n\nvar cleartextStream = tls.connect(8000, options, function() {\n  console.log('client connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  process.stdin.pipe(cleartextStream);\n  process.stdin.resume();\n});\ncleartextStream.setEncoding('utf8');\ncleartextStream.on('data', function(data) {\n  console.log(data);\n});\ncleartextStream.on('end', function() {\n  server.close();\n});
\n

Or\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('client.pfx')\n};\n\nvar cleartextStream = tls.connect(8000, options, function() {\n  console.log('client connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  process.stdin.pipe(cleartextStream);\n  process.stdin.resume();\n});\ncleartextStream.setEncoding('utf8');\ncleartextStream.on('data', function(data) {\n  console.log(data);\n});\ncleartextStream.on('end', function() {\n  server.close();\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "port" + }, + { + "name": "host", + "optional": true + }, + { + "name": "options", + "optional": true + }, + { + "name": "secureConnectListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])", + "type": "method", + "name": "createSecurePair", + "desc": "

Creates a new secure pair object with two streams, one of which reads/writes\nencrypted data, and one reads/writes cleartext data.\nGenerally the encrypted one is piped to/from an incoming encrypted data stream,\nand the cleartext one is used as a replacement for the initial encrypted stream.\n\n

\n
    \n

  • credentials: A credentials object from crypto.createCredentials( ... )

    \n
    • \n

  • isServer: A boolean indicating whether this tls connection should be\nopened as a server or a client.

    \n
    • \n

  • requestCert: A boolean indicating whether a server should request a\ncertificate from a connecting client. Only applies to server connections.

    \n
    • \n

  • rejectUnauthorized: A boolean indicating whether a server should\nautomatically reject clients with invalid certificates. Only applies to\nservers with requestCert enabled.

    \n
    • \n
\n

tls.createSecurePair() returns a SecurePair object with\ncleartext and encrypted stream properties.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "credentials", + "optional": true + }, + { + "name": "isServer", + "optional": true + }, + { + "name": "requestCert", + "optional": true + }, + { + "name": "rejectUnauthorized", + "optional": true + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: SecurePair", + "type": "class", + "name": "SecurePair", + "desc": "

Returned by tls.createSecurePair.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'secure'", + "type": "event", + "name": "secure", + "desc": "

The event is emitted from the SecurePair once the pair has successfully\nestablished a secure connection.\n\n

\n

Similarly to the checking for the server 'secureConnection' event,\npair.cleartext.authorized should be checked to confirm whether the certificate\nused properly authorized.\n\n

\n", + "params": [] + } + ] + }, + { + "textRaw": "Class: tls.Server", + "type": "class", + "name": "tls.Server", + "desc": "

This class is a subclass of net.Server and has the same methods on it.\nInstead of accepting just raw TCP connections, this accepts encrypted\nconnections using TLS or SSL.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'secureConnection'", + "type": "event", + "name": "secureConnection", + "desc": "

function (cleartextStream) {}\n\n

\n

This event is emitted after a new connection has been successfully\nhandshaked. The argument is a instance of\nCleartextStream. It has all the common stream methods\nand events.\n\n

\n

cleartextStream.authorized is a boolean value which indicates if the\nclient has verified by one of the supplied certificate authorities for the\nserver. If cleartextStream.authorized is false, then\ncleartextStream.authorizationError is set to describe how authorization\nfailed. Implied but worth mentioning: depending on the settings of the TLS\nserver, you unauthorized connections may be accepted.\ncleartextStream.npnProtocol is a string containing selected NPN protocol.\ncleartextStream.servername is a string containing servername requested with\nSNI.\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'clientError'", + "type": "event", + "name": "clientError", + "desc": "

function (exception) { }\n\n

\n

When a client connection emits an 'error' event before secure connection is\nestablished - it will be forwarded here.\n\n\n

\n", + "params": [] + } + ], + "methods": [ + { + "textRaw": "server.listen(port, [host], [callback])", + "type": "method", + "name": "listen", + "desc": "

Begin accepting connections on the specified port and host. If the\nhost is omitted, the server will accept connections directed to any\nIPv4 address (INADDR_ANY).\n\n

\n

This function is asynchronous. The last parameter callback will be called\nwhen the server has been bound.\n\n

\n

See net.Server for more information.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "port" + }, + { + "name": "host", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "server.close()", + "type": "method", + "name": "close", + "desc": "

Stops the server from accepting new connections. This function is\nasynchronous, the server is finally closed when the server emits a 'close'\nevent.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "server.address()", + "type": "method", + "name": "address", + "desc": "

Returns the bound address and port of the server as reported by the operating\nsystem.\nSee net.Server.address() for more information.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "server.addContext(hostname, credentials)", + "type": "method", + "name": "addContext", + "desc": "

Add secure context that will be used if client request's SNI hostname is\nmatching passed hostname (wildcards can be used). credentials can contain\nkey, cert and ca.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "hostname" + }, + { + "name": "credentials" + } + ] + } + ] + } + ], + "properties": [ + { + "textRaw": "server.maxConnections", + "name": "maxConnections", + "desc": "

Set this property to reject connections when the server's connection count\ngets high.\n\n

\n" + }, + { + "textRaw": "server.connections", + "name": "connections", + "desc": "

The number of concurrent connections on the server.\n\n\n

\n" + } + ] + }, + { + "textRaw": "Class: tls.CleartextStream", + "type": "class", + "name": "tls.CleartextStream", + "desc": "

This is a stream on top of the Encrypted stream that makes it possible to\nread/write an encrypted data as a cleartext data.\n\n

\n

This instance implements a duplex Stream interfaces.\nIt has all the common stream methods and events.\n\n

\n

A ClearTextStream is the clear member of a SecurePair object.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'secureConnect'", + "type": "event", + "name": "secureConnect", + "desc": "

This event is emitted after a new connection has been successfully handshaked. \nThe listener will be called no matter if the server's certificate was\nauthorized or not. It is up to the user to test cleartextStream.authorized\nto see if the server certificate was signed by one of the specified CAs.\nIf cleartextStream.authorized === false then the error can be found in\ncleartextStream.authorizationError. Also if NPN was used - you can check\ncleartextStream.npnProtocol for negotiated protocol.\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "cleartextStream.authorized", + "name": "authorized", + "desc": "

A boolean that is true if the peer certificate was signed by one of the\nspecified CAs, otherwise false\n\n

\n" + }, + { + "textRaw": "cleartextStream.authorizationError", + "name": "authorizationError", + "desc": "

The reason why the peer's certificate has not been verified. This property\nbecomes available only when cleartextStream.authorized === false.\n\n

\n" + }, + { + "textRaw": "cleartextStream.remoteAddress", + "name": "remoteAddress", + "desc": "

The string representation of the remote IP address. For example,\n'74.125.127.100' or '2001:4860:a005::68'.\n\n

\n" + }, + { + "textRaw": "cleartextStream.remotePort", + "name": "remotePort", + "desc": "

The numeric representation of the remote port. For example, 443.\n\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "cleartextStream.getPeerCertificate()", + "type": "method", + "name": "getPeerCertificate", + "desc": "

Returns an object representing the peer's certificate. The returned object has\nsome properties corresponding to the field of the certificate.\n\n

\n

Example:\n\n

\n
{ subject: \n   { C: 'UK',\n     ST: 'Acknack Ltd',\n     L: 'Rhys Jones',\n     O: 'node.js',\n     OU: 'Test TLS Certificate',\n     CN: 'localhost' },\n  issuer: \n   { C: 'UK',\n     ST: 'Acknack Ltd',\n     L: 'Rhys Jones',\n     O: 'node.js',\n     OU: 'Test TLS Certificate',\n     CN: 'localhost' },\n  valid_from: 'Nov 11 09:52:22 2009 GMT',\n  valid_to: 'Nov  6 09:52:22 2029 GMT',\n  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF' }
\n

If the peer does not provide a certificate, it returns null or an empty\nobject.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "cleartextStream.address()", + "type": "method", + "name": "address", + "desc": "

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

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + } + ], + "type": "module", + "displayName": "TLS (SSL)" + }, + { + "textRaw": "File System", + "name": "fs", + "stability": 3, + "stabilityText": "Stable", + "desc": "

File I/O is provided by simple wrappers around standard POSIX functions. To\nuse this module do require('fs'). All the methods have asynchronous and\nsynchronous forms.\n\n

\n

The asynchronous form always take a completion callback as its last argument.\nThe arguments passed to the completion callback depend on the method, but the\nfirst argument is always reserved for an exception. If the operation was\ncompleted successfully, then the first argument will be null or undefined.\n\n

\n

When using the synchronous form any exceptions are immediately thrown.\nYou can use try/catch to handle exceptions or allow them to bubble up.\n\n

\n

Here is an example of the asynchronous version:\n\n

\n
var fs = require('fs');\n\nfs.unlink('/tmp/hello', function (err) {\n  if (err) throw err;\n  console.log('successfully deleted /tmp/hello');\n});
\n

Here is the synchronous version:\n\n

\n
var fs = require('fs');\n\nfs.unlinkSync('/tmp/hello')\nconsole.log('successfully deleted /tmp/hello');
\n

With the asynchronous methods there is no guaranteed ordering. So the\nfollowing is prone to error:\n\n

\n
fs.rename('/tmp/hello', '/tmp/world', function (err) {\n  if (err) throw err;\n  console.log('renamed complete');\n});\nfs.stat('/tmp/world', function (err, stats) {\n  if (err) throw err;\n  console.log('stats: ' + JSON.stringify(stats));\n});
\n

It could be that fs.stat is executed before fs.rename.\nThe correct way to do this is to chain the callbacks.\n\n

\n
fs.rename('/tmp/hello', '/tmp/world', function (err) {\n  if (err) throw err;\n  fs.stat('/tmp/world', function (err, stats) {\n    if (err) throw err;\n    console.log('stats: ' + JSON.stringify(stats));\n  });\n});
\n

In busy processes, the programmer is strongly encouraged to use the\nasynchronous versions of these calls. The synchronous versions will block\nthe entire process until they complete--halting all connections.\n\n

\n

Relative path to filename can be used, remember however that this path will be relative\nto process.cwd().\n\n

\n", + "methods": [ + { + "textRaw": "fs.rename(path1, path2, [callback])", + "type": "method", + "name": "rename", + "desc": "

Asynchronous rename(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path1" + }, + { + "name": "path2" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.renameSync(path1, path2)", + "type": "method", + "name": "renameSync", + "desc": "

Synchronous rename(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path1" + }, + { + "name": "path2" + } + ] + } + ] + }, + { + "textRaw": "fs.truncate(fd, len, [callback])", + "type": "method", + "name": "truncate", + "desc": "

Asynchronous ftruncate(2). No arguments other than a possible exception are\ngiven to the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "len" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.truncateSync(fd, len)", + "type": "method", + "name": "truncateSync", + "desc": "

Synchronous ftruncate(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "len" + } + ] + } + ] + }, + { + "textRaw": "fs.chown(path, uid, gid, [callback])", + "type": "method", + "name": "chown", + "desc": "

Asynchronous chown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "uid" + }, + { + "name": "gid" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.chownSync(path, uid, gid)", + "type": "method", + "name": "chownSync", + "desc": "

Synchronous chown(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "uid" + }, + { + "name": "gid" + } + ] + } + ] + }, + { + "textRaw": "fs.fchown(fd, uid, gid, [callback])", + "type": "method", + "name": "fchown", + "desc": "

Asynchronous fchown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "uid" + }, + { + "name": "gid" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.fchownSync(fd, uid, gid)", + "type": "method", + "name": "fchownSync", + "desc": "

Synchronous fchown(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "uid" + }, + { + "name": "gid" + } + ] + } + ] + }, + { + "textRaw": "fs.lchown(path, uid, gid, [callback])", + "type": "method", + "name": "lchown", + "desc": "

Asynchronous lchown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "uid" + }, + { + "name": "gid" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.lchownSync(path, uid, gid)", + "type": "method", + "name": "lchownSync", + "desc": "

Synchronous lchown(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "uid" + }, + { + "name": "gid" + } + ] + } + ] + }, + { + "textRaw": "fs.chmod(path, mode, [callback])", + "type": "method", + "name": "chmod", + "desc": "

Asynchronous chmod(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.chmodSync(path, mode)", + "type": "method", + "name": "chmodSync", + "desc": "

Synchronous chmod(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode" + } + ] + } + ] + }, + { + "textRaw": "fs.fchmod(fd, mode, [callback])", + "type": "method", + "name": "fchmod", + "desc": "

Asynchronous fchmod(2). No arguments other than a possible exception\nare given to the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "mode" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.fchmodSync(fd, mode)", + "type": "method", + "name": "fchmodSync", + "desc": "

Synchronous fchmod(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "mode" + } + ] + } + ] + }, + { + "textRaw": "fs.lchmod(path, mode, [callback])", + "type": "method", + "name": "lchmod", + "desc": "

Asynchronous lchmod(2). No arguments other than a possible exception\nare given to the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.lchmodSync(path, mode)", + "type": "method", + "name": "lchmodSync", + "desc": "

Synchronous lchmod(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode" + } + ] + } + ] + }, + { + "textRaw": "fs.stat(path, [callback])", + "type": "method", + "name": "stat", + "desc": "

Asynchronous stat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. See the fs.Stats\nsection below for more information.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.lstat(path, [callback])", + "type": "method", + "name": "lstat", + "desc": "

Asynchronous lstat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. lstat() is identical to stat(), except that if\npath is a symbolic link, then the link itself is stat-ed, not the file that it\nrefers to.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.fstat(fd, [callback])", + "type": "method", + "name": "fstat", + "desc": "

Asynchronous fstat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. fstat() is identical to stat(), except that\nthe file to be stat-ed is specified by the file descriptor fd.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.statSync(path)", + "type": "method", + "name": "statSync", + "desc": "

Synchronous stat(2). Returns an instance of fs.Stats.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.lstatSync(path)", + "type": "method", + "name": "lstatSync", + "desc": "

Synchronous lstat(2). Returns an instance of fs.Stats.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.fstatSync(fd)", + "type": "method", + "name": "fstatSync", + "desc": "

Synchronous fstat(2). Returns an instance of fs.Stats.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + } + ] + } + ] + }, + { + "textRaw": "fs.link(srcpath, dstpath, [callback])", + "type": "method", + "name": "link", + "desc": "

Asynchronous link(2). No arguments other than a possible exception are given to\nthe completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "srcpath" + }, + { + "name": "dstpath" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.linkSync(srcpath, dstpath)", + "type": "method", + "name": "linkSync", + "desc": "

Synchronous link(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "srcpath" + }, + { + "name": "dstpath" + } + ] + } + ] + }, + { + "textRaw": "fs.symlink(linkdata, path, [type], [callback])", + "type": "method", + "name": "symlink", + "desc": "

Asynchronous symlink(2). No arguments other than a possible exception are given\nto the completion callback.\ntype argument can be either 'dir' or 'file' (default is 'file'). It is only \nused on Windows (ignored on other platforms).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "linkdata" + }, + { + "name": "path" + }, + { + "name": "type", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.symlinkSync(linkdata, path, [type])", + "type": "method", + "name": "symlinkSync", + "desc": "

Synchronous symlink(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "linkdata" + }, + { + "name": "path" + }, + { + "name": "type", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readlink(path, [callback])", + "type": "method", + "name": "readlink", + "desc": "

Asynchronous readlink(2). The callback gets two arguments (err,\nlinkString).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readlinkSync(path)", + "type": "method", + "name": "readlinkSync", + "desc": "

Synchronous readlink(2). Returns the symbolic link's string value.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.realpath(path, [callback])", + "type": "method", + "name": "realpath", + "desc": "

Asynchronous realpath(2). The callback gets two arguments (err,\nresolvedPath). May use process.cwd to resolve relative paths.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.realpathSync(path)", + "type": "method", + "name": "realpathSync", + "desc": "

Synchronous realpath(2). Returns the resolved path.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.unlink(path, [callback])", + "type": "method", + "name": "unlink", + "desc": "

Asynchronous unlink(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.unlinkSync(path)", + "type": "method", + "name": "unlinkSync", + "desc": "

Synchronous unlink(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.rmdir(path, [callback])", + "type": "method", + "name": "rmdir", + "desc": "

Asynchronous rmdir(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.rmdirSync(path)", + "type": "method", + "name": "rmdirSync", + "desc": "

Synchronous rmdir(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.mkdir(path, [mode], [callback])", + "type": "method", + "name": "mkdir", + "desc": "

Asynchronous mkdir(2). No arguments other than a possible exception are given\nto the completion callback. mode defaults to 0777.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.mkdirSync(path, [mode])", + "type": "method", + "name": "mkdirSync", + "desc": "

Synchronous mkdir(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "mode", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readdir(path, [callback])", + "type": "method", + "name": "readdir", + "desc": "

Asynchronous readdir(3). Reads the contents of a directory.\nThe callback gets two arguments (err, files) where files is an array of\nthe names of the files in the directory excluding '.' and '..'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readdirSync(path)", + "type": "method", + "name": "readdirSync", + "desc": "

Synchronous readdir(3). Returns an array of filenames excluding '.' and\n'..'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + } + ] + } + ] + }, + { + "textRaw": "fs.close(fd, [callback])", + "type": "method", + "name": "close", + "desc": "

Asynchronous close(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.closeSync(fd)", + "type": "method", + "name": "closeSync", + "desc": "

Synchronous close(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + } + ] + } + ] + }, + { + "textRaw": "fs.open(path, flags, [mode], [callback])", + "type": "method", + "name": "open", + "desc": "

Asynchronous file open. See open(2). flags can be:\n\n

\n
    \n

  • 'r' - Open file for reading.\nAn exception occurs if the file does not exist.

    \n
    • \n

  • 'r+' - Open file for reading and writing.\nAn exception occurs if the file does not exist.

    \n
    • \n

  • 'w' - Open file for writing.\nThe file is created (if it does not exist) or truncated (if it exists).

    \n
    • \n

  • 'w+' - Open file for reading and writing.\nThe file is created (if it does not exist) or truncated (if it exists).

    \n
    • \n

  • 'a' - Open file for appending.\nThe file is created if it does not exist.

    \n
    • \n

  • 'a+' - Open file for reading and appending.\nThe file is created if it does not exist.

    \n
    • \n
\n

mode defaults to 0666. The callback gets two arguments (err, fd).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "flags" + }, + { + "name": "mode", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.openSync(path, flags, [mode])", + "type": "method", + "name": "openSync", + "desc": "

Synchronous open(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "flags" + }, + { + "name": "mode", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.utimes(path, atime, mtime, [callback])", + "type": "method", + "name": "utimes", + "desc": "

Change file timestamps of the file referenced by the supplied path.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "atime" + }, + { + "name": "mtime" + } + ] + }, + { + "params": [ + { + "name": "path" + }, + { + "name": "atime" + }, + { + "name": "mtime" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.utimesSync(path, atime, mtime)", + "type": "method", + "name": "utimesSync", + "desc": "

Change file timestamps of the file referenced by the supplied path.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "atime" + }, + { + "name": "mtime" + } + ] + } + ] + }, + { + "textRaw": "fs.futimes(fd, atime, mtime, [callback])", + "type": "method", + "name": "futimes", + "desc": "

Change the file timestamps of a file referenced by the supplied file\ndescriptor.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "atime" + }, + { + "name": "mtime" + } + ] + }, + { + "params": [ + { + "name": "fd" + }, + { + "name": "atime" + }, + { + "name": "mtime" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.futimesSync(fd, atime, mtime)", + "type": "method", + "name": "futimesSync", + "desc": "

Change the file timestamps of a file referenced by the supplied file\ndescriptor.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "atime" + }, + { + "name": "mtime" + } + ] + } + ] + }, + { + "textRaw": "fs.fsync(fd, [callback])", + "type": "method", + "name": "fsync", + "desc": "

Asynchronous fsync(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.fsyncSync(fd)", + "type": "method", + "name": "fsyncSync", + "desc": "

Synchronous fsync(2).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + } + ] + } + ] + }, + { + "textRaw": "fs.write(fd, buffer, offset, length, position, [callback])", + "type": "method", + "name": "write", + "desc": "

Write buffer to the file specified by fd.\n\n

\n

offset and length determine the part of the buffer to be written.\n\n

\n

position refers to the offset from the beginning of the file where this data\nshould be written. If position is null, the data will be written at the\ncurrent position.\nSee pwrite(2).\n\n

\n

The callback will be given three arguments (err, written, buffer) where written\nspecifies how many bytes were written from buffer.\n\n

\n

Note that it is unsafe to use fs.write multiple times on the same file\nwithout waiting for the callback. For this scenario,\nfs.createWriteStream is strongly recommended.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "buffer" + }, + { + "name": "offset" + }, + { + "name": "length" + }, + { + "name": "position" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.writeSync(fd, buffer, offset, length, position)", + "type": "method", + "name": "writeSync", + "desc": "

Synchronous version of buffer-based fs.write(). Returns the number of bytes\nwritten.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "buffer" + }, + { + "name": "offset" + }, + { + "name": "length" + }, + { + "name": "position" + } + ] + } + ] + }, + { + "textRaw": "fs.writeSync(fd, str, position, [encoding])", + "type": "method", + "name": "writeSync", + "desc": "

Synchronous version of string-based fs.write(). encoding defaults to\n'utf8'. Returns the number of bytes written.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "str" + }, + { + "name": "position" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.read(fd, buffer, offset, length, position, [callback])", + "type": "method", + "name": "read", + "desc": "

Read data from the file specified by fd.\n\n

\n

buffer is the buffer that the data will be written to.\n\n

\n

offset is offset within the buffer where writing will start.\n\n

\n

length is an integer specifying the number of bytes to read.\n\n

\n

position is an integer specifying where to begin reading from in the file.\nIf position is null, data will be read from the current file position.\n\n

\n

The callback is given the three arguments, (err, bytesRead, buffer).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "buffer" + }, + { + "name": "offset" + }, + { + "name": "length" + }, + { + "name": "position" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readSync(fd, buffer, offset, length, position)", + "type": "method", + "name": "readSync", + "desc": "

Synchronous version of buffer-based fs.read. Returns the number of\nbytesRead.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "buffer" + }, + { + "name": "offset" + }, + { + "name": "length" + }, + { + "name": "position" + } + ] + } + ] + }, + { + "textRaw": "fs.readSync(fd, length, position, encoding)", + "type": "method", + "name": "readSync", + "desc": "

Synchronous version of string-based fs.read. Returns the number of\nbytesRead.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + }, + { + "name": "length" + }, + { + "name": "position" + }, + { + "name": "encoding" + } + ] + } + ] + }, + { + "textRaw": "fs.readFile(filename, [encoding], [callback])", + "type": "method", + "name": "readFile", + "desc": "

Asynchronously reads the entire contents of a file. Example:\n\n

\n
fs.readFile('/etc/passwd', function (err, data) {\n  if (err) throw err;\n  console.log(data);\n});
\n

The callback is passed two arguments (err, data), where data is the\ncontents of the file.\n\n

\n

If no encoding is specified, then the raw buffer is returned.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "encoding", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.readFileSync(filename, [encoding])", + "type": "method", + "name": "readFileSync", + "desc": "

Synchronous version of fs.readFile. Returns the contents of the filename.\n\n

\n

If encoding is specified then this function returns a string. Otherwise it\nreturns a buffer.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.writeFile(filename, data, [encoding], [callback])", + "type": "method", + "name": "writeFile", + "desc": "

Asynchronously writes data to a file, replacing the file if it already exists.\ndata can be a string or a buffer. The encoding argument is ignored if\ndata is a buffer. It defaults to 'utf8'.\n\n

\n

Example:\n\n

\n
fs.writeFile('message.txt', 'Hello Node', function (err) {\n  if (err) throw err;\n  console.log('It\\'s saved!');\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "data" + }, + { + "name": "encoding", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.writeFileSync(filename, data, [encoding])", + "type": "method", + "name": "writeFileSync", + "desc": "

The synchronous version of fs.writeFile.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "data" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.watchFile(filename, [options], listener)", + "type": "method", + "name": "watchFile", + "stability": 2, + "stabilityText": "Unstable. Use fs.watch instead, if available.", + "desc": "

Watch for changes on filename. The callback listener will be called each\ntime the file is accessed.\n\n

\n

The second argument is optional. The options if provided should be an object\ncontaining two members a boolean, persistent, and interval. persistent\nindicates whether the process should continue to run as long as files are\nbeing watched. interval indicates how often the target should be polled,\nin milliseconds. (On Linux systems with inotify, interval is ignored.) The\ndefault is { persistent: true, interval: 0 }.\n\n

\n

The listener gets two arguments the current stat object and the previous\nstat object:\n\n

\n
fs.watchFile('message.text', function (curr, prev) {\n  console.log('the current mtime is: ' + curr.mtime);\n  console.log('the previous mtime was: ' + prev.mtime);\n});
\n

These stat objects are instances of fs.Stat.\n\n

\n

If you want to be notified when the file was modified, not just accessed\nyou need to compare curr.mtime and prev.mtime.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "options", + "optional": true + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "fs.unwatchFile(filename)", + "type": "method", + "name": "unwatchFile", + "stability": 2, + "stabilityText": "Unstable. Use fs.watch instead, if available.", + "desc": "

Stop watching for changes on filename.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "filename" + } + ] + } + ] + }, + { + "textRaw": "fs.watch(filename, [options], listener)", + "type": "method", + "name": "watch", + "stability": 2, + "stabilityText": "Unstable. Not available on all platforms.", + "desc": "

Watch for changes on filename, where filename is either a file or a\ndirectory. The returned object is a fs.FSWatcher.\n\n

\n

The second argument is optional. The options if provided should be an object\ncontaining a boolean member persistent, which indicates whether the process\nshould continue to run as long as files are being watched. The default is\n{ persistent: true }.\n\n

\n

The listener callback gets two arguments (event, filename). event is either\n'rename' or 'change', and filename is the name of the file which triggered\nthe event.\n\n

\n", + "miscs": [ + { + "textRaw": "Caveats", + "name": "Caveats", + "type": "misc", + "desc": "

The fs.watch API is not 100% consistent across platforms, and is\nunavailable in some situations.\n\n

\n", + "miscs": [ + { + "textRaw": "Availability", + "name": "Availability", + "type": "misc", + "desc": "

This feature depends on the underlying operating system providing a way\nto be notified of filesystem changes.\n\n

\n
    \n
  • On Linux systems, this uses inotify.
    • \n
  • On BSD systems (including OS X), this uses kqueue.
    • \n
  • On SunOS systems (including Solaris and SmartOS), this uses event ports.
    • \n
  • On Windows systems, this feature depends on ReadDirectoryChangesW.
    • \n
\n

If the underlying functionality is not available for some reason, then\nfs.watch will not be able to function. You can still use\nfs.watchFile, which uses stat polling, but it is slower and less\nreliable.\n\n

\n" + }, + { + "textRaw": "Filename Argument", + "name": "Filename Argument", + "type": "misc", + "desc": "

Providing filename argument in the callback is not supported\non every platform (currently it's only supported on Linux and Windows). Even\non supported platforms filename is not always guaranteed to be provided.\nTherefore, don't assume that filename argument is always provided in the\ncallback, and have some fallback logic if it is null.\n\n

\n
fs.watch('somedir', function (event, filename) {\n  console.log('event is: ' + event);\n  if (filename) {\n    console.log('filename provided: ' + filename);\n  } else {\n    console.log('filename not provided');\n  }\n});
\n" + } + ] + } + ], + "signatures": [ + { + "params": [ + { + "name": "filename" + }, + { + "name": "options", + "optional": true + }, + { + "name": "listener" + } + ] + } + ] + }, + { + "textRaw": "fs.createReadStream(path, [options])", + "type": "method", + "name": "createReadStream", + "desc": "

Returns a new ReadStream object (See Readable Stream).\n\n

\n

options is an object with the following defaults:\n\n

\n
{ flags: 'r',\n  encoding: null,\n  fd: null,\n  mode: 0666,\n  bufferSize: 64 * 1024\n}
\n

options can include start and end values to read a range of bytes from\nthe file instead of the entire file. Both start and end are inclusive and\nstart at 0.\n\n

\n

An example to read the last 10 bytes of a file which is 100 bytes long:\n\n

\n
fs.createReadStream('sample.txt', {start: 90, end: 99});
\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "fs.createWriteStream(path, [options])", + "type": "method", + "name": "createWriteStream", + "desc": "

Returns a new WriteStream object (See Writable Stream).\n\n

\n

options is an object with the following defaults:\n\n

\n
{ flags: 'w',\n  encoding: null,\n  mode: 0666 }
\n

options may also include a start option to allow writing data at\nsome position past the beginning of the file. Modifying a file rather\nthan replacing it may require a flags mode of r+ rather than the\ndefault mode w.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "options", + "optional": true + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: fs.Stats", + "type": "class", + "name": "fs.Stats", + "desc": "

Objects returned from fs.stat(), fs.lstat() and fs.fstat() and their\nsynchronous counterparts are of this type.\n\n

\n
    \n
  • stats.isFile()
    • \n
  • stats.isDirectory()
    • \n
  • stats.isBlockDevice()
    • \n
  • stats.isCharacterDevice()
    • \n
  • stats.isSymbolicLink() (only valid with fs.lstat())
    • \n
  • stats.isFIFO()
    • \n
  • stats.isSocket()
    • \n
\n

For a regular file util.inspect(stats) would return a string very\nsimilar to this:\n\n

\n
{ dev: 2114,\n  ino: 48064969,\n  mode: 33188,\n  nlink: 1,\n  uid: 85,\n  gid: 100,\n  rdev: 0,\n  size: 527,\n  blksize: 4096,\n  blocks: 8,\n  atime: Mon, 10 Oct 2011 23:24:11 GMT,\n  mtime: Mon, 10 Oct 2011 23:24:11 GMT,\n  ctime: Mon, 10 Oct 2011 23:24:11 GMT }
\n

Please note that atime, mtime and ctime are instances\nof [Date][MDN-Date] object and to compare the values of\nthese objects you should use appropriate methods. For most\ngeneral uses [getTime()][MDN-Date-getTime] will return\nthe number of milliseconds elapsed since 1 January 1970\n00:00:00 UTC and this integer should be sufficient for\nany comparison, however there additional methods which can\nbe used for displaying fuzzy information. More details can\nbe found in the [MDN JavaScript Reference][MDN-Date] page.\n\n

\n" + }, + { + "textRaw": "Class: fs.ReadStream", + "type": "class", + "name": "fs.ReadStream", + "desc": "

ReadStream is a Readable Stream.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'open'", + "type": "event", + "name": "open", + "params": [], + "desc": "

Emitted when the ReadStream's file is opened.\n\n\n

\n" + } + ] + }, + { + "textRaw": "Class: fs.FSWatcher", + "type": "class", + "name": "fs.FSWatcher", + "desc": "

Objects returned from fs.watch() are of this type.\n\n

\n", + "methods": [ + { + "textRaw": "watcher.close()", + "type": "method", + "name": "close", + "desc": "

Stop watching for changes on the given fs.FSWatcher.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "events": [ + { + "textRaw": "Event: 'change'", + "type": "event", + "name": "change", + "params": [], + "desc": "

Emitted when something changes in a watched directory or file.\nSee more details in fs.watch.\n\n

\n" + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "params": [], + "desc": "

Emitted when an error occurs.\n\n

\n" + } + ] + } + ], + "properties": [ + { + "textRaw": "fs.WriteStream", + "name": "WriteStream", + "desc": "

WriteStream is a Writable Stream.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'open'", + "type": "event", + "name": "open", + "params": [], + "desc": "

Emitted when the WriteStream's file is opened.\n\n

\n" + } + ], + "properties": [ + { + "textRaw": "file.bytesWritten", + "name": "bytesWritten", + "desc": "

The number of bytes written so far. Does not include data that is still queued\nfor writing.\n\n

\n" + } + ] + } + ], + "type": "module", + "displayName": "fs" + }, + { + "textRaw": "Path", + "name": "path", + "stability": 3, + "stabilityText": "Stable", + "desc": "

This module contains utilities for handling and transforming file\npaths. Almost all these methods perform only string transformations.\nThe file system is not consulted to check whether paths are valid.\n\n

\n

path.exists and path.existsSync are the exceptions, and should\nlogically be found in the fs module as they do access the file system.\n\n

\n

Use require('path') to use this module. The following methods are provided:\n\n

\n", + "methods": [ + { + "textRaw": "path.normalize(p)", + "type": "method", + "name": "normalize", + "desc": "

Normalize a string path, taking care of '..' and '.' parts.\n\n

\n

When multiple slashes are found, they're replaced by a single one;\nwhen the path contains a trailing slash, it is preserved.\nOn windows backslashes are used. \n\n

\n

Example:\n\n

\n
path.normalize('/foo/bar//baz/asdf/quux/..')\n// returns\n'/foo/bar/baz/asdf'
\n", + "signatures": [ + { + "params": [ + { + "name": "p" + } + ] + } + ] + }, + { + "textRaw": "path.join([path1], [path2], [...])", + "type": "method", + "name": "join", + "desc": "

Join all arguments together and normalize the resulting path.\nNon-string arguments are ignored.\n\n

\n

Example:\n\n

\n
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')\n// returns\n'/foo/bar/baz/asdf'\n\npath.join('foo', {}, 'bar')\n// returns\n'foo/bar'
\n", + "signatures": [ + { + "params": [ + { + "name": "path1", + "optional": true + }, + { + "name": "path2", + "optional": true + }, + { + "name": "...", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "path.resolve([from ...], to)", + "type": "method", + "name": "resolve", + "desc": "

Resolves to to an absolute path.\n\n

\n

If to isn't already absolute from arguments are prepended in right to left\norder, until an absolute path is found. If after using all from paths still\nno absolute path is found, the current working directory is used as well. The\nresulting path is normalized, and trailing slashes are removed unless the path \ngets resolved to the root directory. Non-string arguments are ignored.\n\n

\n

Another way to think of it is as a sequence of cd commands in a shell.\n\n

\n
path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
\n

Is similar to:\n\n

\n
cd foo/bar\ncd /tmp/file/\ncd ..\ncd a/../subfile\npwd
\n

The difference is that the different paths don't need to exist and may also be\nfiles.\n\n

\n

Examples:\n\n

\n
path.resolve('/foo/bar', './baz')\n// returns\n'/foo/bar/baz'\n\npath.resolve('/foo/bar', '/tmp/file/')\n// returns\n'/tmp/file'\n\npath.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')\n// if currently in /home/myself/node, it returns\n'/home/myself/node/wwwroot/static_files/gif/image.gif'
\n", + "signatures": [ + { + "params": [ + { + "name": "from ...", + "optional": true + }, + { + "name": "to" + } + ] + } + ] + }, + { + "textRaw": "path.relative(from, to)", + "type": "method", + "name": "relative", + "desc": "

Solve the relative path from from to to.\n\n

\n

At times we have two absolute paths, and we need to derive the relative\npath from one to the other. This is actually the reverse transform of\npath.resolve, which means we see that:\n\n

\n
path.resolve(from, path.relative(from, to)) == path.resolve(to)
\n

Examples:\n\n

\n
path.relative('C:\\\\orandea\\\\test\\\\aaa', 'C:\\\\orandea\\\\impl\\\\bbb')\n// returns\n'..\\\\..\\\\impl\\\\bbb'\n\npath.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')\n// returns\n'../../impl/bbb'
\n", + "signatures": [ + { + "params": [ + { + "name": "from" + }, + { + "name": "to" + } + ] + } + ] + }, + { + "textRaw": "path.dirname(p)", + "type": "method", + "name": "dirname", + "desc": "

Return the directory name of a path. Similar to the Unix dirname command.\n\n

\n

Example:\n\n

\n
path.dirname('/foo/bar/baz/asdf/quux')\n// returns\n'/foo/bar/baz/asdf'
\n", + "signatures": [ + { + "params": [ + { + "name": "p" + } + ] + } + ] + }, + { + "textRaw": "path.basename(p, [ext])", + "type": "method", + "name": "basename", + "desc": "

Return the last portion of a path. Similar to the Unix basename command.\n\n

\n

Example:\n\n

\n
path.basename('/foo/bar/baz/asdf/quux.html')\n// returns\n'quux.html'\n\npath.basename('/foo/bar/baz/asdf/quux.html', '.html')\n// returns\n'quux'
\n", + "signatures": [ + { + "params": [ + { + "name": "p" + }, + { + "name": "ext", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "path.extname(p)", + "type": "method", + "name": "extname", + "desc": "

Return the extension of the path, from the last '.' to end of string\nin the last portion of the path. If there is no '.' in the last portion\nof the path or the first character of it is '.', then it returns\nan empty string. Examples:\n\n

\n
path.extname('index.html')\n// returns\n'.html'\n\npath.extname('index.')\n// returns\n'.'\n\npath.extname('index')\n// returns\n''
\n", + "signatures": [ + { + "params": [ + { + "name": "p" + } + ] + } + ] + }, + { + "textRaw": "path.exists(p, [callback])", + "type": "method", + "name": "exists", + "desc": "

Test whether or not the given path exists by checking with the file system.\nThen call the callback argument with either true or false. Example:\n\n

\n
path.exists('/etc/passwd', function (exists) {\n  util.debug(exists ? "it's there" : "no passwd!");\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "p" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "path.existsSync(p)", + "type": "method", + "name": "existsSync", + "desc": "

Synchronous version of path.exists.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "p" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "Path" + }, + { + "textRaw": "net", + "name": "net", + "stability": 3, + "stabilityText": "Stable", + "desc": "

The net module provides you with an asynchronous network wrapper. It contains\nmethods for creating both servers and clients (called streams). You can include\nthis module with require('net');\n\n

\n", + "methods": [ + { + "textRaw": "net.createServer([options], [connectionListener])", + "type": "method", + "name": "createServer", + "desc": "

Creates a new TCP server. The connectionListener argument is\nautomatically set as a listener for the 'connection'\nevent.\n\n

\n

options is an object with the following defaults:\n\n

\n
{ allowHalfOpen: false\n}
\n

If allowHalfOpen is true, then the socket won't automatically send FIN\npacket when the other end of the socket sends a FIN packet. The socket becomes\nnon-readable, but still writable. You should call the end() method explicitly.\nSee 'end' event for more information.\n\n

\n

Here is an example of a echo server which listens for connections\non port 8124:\n\n

\n
var net = require('net');\nvar server = net.createServer(function(c) { //'connection' listener\n  console.log('server connected');\n  c.on('end', function() {\n    console.log('server disconnected');\n  });\n  c.write('hello\\r\\n');\n  c.pipe(c);\n});\nserver.listen(8124, function() { //'listening' listener\n  console.log('server bound');\n});
\n

Test this by using telnet:\n\n

\n
telnet localhost 8124
\n

To listen on the socket /tmp/echo.sock the third line from the last would\njust be changed to\n\n

\n
server.listen('/tmp/echo.sock', function() { //'listening' listener
\n

Use nc to connect to a UNIX domain socket server:\n\n

\n
nc -U /tmp/echo.sock
\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + }, + { + "name": "connectionListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "net.connect(arguments...)", + "type": "method", + "name": "connect", + "desc": "

Construct a new socket object and opens a socket to the given location. When\nthe socket is established the 'connect' event will be\nemitted.\n\n

\n

The arguments for these methods change the type of connection:\n\n

\n
    \n
  • net.connect(port, [host], [connectListener])
    • \n

  • net.createConnection(port, [host], [connectListener])

    \n

    Creates a TCP connection to port on host. If host is omitted,\n'localhost' will be assumed.

    \n
    • \n

  • net.connect(path, [connectListener])

    \n
    • \n

  • net.createConnection(path, [connectListener])

    \n

    Creates unix socket connection to path.

    \n
    • \n
\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n

\n

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

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

To connect on the socket /tmp/echo.sock the second line would just be\nchanged to\n\n

\n
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
\n", + "signatures": [ + { + "params": [ + { + "name": "arguments..." + } + ] + }, + { + "params": [ + { + "name": "arguments..." + } + ] + } + ] + }, + { + "textRaw": "net.createConnection(arguments...)", + "type": "method", + "name": "createConnection", + "desc": "

Construct a new socket object and opens a socket to the given location. When\nthe socket is established the 'connect' event will be\nemitted.\n\n

\n

The arguments for these methods change the type of connection:\n\n

\n
    \n
  • net.connect(port, [host], [connectListener])
    • \n

  • net.createConnection(port, [host], [connectListener])

    \n

    Creates a TCP connection to port on host. If host is omitted,\n'localhost' will be assumed.

    \n
    • \n

  • net.connect(path, [connectListener])

    \n
    • \n

  • net.createConnection(path, [connectListener])

    \n

    Creates unix socket connection to path.

    \n
    • \n
\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n

\n

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

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

To connect on the socket /tmp/echo.sock the second line would just be\nchanged to\n\n

\n
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
\n", + "signatures": [ + { + "params": [ + { + "name": "arguments..." + } + ] + } + ] + }, + { + "textRaw": "net.isIP(input)", + "type": "method", + "name": "isIP", + "desc": "

Tests if input is an IP address. Returns 0 for invalid strings,\nreturns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "input" + } + ] + } + ] + }, + { + "textRaw": "net.isIPv4(input)", + "type": "method", + "name": "isIPv4", + "desc": "

Returns true if input is a version 4 IP address, otherwise returns false.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "input" + } + ] + } + ] + }, + { + "textRaw": "net.isIPv6(input)", + "type": "method", + "name": "isIPv6", + "desc": "

Returns true if input is a version 6 IP address, otherwise returns false.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "input" + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: net.Server", + "type": "class", + "name": "net.Server", + "desc": "

This class is used to create a TCP or UNIX server.\nA server is a net.Socket that can listen for new incoming connections.\n\n

\n", + "methods": [ + { + "textRaw": "server.listen(port, [host], [listeningListener])", + "type": "method", + "name": "listen", + "desc": "

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

\n

This function is asynchronous. When the server has been bound,\n'listening' event will be emitted.\nthe last parameter listeningListener will be added as an listener for the\n'listening' event.\n\n

\n

One issue some users run into is getting EADDRINUSE errors. This means that\nanother server is already running on the requested port. One way of handling this\nwould be to wait a second and then try again. This can be done with\n\n

\n
server.on('error', function (e) {\n  if (e.code == 'EADDRINUSE') {\n    console.log('Address in use, retrying...');\n    setTimeout(function () {\n      server.close();\n      server.listen(PORT, HOST);\n    }, 1000);\n  }\n});
\n

(Note: All sockets in Node set SO_REUSEADDR already)\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "port" + }, + { + "name": "host", + "optional": true + }, + { + "name": "listeningListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "server.listen(path, [listeningListener])", + "type": "method", + "name": "listen", + "desc": "

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

\n

This function is asynchronous. When the server has been bound,\n'listening' event will be emitted.\nthe last parameter listeningListener will be added as an listener for the\n'listening' event.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "listeningListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "server.close()", + "type": "method", + "name": "close", + "desc": "

Stops the server from accepting new connections. This function is\nasynchronous, the server is finally closed when the server emits a 'close'\nevent.\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "server.address()", + "type": "method", + "name": "address", + "desc": "

Returns the bound address and port of the server as reported by the operating system.\nUseful to find which port was assigned when giving getting an OS-assigned address.\nReturns an object with two properties, e.g. {"address":"127.0.0.1", "port":2121}\n\n

\n

Example:\n\n

\n
var server = net.createServer(function (socket) {\n  socket.end("goodbye\\n");\n});\n\n// grab a random port.\nserver.listen(function() {\n  address = server.address();\n  console.log("opened server on %j", address);\n});
\n

Don't call server.address() until the 'listening' event has been emitted.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "properties": [ + { + "textRaw": "server.maxConnections", + "name": "maxConnections", + "desc": "

Set this property to reject connections when the server's connection count gets\nhigh.\n\n

\n" + }, + { + "textRaw": "server.connections", + "name": "connections", + "desc": "

The number of concurrent connections on the server.\n\n\n

\n

net.Server is an EventEmitter with the following events:\n\n

\n" + } + ], + "events": [ + { + "textRaw": "Event: 'listening'", + "type": "event", + "name": "listening", + "desc": "

Emitted when the server has been bound after calling server.listen.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'connection'", + "type": "event", + "name": "connection", + "params": [], + "desc": "

Emitted when a new connection is made. socket is an instance of\nnet.Socket.\n\n

\n" + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

Emitted when the server closes.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "params": [], + "desc": "

Emitted when an error occurs. The 'close' event will be called directly\nfollowing this event. See example in discussion of server.listen.\n\n

\n" + } + ] + }, + { + "textRaw": "Class: net.Socket", + "type": "class", + "name": "net.Socket", + "desc": "

This object is an abstraction of a TCP or UNIX socket. net.Socket\ninstances implement a duplex Stream interface. They can be created by the\nuser and used as a client (with connect()) or they can be created by Node\nand passed to the user through the 'connection' event of a server.\n\n

\n", + "methods": [ + { + "textRaw": "new net.Socket([options])", + "type": "method", + "name": "Socket", + "desc": "

Construct a new socket object.\n\n

\n

options is an object with the following defaults:\n\n

\n
{ fd: null\n  type: null\n  allowHalfOpen: false\n}
\n

fd allows you to specify the existing file descriptor of socket. type\nspecified underlying protocol. It can be 'tcp4', 'tcp6', or 'unix'.\nAbout allowHalfOpen, refer to createServer() and 'end' event.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.connect(port, [host], [connectListener])", + "type": "method", + "name": "connect", + "desc": "

Opens the connection for a given socket. If port and host are given,\nthen the socket will be opened as a TCP socket, if host is omitted,\nlocalhost will be assumed. If a path is given, the socket will be\nopened as a unix socket to that path.\n\n

\n

Normally this method is not needed, as net.createConnection opens the\nsocket. Use this only if you are implementing a custom Socket or if a\nSocket is closed and you want to reuse it to connect to another server.\n\n

\n

This function is asynchronous. When the 'connect' event is\nemitted the socket is established. If there is a problem connecting, the\n'connect' event will not be emitted, the 'error' event will be emitted with\nthe exception.\n\n

\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "connectListener", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "port" + }, + { + "name": "host", + "optional": true + }, + { + "name": "connectListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.connect(path, [connectListener])", + "type": "method", + "name": "connect", + "desc": "

Opens the connection for a given socket. If port and host are given,\nthen the socket will be opened as a TCP socket, if host is omitted,\nlocalhost will be assumed. If a path is given, the socket will be\nopened as a unix socket to that path.\n\n

\n

Normally this method is not needed, as net.createConnection opens the\nsocket. Use this only if you are implementing a custom Socket or if a\nSocket is closed and you want to reuse it to connect to another server.\n\n

\n

This function is asynchronous. When the 'connect' event is\nemitted the socket is established. If there is a problem connecting, the\n'connect' event will not be emitted, the 'error' event will be emitted with\nthe exception.\n\n

\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "connectListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.setEncoding([encoding])", + "type": "method", + "name": "setEncoding", + "desc": "

Sets the encoding (either 'ascii', 'utf8', or 'base64') for data that is\nreceived. Defaults to null.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.setSecure()", + "type": "method", + "name": "setSecure", + "desc": "

This function has been removed in v0.3. It used to upgrade the connection to\nSSL/TLS. See the TLS section for the new API.\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "socket.write(data, [encoding], [callback])", + "type": "method", + "name": "write", + "desc": "

Sends data on the socket. The second parameter specifies the encoding in the\ncase of a string--it defaults to UTF8 encoding.\n\n

\n

Returns true if the entire data was flushed successfully to the kernel\nbuffer. Returns false if all or part of the data was queued in user memory.\n'drain' will be emitted when the buffer is again free.\n\n

\n

The optional callback parameter will be executed when the data is finally\nwritten out - this may not be immediately.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + }, + { + "name": "encoding", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.end([data], [encoding])", + "type": "method", + "name": "end", + "desc": "

Half-closes the socket. i.e., it sends a FIN packet. It is possible the\nserver will still send some data.\n\n

\n

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

\n", + "signatures": [ + { + "params": [ + { + "name": "data", + "optional": true + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.destroy()", + "type": "method", + "name": "destroy", + "desc": "

Ensures that no more I/O activity happens on this socket. Only necessary in\ncase of errors (parse error or so).\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "socket.pause()", + "type": "method", + "name": "pause", + "desc": "

Pauses the reading of data. That is, 'data' events will not be emitted.\nUseful to throttle back an upload.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "socket.resume()", + "type": "method", + "name": "resume", + "desc": "

Resumes reading after a call to pause().\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "socket.setTimeout(timeout, [callback])", + "type": "method", + "name": "setTimeout", + "desc": "

Sets the socket to timeout after timeout milliseconds of inactivity on\nthe socket. By default net.Socket do not have a timeout.\n\n

\n

When an idle timeout is triggered the socket will receive a 'timeout'\nevent but the connection will not be severed. The user must manually end()\nor destroy() the socket.\n\n

\n

If timeout is 0, then the existing idle timeout is disabled.\n\n

\n

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

\n", + "signatures": [ + { + "params": [ + { + "name": "timeout" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.setNoDelay([noDelay])", + "type": "method", + "name": "setNoDelay", + "desc": "

Disables the Nagle algorithm. By default TCP connections use the Nagle\nalgorithm, they buffer data before sending it off. Setting true for\nnoDelay will immediately fire off data each time socket.write() is called.\nnoDelay defaults to true.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "noDelay", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.setKeepAlive([enable], [initialDelay])", + "type": "method", + "name": "setKeepAlive", + "desc": "

Enable/disable keep-alive functionality, and optionally set the initial\ndelay before the first keepalive probe is sent on an idle socket.\nenable defaults to false.\n\n

\n

Set initialDelay (in milliseconds) to set the delay between the last\ndata packet received and the first keepalive probe. Setting 0 for\ninitialDelay will leave the value unchanged from the default\n(or previous) setting. Defaults to 0.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "enable", + "optional": true + }, + { + "name": "initialDelay", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "socket.address()", + "type": "method", + "name": "address", + "desc": "

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

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "properties": [ + { + "textRaw": "socket.bufferSize", + "name": "bufferSize", + "desc": "

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

\n

The consequence of this internal buffering is that memory may grow. This\nproperty shows the number of characters currently buffered to be written.\n(Number of characters is approximately equal to the number of bytes to be\nwritten, but the buffer may contain strings, and the strings are lazily\nencoded, so the exact number of bytes is not known.)\n\n

\n

Users who experience large or growing bufferSize should attempt to\n"throttle" the data flows in their program with pause() and resume().\n\n\n

\n" + }, + { + "textRaw": "socket.remoteAddress", + "name": "remoteAddress", + "desc": "

The string representation of the remote IP address. For example,\n'74.125.127.100' or '2001:4860:a005::68'.\n\n

\n" + }, + { + "textRaw": "socket.remotePort", + "name": "remotePort", + "desc": "

The numeric representation of the remote port. For example,\n80 or 21.\n\n

\n" + }, + { + "textRaw": "socket.bytesRead", + "name": "bytesRead", + "desc": "

The amount of received bytes.\n\n

\n" + }, + { + "textRaw": "socket.bytesWritten", + "name": "bytesWritten", + "desc": "

The amount of bytes sent.\n\n\n

\n

net.Socket instances are EventEmitters with the following events:\n\n

\n" + } + ], + "events": [ + { + "textRaw": "Event: 'connect'", + "type": "event", + "name": "connect", + "desc": "

Emitted when a socket connection is successfully established.\nSee connect().\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'data'", + "type": "event", + "name": "data", + "params": [], + "desc": "

Emitted when data is received. The argument data will be a Buffer or\nString. Encoding of data is set by socket.setEncoding().\n(See the Readable Stream section for more\ninformation.)\n\n

\n

Note that the data will be lost if there is no listener when a Socket\nemits a 'data' event.\n\n

\n" + }, + { + "textRaw": "Event: 'end'", + "type": "event", + "name": "end", + "desc": "

Emitted when the other end of the socket sends a FIN packet.\n\n

\n

By default (allowHalfOpen == false) the socket will destroy its file\ndescriptor once it has written out its pending write queue. However, by\nsetting allowHalfOpen == true the socket will not automatically end()\nits side allowing the user to write arbitrary amounts of data, with the\ncaveat that the user is required to end() their side now.\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'timeout'", + "type": "event", + "name": "timeout", + "desc": "

Emitted if the socket times out from inactivity. This is only to notify that\nthe socket has been idle. The user must manually close the connection.\n\n

\n

See also: socket.setTimeout()\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'drain'", + "type": "event", + "name": "drain", + "desc": "

Emitted when the write buffer becomes empty. Can be used to throttle uploads.\n\n

\n

See also: the return values of socket.write()\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "params": [], + "desc": "

Emitted when an error occurs. The 'close' event will be called directly\nfollowing this event.\n\n

\n" + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "params": [], + "desc": "

Emitted once the socket is fully closed. The argument had_error is a boolean\nwhich says if the socket was closed due to a transmission error.\n\n

\n" + } + ] + } + ], + "type": "module", + "displayName": "net" + }, + { + "textRaw": "UDP / Datagram Sockets", + "name": "dgram", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Datagram sockets are available through require('dgram').\n\n

\n", + "methods": [ + { + "textRaw": "dgram.createSocket(type, [callback])", + "type": "method", + "name": "createSocket", + "signatures": [ + { + "return": { + "textRaw": "Returns: Socket object ", + "name": "return", + "desc": "Socket object" + }, + "params": [ + { + "textRaw": "`type` String. Either 'udp4' or 'udp6' ", + "name": "type", + "desc": "String. Either 'udp4' or 'udp6'" + }, + { + "textRaw": "`callback` Function. Attached as a listener to `message` events. Optional ", + "name": "callback", + "optional": true, + "desc": "Function. Attached as a listener to `message` events." + } + ] + }, + { + "params": [ + { + "name": "type" + }, + { + "name": "callback", + "optional": true + } + ] + } + ], + "desc": "

Creates a datagram Socket of the specified types. Valid types are udp4\nand udp6.\n\n

\n

Takes an optional callback which is added as a listener for message events.\n\n

\n

Call socket.bind if you want to receive datagrams. socket.bind() will bind\nto the "all interfaces" address on a random port (it does the right thing for\nboth udp4 and udp6 sockets). You can then retrieve the address and port\nwith socket.address().address and socket.address().port.\n\n

\n" + } + ], + "classes": [ + { + "textRaw": "Class: Socket", + "type": "class", + "name": "Socket", + "desc": "

The dgram Socket class encapsulates the datagram functionality. It\nshould be created via dgram.createSocket(type, [callback]).\n\n

\n", + "events": [ + { + "textRaw": "Event: 'message'", + "type": "event", + "name": "message", + "params": [], + "desc": "

Emitted when a new datagram is available on a socket. msg is a Buffer and rinfo is\nan object with the sender's address information and the number of bytes in the datagram.\n\n

\n" + }, + { + "textRaw": "Event: 'listening'", + "type": "event", + "name": "listening", + "desc": "

Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets\nare created.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

Emitted when a socket is closed with close(). No new message events will be emitted\non this socket.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "params": [], + "desc": "

Emitted when an error occurs.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "dgram.send(buf, offset, length, port, address, [callback])", + "type": "method", + "name": "send", + "signatures": [ + { + "params": [ + { + "textRaw": "`buf` Buffer object. Message to be sent ", + "name": "buf", + "desc": "Buffer object. Message to be sent" + }, + { + "textRaw": "`offset` Integer. Offset in the buffer where the message starts. ", + "name": "offset", + "desc": "Integer. Offset in the buffer where the message starts." + }, + { + "textRaw": "`length` Integer. Number of bytes in the message. ", + "name": "length", + "desc": "Integer. Number of bytes in the message." + }, + { + "textRaw": "`port` Integer. destination port ", + "name": "port", + "desc": "Integer. destination port" + }, + { + "textRaw": "`address` String. destination IP ", + "name": "address", + "desc": "String. destination IP" + }, + { + "textRaw": "`callback` Function. Callback when message is done being delivered. Optional. ", + "name": "callback", + "desc": "Function. Callback when message is done being delivered. Optional.", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "buf" + }, + { + "name": "offset" + }, + { + "name": "length" + }, + { + "name": "port" + }, + { + "name": "address" + }, + { + "name": "callback", + "optional": true + } + ] + } + ], + "desc": "

For UDP sockets, the destination port and IP address must be specified. A string\nmay be supplied for the address parameter, and it will be resolved with DNS. An\noptional callback may be specified to detect any DNS errors and when buf may be\nre-used. Note that DNS lookups will delay the time that a send takes place, at\nleast until the next tick. The only way to know for sure that a send has taken place\nis to use the callback.\n\n

\n

If the socket has not been previously bound with a call to bind, it's\nassigned a random port number and bound to the "all interfaces" address\n(0.0.0.0 for udp4 sockets, ::0 for udp6 sockets).\n\n

\n

Example of sending a UDP packet to a random port on localhost;\n\n

\n
var dgram = require('dgram');\nvar message = new Buffer("Some bytes");\nvar client = dgram.createSocket("udp4");\nclient.send(message, 0, message.length, 41234, "localhost", function(err, bytes) {\n  client.close();\n});
\n

A Note about UDP datagram size\n\n

\n

The maximum size of an IPv4/v6 datagram depends on the MTU (Maximum Transmission Unit)\nand on the Payload Length field size.\n\n

\n
    \n

  • The Payload Length field is 16 bits wide, which means that a normal payload\ncannot be larger than 64K octets including internet header and data\n(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header);\nthis is generally true for loopback interfaces, but such long datagrams\nare impractical for most hosts and networks.

    \n
    • \n

  • The MTU is the largest size a given link layer technology can support for datagrams.\nFor any link, IPv4 mandates a minimum MTU of 68 octets, while the recommended MTU\nfor IPv4 is 576 (typically recommended as the MTU for dial-up type applications),\nwhether they arrive whole or in fragments.

    \n

    For IPv6, the minimum MTU is 1280 octets, however, the mandatory minimum\nfragment reassembly buffer size is 1500 octets.\nThe value of 68 octets is very small, since most current link layer technologies have\na minimum MTU of 1500 (like Ethernet).

    \n
    • \n
\n

Note that it's impossible to know in advance the MTU of each link through which\na packet might travel, and that generally sending a datagram greater than\nthe (receiver) MTU won't work (the packet gets silently dropped, without\ninforming the source that the data did not reach its intended recipient).\n\n

\n" + }, + { + "textRaw": "dgram.bind(port, [address])", + "type": "method", + "name": "bind", + "signatures": [ + { + "params": [ + { + "textRaw": "`port` Integer ", + "name": "port", + "desc": "Integer" + }, + { + "textRaw": "`address` String, Optional ", + "name": "address", + "optional": true, + "desc": "String" + } + ] + }, + { + "params": [ + { + "name": "port" + }, + { + "name": "address", + "optional": true + } + ] + } + ], + "desc": "

For UDP sockets, listen for datagrams on a named port and optional address. If\naddress is not specified, the OS will try to listen on all addresses.\n\n

\n

Example of a UDP server listening on port 41234:\n\n

\n
var dgram = require("dgram");\n\nvar server = dgram.createSocket("udp4");\n\nserver.on("message", function (msg, rinfo) {\n  console.log("server got: " + msg + " from " +\n    rinfo.address + ":" + rinfo.port);\n});\n\nserver.on("listening", function () {\n  var address = server.address();\n  console.log("server listening " +\n      address.address + ":" + address.port);\n});\n\nserver.bind(41234);\n// server listening 0.0.0.0:41234
\n" + }, + { + "textRaw": "dgram.close()", + "type": "method", + "name": "close", + "desc": "

Close the underlying socket and stop listening for data on it.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "dgram.address()", + "type": "method", + "name": "address", + "desc": "

Returns an object containing the address information for a socket. For UDP sockets,\nthis object will contain address and port.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "dgram.setBroadcast(flag)", + "type": "method", + "name": "setBroadcast", + "signatures": [ + { + "params": [ + { + "textRaw": "`flag` Boolean ", + "name": "flag", + "desc": "Boolean" + } + ] + }, + { + "params": [ + { + "name": "flag" + } + ] + } + ], + "desc": "

Sets or clears the SO_BROADCAST socket option. When this option is set, UDP packets\nmay be sent to a local interface's broadcast address.\n\n

\n" + }, + { + "textRaw": "dgram.setTTL(ttl)", + "type": "method", + "name": "setTTL", + "signatures": [ + { + "params": [ + { + "textRaw": "`ttl` Integer ", + "name": "ttl", + "desc": "Integer" + } + ] + }, + { + "params": [ + { + "name": "ttl" + } + ] + } + ], + "desc": "

Sets the IP_TTL socket option. TTL stands for "Time to Live," but in this context it\nspecifies the number of IP hops that a packet is allowed to go through. Each router or\ngateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a\nrouter, it will not be forwarded. Changing TTL values is typically done for network\nprobes or when multicasting.\n\n

\n

The argument to setTTL() is a number of hops between 1 and 255. The default on most\nsystems is 64.\n\n

\n" + }, + { + "textRaw": "dgram.setMulticastTTL(ttl)", + "type": "method", + "name": "setMulticastTTL", + "signatures": [ + { + "params": [ + { + "textRaw": "`ttl` Integer ", + "name": "ttl", + "desc": "Integer" + } + ] + }, + { + "params": [ + { + "name": "ttl" + } + ] + } + ], + "desc": "

Sets the IP_MULTICAST_TTL socket option. TTL stands for "Time to Live," but in this\ncontext it specifies the number of IP hops that a packet is allowed to go through,\nspecifically for multicast traffic. Each router or gateway that forwards a packet\ndecrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded.\n\n

\n

The argument to setMulticastTTL() is a number of hops between 0 and 255. The default on most\nsystems is 64.\n\n

\n" + }, + { + "textRaw": "dgram.setMulticastLoopback(flag)", + "type": "method", + "name": "setMulticastLoopback", + "signatures": [ + { + "params": [ + { + "textRaw": "`flag` Boolean ", + "name": "flag", + "desc": "Boolean" + } + ] + }, + { + "params": [ + { + "name": "flag" + } + ] + } + ], + "desc": "

Sets or clears the IP_MULTICAST_LOOP socket option. When this option is set, multicast\npackets will also be received on the local interface.\n\n

\n" + }, + { + "textRaw": "dgram.addMembership(multicastAddress, [multicastInterface])", + "type": "method", + "name": "addMembership", + "signatures": [ + { + "params": [ + { + "textRaw": "`multicastAddress` String ", + "name": "multicastAddress", + "desc": "String" + }, + { + "textRaw": "`multicastInterface` String, Optional ", + "name": "multicastInterface", + "optional": true, + "desc": "String" + } + ] + }, + { + "params": [ + { + "name": "multicastAddress" + }, + { + "name": "multicastInterface", + "optional": true + } + ] + } + ], + "desc": "

Tells the kernel to join a multicast group with IP_ADD_MEMBERSHIP socket option.\n\n

\n

If multicastInterface is not specified, the OS will try to add membership to all valid\ninterfaces.\n\n

\n" + }, + { + "textRaw": "dgram.dropMembership(multicastAddress, [multicastInterface])", + "type": "method", + "name": "dropMembership", + "signatures": [ + { + "params": [ + { + "textRaw": "`multicastAddress` String ", + "name": "multicastAddress", + "desc": "String" + }, + { + "textRaw": "`multicastInterface` String, Optional ", + "name": "multicastInterface", + "optional": true, + "desc": "String" + } + ] + }, + { + "params": [ + { + "name": "multicastAddress" + }, + { + "name": "multicastInterface", + "optional": true + } + ] + } + ], + "desc": "

Opposite of addMembership - tells the kernel to leave a multicast group with\nIP_DROP_MEMBERSHIP socket option. This is automatically called by the kernel\nwhen the socket is closed or process terminates, so most apps will never need to call\nthis.\n\n

\n

If multicastInterface is not specified, the OS will try to drop membership to all valid\ninterfaces.\n\n

\n" + } + ] + } + ], + "type": "module", + "displayName": "dgram" + }, + { + "textRaw": "DNS", + "name": "dns", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Use require('dns') to access this module. All methods in the dns module\nuse C-Ares except for dns.lookup which uses getaddrinfo(3) in a thread\npool. C-Ares is much faster than getaddrinfo but the system resolver is\nmore constant with how other programs operate. When a user does\nnet.connect(80, 'google.com') or http.get({ host: 'google.com' }) the\ndns.lookup method is used. Users who need to do a large number of look ups\nquickly should use the methods that go through C-Ares.\n\n

\n

Here is an example which resolves 'www.google.com' then reverse\nresolves the IP addresses which are returned.\n\n

\n
var dns = require('dns');\n\ndns.resolve4('www.google.com', function (err, addresses) {\n  if (err) throw err;\n\n  console.log('addresses: ' + JSON.stringify(addresses));\n\n  addresses.forEach(function (a) {\n    dns.reverse(a, function (err, domains) {\n      if (err) {\n        console.log('reverse for ' + a + ' failed: ' +\n          err.message);\n      } else {\n        console.log('reverse for ' + a + ': ' +\n          JSON.stringify(domains));\n      }\n    });\n  });\n});
\n", + "methods": [ + { + "textRaw": "dns.lookup(domain, [family], callback)", + "type": "method", + "name": "lookup", + "desc": "

Resolves a domain (e.g. 'google.com') into the first found A (IPv4) or\nAAAA (IPv6) record.\nThe family can be the integer 4 or 6. Defaults to null that indicates\nboth Ip v4 and v6 address family.\n\n

\n

The callback has arguments (err, address, family). The address argument\nis a string representation of a IP v4 or v6 address. The family argument\nis either the integer 4 or 6 and denotes the family of address (not\nnecessarily the value initially passed to lookup).\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "family", + "optional": true + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolve(domain, [rrtype], callback)", + "type": "method", + "name": "resolve", + "desc": "

Resolves a domain (e.g. 'google.com') into an array of the record types\nspecified by rrtype. Valid rrtypes are 'A' (IPV4 addresses, default),\n'AAAA' (IPV6 addresses), 'MX' (mail exchange records), 'TXT' (text\nrecords), 'SRV' (SRV records), 'PTR' (used for reverse IP lookups),\n'NS' (name server records) and 'CNAME' (canonical name records).\n\n

\n

The callback has arguments (err, addresses). The type of each item\nin addresses is determined by the record type, and described in the\ndocumentation for the corresponding lookup methods below.\n\n

\n

On error, err would be an instanceof Error object, where err.errno is\none of the error codes listed below and err.message is a string describing\nthe error in English.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "rrtype", + "optional": true + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolve4(domain, callback)", + "type": "method", + "name": "resolve4", + "desc": "

The same as dns.resolve(), but only for IPv4 queries (A records).\naddresses is an array of IPv4 addresses (e.g.\n['74.125.79.104', '74.125.79.105', '74.125.79.106']).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolve6(domain, callback)", + "type": "method", + "name": "resolve6", + "desc": "

The same as dns.resolve4() except for IPv6 queries (an AAAA query).\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolveMx(domain, callback)", + "type": "method", + "name": "resolveMx", + "desc": "

The same as dns.resolve(), but only for mail exchange queries (MX records).\n\n

\n

addresses is an array of MX records, each with a priority and an exchange\nattribute (e.g. [{'priority': 10, 'exchange': 'mx.example.com'},...]).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolveTxt(domain, callback)", + "type": "method", + "name": "resolveTxt", + "desc": "

The same as dns.resolve(), but only for text queries (TXT records).\naddresses is an array of the text records available for domain (e.g.,\n['v=spf1 ip4:0.0.0.0 ~all']).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolveSrv(domain, callback)", + "type": "method", + "name": "resolveSrv", + "desc": "

The same as dns.resolve(), but only for service records (SRV records).\naddresses is an array of the SRV records available for domain. Properties\nof SRV records are priority, weight, port, and name (e.g.,\n[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.reverse(ip, callback)", + "type": "method", + "name": "reverse", + "desc": "

Reverse resolves an ip address to an array of domain names.\n\n

\n

The callback has arguments (err, domains).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "ip" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolveNs(domain, callback)", + "type": "method", + "name": "resolveNs", + "desc": "

The same as dns.resolve(), but only for name server records (NS records).\naddresses is an array of the name server records available for domain\n(e.g., ['ns1.example.com', 'ns2.example.com']).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "dns.resolveCname(domain, callback)", + "type": "method", + "name": "resolveCname", + "desc": "

The same as dns.resolve(), but only for canonical name records (CNAME\nrecords). addresses is an array of the canonical name records available for\ndomain (e.g., ['bar.example.com']).\n\n

\n

If there an an error, err will be non-null and an instanceof the Error\nobject.\n\n

\n

Each DNS query can return an error code.\n\n

\n
    \n
  • dns.TEMPFAIL: timeout, SERVFAIL or similar.
    • \n
  • dns.PROTOCOL: got garbled reply.
    • \n
  • dns.NXDOMAIN: domain does not exists.
    • \n
  • dns.NODATA: domain exists but no data of reqd type.
    • \n
  • dns.NOMEM: out of memory while processing.
    • \n
  • dns.BADQUERY: the query is malformed.
    • \n
\n", + "signatures": [ + { + "params": [ + { + "name": "domain" + }, + { + "name": "callback" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "DNS" + }, + { + "textRaw": "HTTP", + "name": "http", + "stability": 3, + "stabilityText": "Stable", + "desc": "

To use the HTTP server and client one must require('http').\n\n

\n

The HTTP interfaces in Node are designed to support many features\nof the protocol which have been traditionally difficult to use.\nIn particular, large, possibly chunk-encoded, messages. The interface is\ncareful to never buffer entire requests or responses--the\nuser is able to stream data.\n\n

\n

HTTP message headers are represented by an object like this:\n\n

\n
{ 'content-length': '123',\n  'content-type': 'text/plain',\n  'connection': 'keep-alive',\n  'accept': '*/*' }
\n

Keys are lowercased. Values are not modified.\n\n

\n

In order to support the full spectrum of possible HTTP applications, Node's\nHTTP API is very low-level. It deals with stream handling and message\nparsing only. It parses a message into headers and body but it does not\nparse the actual headers or the body.\n\n\n

\n", + "methods": [ + { + "textRaw": "http.createServer([requestListener])", + "type": "method", + "name": "createServer", + "desc": "

Returns a new web server object.\n\n

\n

The requestListener is a function which is automatically\nadded to the 'request' event.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "requestListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "http.request(options, callback)", + "type": "method", + "name": "request", + "desc": "

Node maintains several connections per server to make HTTP requests.\nThis function allows one to transparently issue requests. options align\nwith url.parse().\n\n

\n

Options:\n\n

\n
    \n
  • host: A domain name or IP address of the server to issue the request to.\nDefaults to 'localhost'.
    • \n
  • hostname: To support url.parse() hostname is preferred over host
    • \n
  • port: Port of remote server. Defaults to 80.
    • \n
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • \n
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • \n
  • path: Request path. Defaults to '/'. Should include query string if any.\nE.G. '/index.html?page=12'
    • \n
  • headers: An object containing request headers.
    • \n
  • auth: Basic authentication i.e. 'user:password' to compute an\nAuthorization header.
    • \n
  • agent: Controls Agent behavior. When an Agent is used\nrequest will default to Connection: keep-alive. Possible values:
      \n
    • undefined (default): use global Agent for this host\nand port.
      • \n
    • Agent object: explicitly use the passed in Agent.
      • \n
    • false: opts out of connection pooling with an Agent, defaults request to\nConnection: close.
      • \n
    \n
    • \n
\n

http.request() returns an instance of the http.ClientRequest\nclass. The ClientRequest instance is a writable stream. If one needs to\nupload a file with a POST request, then write to the ClientRequest object.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'www.google.com',\n  port: 80,\n  path: '/upload',\n  method: 'POST'\n};\n\nvar req = http.request(options, function(res) {\n  console.log('STATUS: ' + res.statusCode);\n  console.log('HEADERS: ' + JSON.stringify(res.headers));\n  res.setEncoding('utf8');\n  res.on('data', function (chunk) {\n    console.log('BODY: ' + chunk);\n  });\n});\n\nreq.on('error', function(e) {\n  console.log('problem with request: ' + e.message);\n});\n\n// write data to request body\nreq.write('data\\n');\nreq.write('data\\n');\nreq.end();
\n

Note that in the example req.end() was called. With http.request() one\nmust always call req.end() to signify that you're done with the request -\neven if there is no data being written to the request body.\n\n

\n

If any error is encountered during the request (be that with DNS resolution,\nTCP level errors, or actual HTTP parse errors) an 'error' event is emitted\non the returned request object.\n\n

\n

There are a few special headers that should be noted.\n\n

\n
    \n

  • Sending a 'Connection: keep-alive' will notify Node that the connection to\nthe server should be persisted until the next request.

    \n
    • \n

  • Sending a 'Content-length' header will disable the default chunked encoding.

    \n
    • \n

  • Sending an 'Expect' header will immediately send the request headers.\nUsually, when sending 'Expect: 100-continue', you should both set a timeout\nand listen for the continue event. See RFC2616 Section 8.2.3 for more\ninformation.

    \n
    • \n

  • Sending an Authorization header will override using the auth option\nto compute basic authentication.

    \n
    • \n
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "http.get(options, callback)", + "type": "method", + "name": "get", + "desc": "

Since most requests are GET requests without bodies, Node provides this\nconvenience method. The only difference between this method and http.request() is\nthat it sets the method to GET and calls req.end() automatically.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'www.google.com',\n  port: 80,\n  path: '/index.html'\n};\n\nhttp.get(options, function(res) {\n  console.log("Got response: " + res.statusCode);\n}).on('error', function(e) {\n  console.log("Got error: " + e.message);\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "callback" + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: http.Server", + "type": "class", + "name": "http.Server", + "desc": "

This is an EventEmitter with the following events:\n\n

\n", + "events": [ + { + "textRaw": "Event: 'request'", + "type": "event", + "name": "request", + "desc": "

function (request, response) { }\n\n

\n

Emitted each time there is a request. Note that there may be multiple requests\nper connection (in the case of keep-alive connections).\n request is an instance of http.ServerRequest and response is\n an instance of http.ServerResponse\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'connection'", + "type": "event", + "name": "connection", + "desc": "

function (socket) { }\n\n

\n

When a new TCP stream is established. socket is an object of type\n net.Socket. Usually users will not want to access this event. The\n socket can also be accessed at request.connection.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () { }\n\n

\n

Emitted when the server closes.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'checkContinue'", + "type": "event", + "name": "checkContinue", + "desc": "

function (request, response) { }\n\n

\n

Emitted each time a request with an http Expect: 100-continue is received.\nIf this event isn't listened for, the server will automatically respond\nwith a 100 Continue as appropriate.\n\n

\n

Handling this event involves calling response.writeContinue if the client\nshould continue to send the request body, or generating an appropriate HTTP\nresponse (e.g., 400 Bad Request) if the client should not continue to send the\nrequest body.\n\n

\n

Note that when this event is emitted and handled, the request event will\nnot be emitted.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'upgrade'", + "type": "event", + "name": "upgrade", + "desc": "

function (request, socket, head) { }\n\n

\n

Emitted each time a client requests a http upgrade. If this event isn't\nlistened for, then clients requesting an upgrade will have their connections\nclosed.\n\n

\n
    \n
  • request is the arguments for the http request, as it is in the request event.
    • \n
  • socket is the network socket between the server and client.
    • \n
  • head is an instance of Buffer, the first packet of the upgraded stream, this may be empty.
    • \n
\n

After this event is emitted, the request's socket will not have a data\nevent listener, meaning you will need to bind to it in order to handle data\nsent to the server on that socket.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'clientError'", + "type": "event", + "name": "clientError", + "desc": "

function (exception) { }\n\n

\n

If a client connection emits an 'error' event - it will forwarded here.\n\n

\n", + "params": [] + } + ], + "methods": [ + { + "textRaw": "server.listen(port, [hostname], [callback])", + "type": "method", + "name": "listen", + "desc": "

Begin accepting connections on the specified port and hostname. If the\nhostname is omitted, the server will accept connections directed to any\nIPv4 address (INADDR_ANY).\n\n

\n

To listen to a unix socket, supply a filename instead of port and hostname.\n\n

\n

This function is asynchronous. The last parameter callback will be added as\na listener for the 'listening' event.\nSee also net.Server.listen().\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "port" + }, + { + "name": "hostname", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "server.listen(path, [callback])", + "type": "method", + "name": "listen", + "desc": "

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

\n

This function is asynchronous. The last parameter callback will be added as\na listener for the 'listening' event.\nSee also net.Server.listen().\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "server.close()", + "type": "method", + "name": "close", + "desc": "

Stops the server from accepting new connections.\nSee net.Server.close().\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + }, + { + "textRaw": "Class: http.ServerRequest", + "type": "class", + "name": "http.ServerRequest", + "desc": "

This object is created internally by a HTTP server -- not by\nthe user -- and passed as the first argument to a 'request' listener.\n\n

\n

The request implements the Readable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", + "events": [ + { + "textRaw": "Event: 'data'", + "type": "event", + "name": "data", + "desc": "

function (chunk) { }\n\n

\n

Emitted when a piece of the message body is received. The chunk is a string if\nan encoding has been set with request.setEncoding(), otherwise it's a\nBuffer.\n\n

\n

Note that the data will be lost if there is no listener when a\nServerRequest emits a 'data' event.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'end'", + "type": "event", + "name": "end", + "desc": "

function () { }\n\n

\n

Emitted exactly once for each request. After that, no more 'data' events\nwill be emitted on the request.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () { }\n\n

\n

Indicates that the underlaying connection was terminated before\nresponse.end() was called or able to flush.\n\n

\n

Just like 'end', this event occurs only once per request, and no more 'data'\nevents will fire afterwards.\n\n

\n

Note: 'close' can fire after 'end', but not vice versa.\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "request.method", + "name": "method", + "desc": "

The request method as a string. Read only. Example:\n'GET', 'DELETE'.\n\n\n

\n" + }, + { + "textRaw": "request.url", + "name": "url", + "desc": "

Request URL string. This contains only the URL that is\npresent in the actual HTTP request. If the request is:\n\n

\n
GET /status?name=ryan HTTP/1.1\\r\\n\nAccept: text/plain\\r\\n\n\\r\\n
\n

Then request.url will be:\n\n

\n
'/status?name=ryan'
\n

If you would like to parse the URL into its parts, you can use\nrequire('url').parse(request.url). Example:\n\n

\n
node> require('url').parse('/status?name=ryan')\n{ href: '/status?name=ryan',\n  search: '?name=ryan',\n  query: 'name=ryan',\n  pathname: '/status' }
\n

If you would like to extract the params from the query string,\nyou can use the require('querystring').parse function, or pass\ntrue as the second argument to require('url').parse. Example:\n\n

\n
node> require('url').parse('/status?name=ryan', true)\n{ href: '/status?name=ryan',\n  search: '?name=ryan',\n  query: { name: 'ryan' },\n  pathname: '/status' }
\n" + }, + { + "textRaw": "request.headers", + "name": "headers", + "desc": "

Read only.\n\n

\n" + }, + { + "textRaw": "request.trailers", + "name": "trailers", + "desc": "

Read only; HTTP trailers (if present). Only populated after the 'end' event.\n\n

\n" + }, + { + "textRaw": "request.httpVersion", + "name": "httpVersion", + "desc": "

The HTTP protocol version as a string. Read only. Examples:\n'1.1', '1.0'.\nAlso request.httpVersionMajor is the first integer and\nrequest.httpVersionMinor is the second.\n\n\n

\n" + }, + { + "textRaw": "request.connection", + "name": "connection", + "desc": "

The net.Socket object associated with the connection.\n\n\n

\n

With HTTPS support, use request.connection.verifyPeer() and\nrequest.connection.getPeerCertificate() to obtain the client's\nauthentication details.\n\n\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "request.setEncoding([encoding])", + "type": "method", + "name": "setEncoding", + "desc": "

Set the encoding for the request body. Either 'utf8' or 'binary'. Defaults\nto null, which means that the 'data' event will emit a Buffer object..\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "request.pause()", + "type": "method", + "name": "pause", + "desc": "

Pauses request from emitting events. Useful to throttle back an upload.\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "request.resume()", + "type": "method", + "name": "resume", + "desc": "

Resumes a paused request.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + }, + { + "textRaw": "Class: http.ServerResponse", + "type": "class", + "name": "http.ServerResponse", + "desc": "

This object is created internally by a HTTP server--not by the user. It is\npassed as the second parameter to the 'request' event.\n\n

\n

The response implements the Writable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", + "events": [ + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () { }\n\n

\n

Indicates that the underlaying connection was terminated before\nresponse.end() was called or able to flush.\n\n

\n", + "params": [] + } + ], + "methods": [ + { + "textRaw": "response.writeContinue()", + "type": "method", + "name": "writeContinue", + "desc": "

Sends a HTTP/1.1 100 Continue message to the client, indicating that\nthe request body should be sent. See the checkContinue event on\nServer.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "response.writeHead(statusCode, [reasonPhrase], [headers])", + "type": "method", + "name": "writeHead", + "desc": "

Sends a response header to the request. The status code is a 3-digit HTTP\nstatus code, like 404. The last argument, headers, are the response headers.\nOptionally one can give a human-readable reasonPhrase as the second\nargument.\n\n

\n

Example:\n\n

\n
var body = 'hello world';\nresponse.writeHead(200, {\n  'Content-Length': body.length,\n  'Content-Type': 'text/plain' });
\n

This method must only be called once on a message and it must\nbe called before response.end() is called.\n\n

\n

If you call response.write() or response.end() before calling this, the\nimplicit/mutable headers will be calculated and call this function for you.\n\n

\n

Note: that Content-Length is given in bytes not characters. The above example\nworks because the string 'hello world' contains only single byte characters.\nIf the body contains higher coded characters then Buffer.byteLength()\nshould be used to determine the number of bytes in a given encoding.\nAnd Node does not check whether Content-Length and the length of the body\nwhich has been transmitted are equal or not.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "statusCode" + }, + { + "name": "reasonPhrase", + "optional": true + }, + { + "name": "headers", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "response.setHeader(name, value)", + "type": "method", + "name": "setHeader", + "desc": "

Sets a single header value for implicit headers. If this header already exists\nin the to-be-sent headers, its value will be replaced. Use an array of strings\nhere if you need to send multiple headers with the same name.\n\n

\n

Example:\n\n

\n
response.setHeader("Content-Type", "text/html");
\n

or\n\n

\n
response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]);
\n", + "signatures": [ + { + "params": [ + { + "name": "name" + }, + { + "name": "value" + } + ] + } + ] + }, + { + "textRaw": "response.getHeader(name)", + "type": "method", + "name": "getHeader", + "desc": "

Reads out a header that's already been queued but not sent to the client. Note\nthat the name is case insensitive. This can only be called before headers get\nimplicitly flushed.\n\n

\n

Example:\n\n

\n
var contentType = response.getHeader('content-type');
\n", + "signatures": [ + { + "params": [ + { + "name": "name" + } + ] + } + ] + }, + { + "textRaw": "response.removeHeader(name)", + "type": "method", + "name": "removeHeader", + "desc": "

Removes a header that's queued for implicit sending.\n\n

\n

Example:\n\n

\n
response.removeHeader("Content-Encoding");
\n", + "signatures": [ + { + "params": [ + { + "name": "name" + } + ] + } + ] + }, + { + "textRaw": "response.write(chunk, [encoding])", + "type": "method", + "name": "write", + "desc": "

If this method is called and response.writeHead() has not been called, it will\nswitch to implicit header mode and flush the implicit headers.\n\n

\n

This sends a chunk of the response body. This method may\nbe called multiple times to provide successive parts of the body.\n\n

\n

chunk can be a string or a buffer. If chunk is a string,\nthe second parameter specifies how to encode it into a byte stream.\nBy default the encoding is 'utf8'.\n\n

\n

Note: This is the raw HTTP body and has nothing to do with\nhigher-level multi-part body encodings that may be used.\n\n

\n

The first time response.write() is called, it will send the buffered\nheader information and the first body to the client. The second time\nresponse.write() is called, Node assumes you're going to be streaming\ndata, and sends that separately. That is, the response is buffered up to the\nfirst chunk of body.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "chunk" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "response.addTrailers(headers)", + "type": "method", + "name": "addTrailers", + "desc": "

This method adds HTTP trailing headers (a header but at the end of the\nmessage) to the response.\n\n

\n

Trailers will only be emitted if chunked encoding is used for the\nresponse; if it is not (e.g., if the request was HTTP/1.0), they will\nbe silently discarded.\n\n

\n

Note that HTTP requires the Trailer header to be sent if you intend to\nemit trailers, with a list of the header fields in its value. E.g.,\n\n

\n
response.writeHead(200, { 'Content-Type': 'text/plain',\n                          'Trailer': 'Content-MD5' });\nresponse.write(fileData);\nresponse.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});\nresponse.end();
\n", + "signatures": [ + { + "params": [ + { + "name": "headers" + } + ] + } + ] + }, + { + "textRaw": "response.end([data], [encoding])", + "type": "method", + "name": "end", + "desc": "

This method signals to the server that all of the response headers and body\nhas been sent; that server should consider this message complete.\nThe method, response.end(), MUST be called on each\nresponse.\n\n

\n

If data is specified, it is equivalent to calling response.write(data, encoding)\nfollowed by response.end().\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data", + "optional": true + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + } + ], + "properties": [ + { + "textRaw": "response.statusCode", + "name": "statusCode", + "desc": "

When using implicit headers (not calling response.writeHead() explicitly), this property\ncontrols the status code that will be send to the client when the headers get\nflushed.\n\n

\n

Example:\n\n

\n
response.statusCode = 404;
\n

After response header was sent to the client, this property indicates the\nstatus code which was sent out.\n\n

\n" + } + ] + }, + { + "textRaw": "Class: http.Agent", + "type": "class", + "name": "http.Agent", + "desc": "

In node 0.5.3+ there is a new implementation of the HTTP Agent which is used\nfor pooling sockets used in HTTP client requests.\n\n

\n

Previously, a single agent instance help the pool for single host+port. The\ncurrent implementation now holds sockets for any number of hosts.\n\n

\n

The current HTTP Agent also defaults client requests to using\nConnection:keep-alive. If no pending HTTP requests are waiting on a socket\nto become free the socket is closed. This means that node's pool has the\nbenefit of keep-alive when under load but still does not require developers\nto manually close the HTTP clients using keep-alive.\n\n

\n

Sockets are removed from the agent's pool when the socket emits either a\n"close" event or a special "agentRemove" event. This means that if you intend\nto keep one HTTP request open for a long time and don't want it to stay in the\npool you can do something along the lines of:\n\n

\n
http.get(options, function(res) {\n  // Do stuff\n}).on("socket", function (socket) {\n  socket.emit("agentRemove");\n});
\n

Alternatively, you could just opt out of pooling entirely using agent:false:\n\n

\n
http.get({host:'localhost', port:80, path:'/', agent:false}, function (res) {\n  // Do stuff\n})
\n", + "properties": [ + { + "textRaw": "agent.maxSockets", + "name": "maxSockets", + "desc": "

By default set to 5. Determines how many concurrent sockets the agent can have \nopen per host.\n\n

\n" + }, + { + "textRaw": "agent.sockets", + "name": "sockets", + "desc": "

An object which contains arrays of sockets currently in use by the Agent. Do not \nmodify.\n\n

\n" + }, + { + "textRaw": "agent.requests", + "name": "requests", + "desc": "

An object which contains queues of requests that have not yet been assigned to \nsockets. Do not modify.\n\n

\n" + } + ] + }, + { + "textRaw": "Class: http.ClientRequest", + "type": "class", + "name": "http.ClientRequest", + "desc": "

This object is created internally and returned from http.request(). It\nrepresents an in-progress request whose header has already been queued. The\nheader is still mutable using the setHeader(name, value), getHeader(name),\nremoveHeader(name) API. The actual header will be sent along with the first\ndata chunk or when closing the connection.\n\n

\n

To get the response, add a listener for 'response' to the request object.\n'response' will be emitted from the request object when the response\nheaders have been received. The 'response' event is executed with one\nargument which is an instance of http.ClientResponse.\n\n

\n

During the 'response' event, one can add listeners to the\nresponse object; particularly to listen for the 'data' event. Note that\nthe 'response' event is called before any part of the response body is received,\nso there is no need to worry about racing to catch the first part of the\nbody. As long as a listener for 'data' is added during the 'response'\nevent, the entire body will be caught.\n\n\n

\n
// Good\nrequest.on('response', function (response) {\n  response.on('data', function (chunk) {\n    console.log('BODY: ' + chunk);\n  });\n});\n\n// Bad - misses all or part of the body\nrequest.on('response', function (response) {\n  setTimeout(function () {\n    response.on('data', function (chunk) {\n      console.log('BODY: ' + chunk);\n    });\n  }, 10);\n});
\n

Note: Node does not check whether Content-Length and the length of the body\nwhich has been transmitted are equal or not.\n\n

\n

The request implements the Writable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", + "events": [ + { + "textRaw": "Event 'response'", + "type": "event", + "name": "response", + "desc": "

function (response) { }\n\n

\n

Emitted when a response is received to this request. This event is emitted only once. The\nresponse argument will be an instance of http.ClientResponse.\n\n

\n

Options:\n\n

\n
    \n
  • host: A domain name or IP address of the server to issue the request to.
    • \n
  • port: Port of remote server.
    • \n
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • \n
\n", + "params": [] + }, + { + "textRaw": "Event: 'socket'", + "type": "event", + "name": "socket", + "desc": "

function (socket) { }\n\n

\n

Emitted after a socket is assigned to this request.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'upgrade'", + "type": "event", + "name": "upgrade", + "desc": "

function (response, socket, head) { }\n\n

\n

Emitted each time a server responds to a request with an upgrade. If this\nevent isn't being listened for, clients receiving an upgrade header will have\ntheir connections closed.\n\n

\n

A client server pair that show you how to listen for the upgrade event using http.getAgent:\n\n

\n
var http = require('http');\nvar net = require('net');\n\n// Create an HTTP server\nvar srv = http.createServer(function (req, res) {\n  res.writeHead(200, {'Content-Type': 'text/plain'});\n  res.end('okay');\n});\nsrv.on('upgrade', function(req, socket, upgradeHead) {\n  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\\r\\n' +\n               'Upgrade: WebSocket\\r\\n' +\n               'Connection: Upgrade\\r\\n' +\n               '\\r\\n\\r\\n');\n\n  socket.ondata = function(data, start, end) {\n    socket.write(data.toString('utf8', start, end), 'utf8'); // echo back\n  };\n});\n\n// now that server is running\nsrv.listen(1337, '127.0.0.1', function() {\n\n  // make a request\n  var options = {\n    port: 1337,\n    host: '127.0.0.1',\n    headers: {\n      'Connection': 'Upgrade',\n      'Upgrade': 'websocket'\n    }\n  };\n\n  var req = http.request(options);\n  req.end();\n\n  req.on('upgrade', function(res, socket, upgradeHead) {\n    console.log('got upgraded!');\n    socket.end();\n    process.exit(0);\n  });\n});
\n", + "params": [] + }, + { + "textRaw": "Event: 'continue'", + "type": "event", + "name": "continue", + "desc": "

function () { }\n\n

\n

Emitted when the server sends a '100 Continue' HTTP response, usually because\nthe request contained 'Expect: 100-continue'. This is an instruction that\nthe client should send the request body.\n\n

\n", + "params": [] + } + ], + "methods": [ + { + "textRaw": "request.write(chunk, [encoding])", + "type": "method", + "name": "write", + "desc": "

Sends a chunk of the body. By calling this method\nmany times, the user can stream a request body to a\nserver--in that case it is suggested to use the\n['Transfer-Encoding', 'chunked'] header line when\ncreating the request.\n\n

\n

The chunk argument should be a buffer or a string.\n\n

\n

The encoding argument is optional and only applies when chunk is a string.\nDefaults to 'utf8'.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "chunk" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "request.end([data], [encoding])", + "type": "method", + "name": "end", + "desc": "

Finishes sending the request. If any parts of the body are\nunsent, it will flush them to the stream. If the request is\nchunked, this will send the terminating '0\\r\\n\\r\\n'.\n\n

\n

If data is specified, it is equivalent to calling\nrequest.write(data, encoding) followed by request.end().\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data", + "optional": true + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "request.abort()", + "type": "method", + "name": "abort", + "desc": "

Aborts a request. (New since v0.3.8.)\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "request.setTimeout(timeout, [callback])", + "type": "method", + "name": "setTimeout", + "desc": "

Once a socket is assigned to this request and is connected \nsocket.setTimeout(timeout, [callback])\nwill be called.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "timeout" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "request.setNoDelay([noDelay])", + "type": "method", + "name": "setNoDelay", + "desc": "

Once a socket is assigned to this request and is connected \nsocket.setNoDelay(noDelay)\nwill be called.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "noDelay", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "request.setSocketKeepAlive([enable], [initialDelay])", + "type": "method", + "name": "setSocketKeepAlive", + "desc": "

Once a socket is assigned to this request and is connected \nsocket.setKeepAlive(enable, [initialDelay])\nwill be called.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "enable", + "optional": true + }, + { + "name": "initialDelay", + "optional": true + } + ] + } + ] + } + ] + } + ], + "properties": [ + { + "textRaw": "http.globalAgent", + "name": "globalAgent", + "desc": "

Global instance of Agent which is used as the default for all http client\nrequests.\n\n\n

\n" + }, + { + "textRaw": "http.ClientResponse", + "name": "ClientResponse", + "desc": "

This object is created when making a request with http.request(). It is\npassed to the 'response' event of the request object.\n\n

\n

The response implements the Readable Stream\ninterface. This is an EventEmitter with the following events:\n\n\n

\n", + "events": [ + { + "textRaw": "Event: 'data'", + "type": "event", + "name": "data", + "desc": "

function (chunk) { }\n\n

\n

Emitted when a piece of the message body is received.\n\n

\n

Note that the data will be lost if there is no listener when a\nClientResponse emits a 'data' event.\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'end'", + "type": "event", + "name": "end", + "desc": "

function () { }\n\n

\n

Emitted exactly once for each message. No arguments. After\nemitted no other events will be emitted on the response.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function (err) { }\n\n

\n

Indicates that the underlaying connection was terminated before\nend event was emitted.\nSee http.ServerRequest's 'close' event for more\ninformation.\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "response.statusCode", + "name": "statusCode", + "desc": "

The 3-digit HTTP response status code. E.G. 404.\n\n

\n" + }, + { + "textRaw": "response.httpVersion", + "name": "httpVersion", + "desc": "

The HTTP version of the connected-to server. Probably either\n'1.1' or '1.0'.\nAlso response.httpVersionMajor is the first integer and\nresponse.httpVersionMinor is the second.\n\n

\n" + }, + { + "textRaw": "response.headers", + "name": "headers", + "desc": "

The response headers object.\n\n

\n" + }, + { + "textRaw": "response.trailers", + "name": "trailers", + "desc": "

The response trailers object. Only populated after the 'end' event.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "response.setEncoding([encoding])", + "type": "method", + "name": "setEncoding", + "desc": "

Set the encoding for the response body. Either 'utf8', 'ascii', or\n'base64'. Defaults to null, which means that the 'data' event will emit\na Buffer object.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "response.pause()", + "type": "method", + "name": "pause", + "desc": "

Pauses response from emitting events. Useful to throttle back a download.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "response.resume()", + "type": "method", + "name": "resume", + "desc": "

Resumes a paused response.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + } + ], + "type": "module", + "displayName": "HTTP" + }, + { + "textRaw": "HTTPS", + "name": "https", + "stability": 3, + "stabilityText": "Stable", + "desc": "

HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a\nseparate module.\n\n

\n", + "classes": [ + { + "textRaw": "Class: https.Server", + "type": "class", + "name": "https.Server", + "desc": "

This class is a subclass of tls.Server and emits events same as\nhttp.Server. See http.Server for more information.\n\n

\n" + }, + { + "textRaw": "Class: https.Agent", + "type": "class", + "name": "https.Agent", + "desc": "

An Agent object for HTTPS similar to http.Agent.\nSee https.request() for more information.\n\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "https.createServer(options, [requestListener])", + "type": "method", + "name": "createServer", + "desc": "

Returns a new HTTPS web server object. The options is similar to\ntls.createServer(). The requestListener is a function which is\nautomatically added to the 'request' event.\n\n

\n

Example:\n\n

\n
// curl -k https://localhost:8000/\nvar https = require('https');\nvar fs = require('fs');\n\nvar options = {\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\n\nhttps.createServer(options, function (req, res) {\n  res.writeHead(200);\n  res.end("hello world\\n");\n}).listen(8000);
\n

Or\n\n

\n
var https = require('https');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('server.pfx')\n};\n\nhttps.createServer(options, function (req, res) {\n  res.writeHead(200);\n  res.end("hello world\\n");\n}).listen(8000);
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "requestListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "https.request(options, callback)", + "type": "method", + "name": "request", + "desc": "

Makes a request to a secure web server.\nAll options from http.request() are valid.\n\n

\n

Example:\n\n

\n
var https = require('https');\n\nvar options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET'\n};\n\nvar req = https.request(options, function(res) {\n  console.log("statusCode: ", res.statusCode);\n  console.log("headers: ", res.headers);\n\n  res.on('data', function(d) {\n    process.stdout.write(d);\n  });\n});\nreq.end();\n\nreq.on('error', function(e) {\n  console.error(e);\n});
\n

The options argument has the following options\n\n

\n
    \n
  • host: IP or domain of host to make request to. Defaults to 'localhost'.
    • \n
  • port: port of host to request to. Defaults to 443.
    • \n
  • path: Path to request. Default '/'.
    • \n

  • method: HTTP request method. Default 'GET'.

    \n
    • \n

  • host: A domain name or IP address of the server to issue the request to.\nDefaults to 'localhost'.

    \n
    • \n
  • hostname: To support url.parse() hostname is preferred over host
    • \n
  • port: Port of remote server. Defaults to 443.
    • \n
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • \n
  • path: Request path. Defaults to '/'. Should include query string if any.\nE.G. '/index.html?page=12'
    • \n
  • headers: An object containing request headers.
    • \n
  • auth: Basic authentication i.e. 'user:password' to compute an\nAuthorization header.
    • \n
  • agent: Controls Agent behavior. When an Agent is\nused request will default to Connection: keep-alive. Possible values:
      \n
    • undefined (default): use globalAgent for this\nhost and port.
      • \n
    • Agent object: explicitly use the passed in Agent.
      • \n
    • false: opts out of connection pooling with an Agent, defaults request to\nConnection: close.
      • \n
    \n
    • \n
\n

The following options from tls.connect() can also be\nspecified. However, a globalAgent silently ignores these.\n\n

\n
    \n
  • pfx: Certificate, Private key and CA certificates to use for SSL. Default null.
    • \n
  • key: Private key to use for SSL. Default null.
    • \n
  • passphrase: A string of passphrase for the private key or pfx. Default null.
    • \n
  • cert: Public x509 certificate to use. Default null.
    • \n
  • ca: An authority certificate or array of authority certificates to check\nthe remote host against.
    • \n
\n

In order to specify these options, use a custom Agent.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\noptions.agent = new https.Agent(options);\n\nvar req = https.request(options, function(res) {\n  ...\n}
\n

Or does not use an Agent.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),\n  agent: false\n};\n\nvar req = https.request(options, function(res) {\n  ...\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "https.get(options, callback)", + "type": "method", + "name": "get", + "desc": "

Like http.get() but for HTTPS.\n\n

\n

Example:\n\n

\n
var https = require('https');\n\nhttps.get({ host: 'encrypted.google.com', path: '/' }, function(res) {\n  console.log("statusCode: ", res.statusCode);\n  console.log("headers: ", res.headers);\n\n  res.on('data', function(d) {\n    process.stdout.write(d);\n  });\n\n}).on('error', function(e) {\n  console.error(e);\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "callback" + } + ] + } + ] + } + ], + "properties": [ + { + "textRaw": "https.globalAgent", + "name": "globalAgent", + "desc": "

Global instance of https.Agent which is used as the default\nfor all HTTPS client requests.\n\n

\n" + } + ], + "type": "module", + "displayName": "HTTPS" + }, + { + "textRaw": "URL", + "name": "url", + "stability": 3, + "stabilityText": "Stable", + "desc": "

This module has utilities for URL resolution and parsing.\nCall require('url') to use it.\n\n

\n

Parsed URL objects have some or all of the following fields, depending on\nwhether or not they exist in the URL string. Any parts that are not in the URL\nstring will not be in the parsed object. Examples are shown for the URL\n\n

\n

'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'\n\n

\n
    \n

  • href: The full URL that was originally parsed. Both the protocol and host are lowercased.

    \n

    Example: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

    \n
    • \n

  • protocol: The request protocol, lowercased.

    \n

    Example: 'http:'

    \n
    • \n

  • host: The full lowercased host portion of the URL, including port\ninformation.

    \n

    Example: 'host.com:8080'

    \n
    • \n

  • auth: The authentication information portion of a URL.

    \n

    Example: 'user:pass'

    \n
    • \n

  • hostname: Just the lowercased hostname portion of the host.

    \n

    Example: 'host.com'

    \n
    • \n

  • port: The port number portion of the host.

    \n

    Example: '8080'

    \n
    • \n

  • pathname: The path section of the URL, that comes after the host and\nbefore the query, including the initial slash if present.

    \n

    Example: '/p/a/t/h'

    \n
    • \n

  • search: The 'query string' portion of the URL, including the leading\nquestion mark.

    \n

    Example: '?query=string'

    \n
    • \n

  • path: Concatenation of pathname and search.

    \n

    Example: '/p/a/t/h?query=string'

    \n
    • \n

  • query: Either the 'params' portion of the query string, or a\nquerystring-parsed object.

    \n

    Example: 'query=string' or {'query':'string'}

    \n
    • \n

  • hash: The 'fragment' portion of the URL including the pound-sign.

    \n

    Example: '#hash'

    \n
    • \n
\n

The following methods are provided by the URL module:\n\n

\n", + "methods": [ + { + "textRaw": "url.parse(urlStr, [parseQueryString], [slashesDenoteHost])", + "type": "method", + "name": "parse", + "desc": "

Take a URL string, and return an object.\n\n

\n

Pass true as the second argument to also parse\nthe query string using the querystring module.\nDefaults to false.\n\n

\n

Pass true as the third argument to treat //foo/bar as\n{ host: 'foo', pathname: '/bar' } rather than\n{ pathname: '//foo/bar' }. Defaults to false.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "urlStr" + }, + { + "name": "parseQueryString", + "optional": true + }, + { + "name": "slashesDenoteHost", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "url.format(urlObj)", + "type": "method", + "name": "format", + "desc": "

Take a parsed URL object, and return a formatted URL string.\n\n

\n
    \n
  • href will be ignored.
    • \n
  • protocolis treated the same with or without the trailing : (colon).
      \n
    • The protocols http, https, ftp, gopher, file will be\npostfixed with :// (colon-slash-slash).
      • \n
    • All other protocols mailto, xmpp, aim, sftp, foo, etc will\nbe postfixed with : (colon)
      • \n
    \n
    • \n
  • auth will be used if present.
    • \n
  • hostname will only be used if host is absent.
    • \n
  • port will only be used if host is absent.
    • \n
  • host will be used in place of auth, hostname, and port
    • \n
  • pathname is treated the same with or without the leading / (slash)
    • \n
  • search will be used in place of query
    • \n
  • query (object; see querystring) will only be used if search is absent.
    • \n
  • search is treated the same with or without the leading ? (question mark)
    • \n
  • hash is treated the same with or without the leading # (pound sign, anchor)
    • \n
\n", + "signatures": [ + { + "params": [ + { + "name": "urlObj" + } + ] + } + ] + }, + { + "textRaw": "url.resolve(from, to)", + "type": "method", + "name": "resolve", + "desc": "

Take a base URL, and a href URL, and resolve them as a browser would for\nan anchor tag.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "from" + }, + { + "name": "to" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "URL" + }, + { + "textRaw": "Query String", + "name": "querystring", + "stability": 3, + "stabilityText": "Stable", + "desc": "

This module provides utilities for dealing with query strings.\nIt provides the following methods:\n\n

\n", + "methods": [ + { + "textRaw": "querystring.stringify(obj, [sep], [eq])", + "type": "method", + "name": "stringify", + "desc": "

Serialize an object to a query string.\nOptionally override the default separator ('&') and assignment ('=')\ncharacters.\n\n

\n

Example:\n\n

\n
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })\n// returns\n'foo=bar&baz=qux&baz=quux&corge='\n\nquerystring.stringify({foo: 'bar', baz: 'qux'}, ';', ':')\n// returns\n'foo:bar;baz:qux'
\n", + "signatures": [ + { + "params": [ + { + "name": "obj" + }, + { + "name": "sep", + "optional": true + }, + { + "name": "eq", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "querystring.parse(str, [sep], [eq])", + "type": "method", + "name": "parse", + "desc": "

Deserialize a query string to an object.\nOptionally override the default separator ('&') and assignment ('=')\ncharacters.\n\n

\n

Example:\n\n

\n
querystring.parse('foo=bar&baz=qux&baz=quux&corge')\n// returns\n{ foo: 'bar', baz: ['qux', 'quux'], corge: '' }
\n", + "signatures": [ + { + "params": [ + { + "name": "str" + }, + { + "name": "sep", + "optional": true + }, + { + "name": "eq", + "optional": true + } + ] + } + ] + } + ], + "properties": [ + { + "textRaw": "querystring.escape", + "name": "escape", + "desc": "

The escape function used by querystring.stringify,\nprovided so that it could be overridden if necessary.\n\n

\n" + }, + { + "textRaw": "querystring.unescape", + "name": "unescape", + "desc": "

The unescape function used by querystring.parse,\nprovided so that it could be overridden if necessary.\n\n

\n" + } + ], + "type": "module", + "displayName": "querystring" + }, + { + "textRaw": "Readline", + "name": "readline", + "stability": 3, + "stabilityText": "Stable", + "desc": "

To use this module, do require('readline'). Readline allows reading of a\nstream (such as STDIN) on a line-by-line basis.\n\n

\n

Note that once you've invoked this module, your node program will not\nterminate until you've closed the interface, and the STDIN stream. Here's how\nto allow your program to gracefully terminate:\n\n

\n
var rl = require('readline');\n\nvar i = rl.createInterface(process.stdin, process.stdout, null);\ni.question("What do you think of node.js?", function(answer) {\n  // TODO: Log the answer in a database\n  console.log("Thank you for your valuable feedback.");\n\n  // These two lines together allow the program to terminate. Without\n  // them, it would run forever.\n  i.close();\n  process.stdin.destroy();\n});
\n", + "methods": [ + { + "textRaw": "rl.createInterface(input, output, completer)", + "type": "method", + "name": "createInterface", + "desc": "

Takes two streams and creates a readline interface. The completer function\nis used for autocompletion. When given a substring, it returns [[substr1,\nsubstr2, ...], originalsubstring].\n\n

\n

Also completer can be run in async mode if it accepts two arguments:\n\n

\n

function completer(linePartial, callback) {\n callback(null, [['123'], linePartial]);\n }\n\n

\n

createInterface is commonly used with process.stdin and\nprocess.stdout in order to accept user input:\n\n

\n
var readline = require('readline'),\n  rl = readline.createInterface(process.stdin, process.stdout);
\n", + "signatures": [ + { + "params": [ + { + "name": "input" + }, + { + "name": "output" + }, + { + "name": "completer" + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: Interface", + "type": "class", + "name": "Interface", + "desc": "

The class that represents a readline interface with a stdin and stdout\nstream.\n\n

\n", + "methods": [ + { + "textRaw": "rl.setPrompt(prompt, length)", + "type": "method", + "name": "setPrompt", + "desc": "

Sets the prompt, for example when you run node on the command line, you see\n> , which is node's prompt.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "prompt" + }, + { + "name": "length" + } + ] + } + ] + }, + { + "textRaw": "rl.prompt()", + "type": "method", + "name": "prompt", + "desc": "

Readies readline for input from the user, putting the current setPrompt\noptions on a new line, giving the user a new spot to write.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "rl.question(query, callback)", + "type": "method", + "name": "question", + "desc": "

Prepends the prompt with query and invokes callback with the user's\nresponse. Displays the query to the user, and then invokes callback with the\nuser's response after it has been typed.\n\n

\n

Example usage:\n\n

\n
interface.question('What is your favorite food?', function(answer) {\n  console.log('Oh, so your favorite food is ' + answer);\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "query" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "rl.close()", + "type": "method", + "name": "close", + "desc": "

Closes tty.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "rl.pause()", + "type": "method", + "name": "pause", + "desc": "

Pauses tty.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "rl.resume()", + "type": "method", + "name": "resume", + "desc": "

Resumes tty.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "rl.write()", + "type": "method", + "name": "write", + "desc": "

Writes to tty.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "events": [ + { + "textRaw": "Event: 'line'", + "type": "event", + "name": "line", + "desc": "

function (line) {}\n\n

\n

Emitted whenever the in stream receives a \\n, usually received when the\nuser hits enter, or return. This is a good hook to listen for user input.\n\n

\n

Example of listening for line:\n\n

\n
rl.on('line', function (cmd) {\n  console.log('You just typed: '+cmd);\n});
\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () {}\n\n

\n

Emitted whenever the in stream receives a ^C or ^D, respectively known\nas SIGINT and EOT. This is a good way to know the user is finished using\nyour program.\n\n

\n

Example of listening for close, and exiting the program afterward:\n\n

\n
rl.on('close', function() {\n  console.log('goodbye!');\n  process.exit(0);\n});
\n

Here's an example of how to use all these together to craft a tiny command\nline interface:\n\n

\n
var readline = require('readline'),\n  rl = readline.createInterface(process.stdin, process.stdout),\n  prefix = 'OHAI> ';\n\nrl.on('line', function(line) {\n  switch(line.trim()) {\n    case 'hello':\n      console.log('world!');\n      break;\n    default:\n      console.log('Say what? I might have heard `' + line.trim() + '`');\n      break;\n  }\n  rl.setPrompt(prefix, prefix.length);\n  rl.prompt();\n}).on('close', function() {\n  console.log('Have a great day!');\n  process.exit(0);\n});\nconsole.log(prefix + 'Good to see you. Try typing stuff.');\nrl.setPrompt(prefix, prefix.length);\nrl.prompt();
\n

Take a look at this slightly more complicated\nexample, and\nhttp-console for a real-life use\ncase.\n\n

\n", + "params": [] + } + ] + } + ], + "type": "module", + "displayName": "Readline" + }, + { + "textRaw": "REPL", + "name": "repl", + "desc": "

A Read-Eval-Print-Loop (REPL) is available both as a standalone program and easily\nincludable in other programs. REPL provides a way to interactively run\nJavaScript and see the results. It can be used for debugging, testing, or\njust trying things out.\n\n

\n

By executing node without any arguments from the command-line you will be\ndropped into the REPL. It has simplistic emacs line-editing.\n\n

\n
mjr:~$ node\nType '.help' for options.\n> a = [ 1, 2, 3];\n[ 1, 2, 3 ]\n> a.forEach(function (v) {\n...   console.log(v);\n...   });\n1\n2\n3
\n

For advanced line-editors, start node with the environmental variable NODE_NO_READLINE=1.\nThis will start the REPL in canonical terminal settings which will allow you to use with rlwrap.\n\n

\n

For example, you could add this to your bashrc file:\n\n

\n
alias node="env NODE_NO_READLINE=1 rlwrap node"
\n", + "methods": [ + { + "textRaw": "repl.start([prompt], [stream], [eval], [useGlobal], [ignoreUndefined])", + "type": "method", + "name": "start", + "desc": "

Starts a REPL with prompt as the prompt and stream for all I/O. prompt\nis optional and defaults to > . stream is optional and defaults to\nprocess.stdin. eval is optional too and defaults to async wrapper for\neval().\n\n

\n

If useGlobal is set to true, then the repl will use the global object,\ninstead of running scripts in a separate context. Defaults to false.\n\n

\n

If ignoreUndefined is set to true, then the repl will not output return value\nof command if it's undefined. Defaults to false.\n\n

\n

You can use your own eval function if it has following signature:\n\n

\n
function eval(cmd, callback) {\n  callback(null, result);\n}
\n

Multiple REPLs may be started against the same running instance of node. Each\nwill share the same global object but will have unique I/O.\n\n

\n

Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:\n\n

\n
var net = require("net"),\n    repl = require("repl");\n\nconnections = 0;\n\nrepl.start("node via stdin> ");\n\nnet.createServer(function (socket) {\n  connections += 1;\n  repl.start("node via Unix socket> ", socket);\n}).listen("/tmp/node-repl-sock");\n\nnet.createServer(function (socket) {\n  connections += 1;\n  repl.start("node via TCP socket> ", socket);\n}).listen(5001);
\n

Running this program from the command line will start a REPL on stdin. Other\nREPL clients may connect through the Unix socket or TCP socket. telnet is useful\nfor connecting to TCP sockets, and socat can be used to connect to both Unix and\nTCP sockets.\n\n

\n

By starting a REPL from a Unix socket-based server instead of stdin, you can\nconnect to a long-running node process without restarting it.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "prompt", + "optional": true + }, + { + "name": "stream", + "optional": true + }, + { + "name": "eval", + "optional": true + }, + { + "name": "useGlobal", + "optional": true + }, + { + "name": "ignoreUndefined", + "optional": true + } + ] + } + ] + } + ], + "miscs": [ + { + "textRaw": "REPL Features", + "name": "REPL Features", + "type": "misc", + "desc": "

Inside the REPL, Control+D will exit. Multi-line expressions can be input.\nTab completion is supported for both global and local variables.\n\n

\n

The special variable _ (underscore) contains the result of the last expression.\n\n

\n
> [ "a", "b", "c" ]\n[ 'a', 'b', 'c' ]\n> _.length\n3\n> _ += 1\n4
\n

The REPL provides access to any variables in the global scope. You can expose\na variable to the REPL explicitly by assigning it to the context object\nassociated with each REPLServer. For example:\n\n

\n
// repl_test.js\nvar repl = require("repl"),\n    msg = "message";\n\nrepl.start().context.m = msg;
\n

Things in the context object appear as local within the REPL:\n\n

\n
mjr:~$ node repl_test.js\n> m\n'message'
\n

There are a few special REPL commands:\n\n

\n
    \n
  • .break - While inputting a multi-line expression, sometimes you get lost\nor just don't care about completing it. .break will start over.
    • \n
  • .clear - Resets the context object to an empty object and clears any\nmulti-line expression.
    • \n
  • .exit - Close the I/O stream, which will cause the REPL to exit.
    • \n
  • .help - Show this list of special commands.
    • \n
  • .save - Save the current REPL session to a file
    \n

    .save ./file/to/save.js

    \n
    \n
    • \n
  • .load - Load a file into the current REPL session.
    \n

    .load ./file/to/load.js

    \n
    \n
    • \n
\n

The following key combinations in the REPL have these special effects:\n\n

\n
    \n
  • <ctrl>C - Similar to the .break keyword. Terminates the current\ncommand. Press twice on a blank line to forcibly exit.
    • \n
  • <ctrl>D - Similar to the .exit keyword.
    • \n
\n" + } + ], + "type": "module", + "displayName": "REPL" + }, + { + "textRaw": "Executing JavaScript", + "name": "vm", + "stability": 3, + "stabilityText": "Stable", + "desc": "

You can access this module with:\n\n

\n
var vm = require('vm');
\n

JavaScript code can be compiled and run immediately or compiled, saved, and run later.\n\n\n

\n", + "methods": [ + { + "textRaw": "vm.runInThisContext(code, [filename])", + "type": "method", + "name": "runInThisContext", + "desc": "

vm.runInThisContext() compiles code, runs it and returns the result. Running\ncode does not have access to local scope. filename is optional, it's used only\nin stack traces.\n\n

\n

Example of using vm.runInThisContext and eval to run the same code:\n\n

\n
var localVar = 123,\n    usingscript, evaled,\n    vm = require('vm');\n\nusingscript = vm.runInThisContext('localVar = 1;',\n  'myfile.vm');\nconsole.log('localVar: ' + localVar + ', usingscript: ' +\n  usingscript);\nevaled = eval('localVar = 1;');\nconsole.log('localVar: ' + localVar + ', evaled: ' +\n  evaled);\n\n// localVar: 123, usingscript: 1\n// localVar: 1, evaled: 1
\n

vm.runInThisContext does not have access to the local scope, so localVar is unchanged.\neval does have access to the local scope, so localVar is changed.\n\n

\n

In case of syntax error in code, vm.runInThisContext emits the syntax error to stderr\nand throws an exception.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code" + }, + { + "name": "filename", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "vm.runInNewContext(code, [sandbox], [filename])", + "type": "method", + "name": "runInNewContext", + "desc": "

vm.runInNewContext compiles code, then runs it in sandbox and returns the\nresult. Running code does not have access to local scope. The object sandbox\nwill be used as the global object for code.\nsandbox and filename are optional, filename is only used in stack traces.\n\n

\n

Example: compile and execute code that increments a global variable and sets a new one.\nThese globals are contained in the sandbox.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    sandbox = {\n      animal: 'cat',\n      count: 2\n    };\n\nvm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');\nconsole.log(util.inspect(sandbox));\n\n// { animal: 'cat', count: 3, name: 'kitty' }
\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, vm.runInNewContext is quite useful, but safely running untrusted code\nrequires a separate process.\n\n

\n

In case of syntax error in code, vm.runInNewContext emits the syntax error to stderr\nand throws an exception.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code" + }, + { + "name": "sandbox", + "optional": true + }, + { + "name": "filename", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "vm.runInContext(code, context, [filename])", + "type": "method", + "name": "runInContext", + "desc": "

vm.runInContext compiles code, then runs it in context and returns the\nresult. A (V8) context comprises a global object, together with a set of\nbuilt-in objects and functions. Running code does not have access to local scope\nand the global object held within context will be used as the global object\nfor code.\nfilename is optional, it's used only in stack traces.\n\n

\n

Example: compile and execute code in a existing context.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    initSandbox = {\n      animal: 'cat',\n      count: 2\n    },\n    context = vm.createContext(initSandbox);\n\nvm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');\nconsole.log(util.inspect(context));\n\n// { animal: 'cat', count: 3, name: 'CATT' }
\n

Note that createContext will perform a shallow clone of the supplied sandbox object in order to\ninitialise the global object of the freshly constructed context.\n\n

\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, vm.runInContext is quite useful, but safely running untrusted code\nrequires a separate process.\n\n

\n

In case of syntax error in code, vm.runInContext emits the syntax error to stderr\nand throws an exception.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code" + }, + { + "name": "context" + }, + { + "name": "filename", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "vm.createContext([initSandbox])", + "type": "method", + "name": "createContext", + "desc": "

vm.createContext creates a new context which is suitable for use as the 2nd argument of a subsequent\ncall to vm.runInContext. A (V8) context comprises a global object together with a set of\nbuild-in objects and functions. The optional argument initSandbox will be shallow-copied\nto seed the initial contents of the global object used by the context.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "initSandbox", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "vm.createScript(code, [filename])", + "type": "method", + "name": "createScript", + "desc": "

createScript compiles code but does not run it. Instead, it returns a\nvm.Script object representing this compiled code. This script can be run\nlater many times using methods below. The returned script is not bound to any\nglobal object. It is bound before each run, just for that run. filename is\noptional, it's only used in stack traces.\n\n

\n

In case of syntax error in code, createScript prints the syntax error to stderr\nand throws an exception.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "code" + }, + { + "name": "filename", + "optional": true + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: Script", + "type": "class", + "name": "Script", + "desc": "

A class for running scripts. Returned by vm.createScript.\n\n

\n", + "methods": [ + { + "textRaw": "script.runInThisContext()", + "type": "method", + "name": "runInThisContext", + "desc": "

Similar to vm.runInThisContext but a method of a precompiled Script object.\nscript.runInThisContext runs the code of script and returns the result.\nRunning code does not have access to local scope, but does have access to the global object\n(v8: in actual context).\n\n

\n

Example of using script.runInThisContext to compile code once and run it multiple times:\n\n

\n
var vm = require('vm');\n\nglobalVar = 0;\n\nvar script = vm.createScript('globalVar += 1', 'myfile.vm');\n\nfor (var i = 0; i < 1000 ; i += 1) {\n  script.runInThisContext();\n}\n\nconsole.log(globalVar);\n\n// 1000
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "script.runInNewContext([sandbox])", + "type": "method", + "name": "runInNewContext", + "desc": "

Similar to vm.runInNewContext a method of a precompiled Script object.\nscript.runInNewContext runs the code of script with sandbox as the global object and returns the result.\nRunning code does not have access to local scope. sandbox is optional.\n\n

\n

Example: compile code that increments a global variable and sets one, then execute this code multiple times.\nThese globals are contained in the sandbox.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    sandbox = {\n      animal: 'cat',\n      count: 2\n    };\n\nvar script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');\n\nfor (var i = 0; i < 10 ; i += 1) {\n  script.runInNewContext(sandbox);\n}\n\nconsole.log(util.inspect(sandbox));\n\n// { animal: 'cat', count: 12, name: 'kitty' }
\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, script.runInNewContext is quite useful, but safely running untrusted code\nrequires a separate process.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "sandbox", + "optional": true + } + ] + } + ] + } + ] + } + ], + "type": "module", + "displayName": "vm" + }, + { + "textRaw": "Child Process", + "name": "child_process", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Node provides a tri-directional popen(3) facility through the\nchild_process module.\n\n

\n

It is possible to stream data through a child's stdin, stdout, and\nstderr in a fully non-blocking way.\n\n

\n

To create a child process use require('child_process').spawn() or\nrequire('child_process').fork(). The semantics of each are slightly\ndifferent, and explained below.\n\n

\n", + "classes": [ + { + "textRaw": "Class: ChildProcess", + "type": "class", + "name": "ChildProcess", + "desc": "

ChildProcess is an EventEmitter.\n\n

\n

Child processes always have three streams associated with them. child.stdin,\nchild.stdout, and child.stderr. These may be shared with the stdio\nstreams of the parent process, or they may be separate stream objects\nwhich can be piped to and from.\n\n

\n

The ChildProcess class is not intended to be used directly. Use the\nspawn() or fork() methods to create a Child Process instance.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'exit'", + "type": "event", + "name": "exit", + "params": [], + "desc": "

This event is emitted after the child process ends. If the process terminated\nnormally, code is the final exit code of the process, otherwise null. If\nthe process terminated due to receipt of a signal, signal is the string name\nof the signal, otherwise null.\n\n

\n

See waitpid(2).\n\n

\n" + } + ], + "properties": [ + { + "textRaw": "`stdin` {Stream object} ", + "name": "stdin", + "desc": "

A Writable Stream that represents the child process's stdin.\nClosing this stream via end() often causes the child process to terminate.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" + }, + { + "textRaw": "`stdout` {Stream object} ", + "name": "stdout", + "desc": "

A Readable Stream that represents the child process's stdout.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" + }, + { + "textRaw": "`stderr` {Stream object} ", + "name": "stderr", + "desc": "

A Readable Stream that represents the child process's stderr.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" + }, + { + "textRaw": "`pid` {Integer} ", + "name": "pid", + "desc": "

The PID of the child process.\n\n

\n

Example:\n\n

\n
var spawn = require('child_process').spawn,\n    grep  = spawn('grep', ['ssh']);\n\nconsole.log('Spawned child pid: ' + grep.pid);\ngrep.stdin.end();
\n" + } + ], + "methods": [ + { + "textRaw": "child.kill([signal])", + "type": "method", + "name": "kill", + "signatures": [ + { + "params": [ + { + "textRaw": "`signal` {String} ", + "name": "signal", + "type": "String", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "signal", + "optional": true + } + ] + } + ], + "desc": "

Send a signal to the child process. If no argument is given, the process will\nbe sent 'SIGTERM'. See signal(7) for a list of available signals.\n\n

\n
var spawn = require('child_process').spawn,\n    grep  = spawn('grep', ['ssh']);\n\ngrep.on('exit', function (code, signal) {\n  console.log('child process terminated due to receipt of signal '+signal);\n});\n\n// send SIGHUP to process\ngrep.kill('SIGHUP');
\n

Note that while the function is called kill, the signal delivered to the child\nprocess may not actually kill it. kill really just sends a signal to a process.\n\n

\n

See kill(2)\n\n

\n" + }, + { + "textRaw": "child.send(message, [sendHandle])", + "type": "method", + "name": "send", + "signatures": [ + { + "params": [ + { + "textRaw": "`message` {Object} ", + "name": "message", + "type": "Object" + }, + { + "textRaw": "`sendHandle` {Handle object} ", + "name": "sendHandle", + "type": "Handle object", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "message" + }, + { + "name": "sendHandle", + "optional": true + } + ] + } + ], + "desc": "

Send a message (and, optionally, a handle object) to a child process.\n\n

\n

See child_process.fork() for details.\n\n

\n" + } + ] + } + ], + "methods": [ + { + "textRaw": "child_process.spawn(command, [args], [options])", + "type": "method", + "name": "spawn", + "signatures": [ + { + "return": { + "textRaw": "return: {ChildProcess object} ", + "name": "return", + "type": "ChildProcess object" + }, + "params": [ + { + "textRaw": "`command` {String} The command to run ", + "name": "command", + "type": "String", + "desc": "The command to run" + }, + { + "textRaw": "`args` {Array} List of string arguments ", + "name": "args", + "type": "Array", + "desc": "List of string arguments", + "optional": true + }, + { + "textRaw": "`options` {Object} ", + "options": [ + { + "textRaw": "`cwd` {String} Current working directory of the child process ", + "name": "cwd", + "type": "String", + "desc": "Current working directory of the child process" + }, + { + "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", + "name": "customFds", + "type": "Array", + "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" + }, + { + "textRaw": "`env` {Object} Environment key-value pairs ", + "name": "env", + "type": "Object", + "desc": "Environment key-value pairs" + } + ], + "name": "options", + "type": "Object", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "command" + }, + { + "name": "args", + "optional": true + }, + { + "name": "options", + "optional": true + } + ] + } + ], + "desc": "

Launches a new process with the given command, with command line arguments in args.\nIf omitted, args defaults to an empty Array.\n\n

\n

The third argument is used to specify additional options, which defaults to:\n\n

\n
{ cwd: undefined,\n  env: process.env\n}
\n

cwd allows you to specify the working directory from which the process is spawned.\nUse env to specify environment variables that will be visible to the new process.\n\n

\n

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:\n\n

\n
var util  = require('util'),\n    spawn = require('child_process').spawn,\n    ls    = spawn('ls', ['-lh', '/usr']);\n\nls.stdout.on('data', function (data) {\n  console.log('stdout: ' + data);\n});\n\nls.stderr.on('data', function (data) {\n  console.log('stderr: ' + data);\n});\n\nls.on('exit', function (code) {\n  console.log('child process exited with code ' + code);\n});
\n

Example: A very elaborate way to run 'ps ax | grep ssh'\n\n

\n
var util  = require('util'),\n    spawn = require('child_process').spawn,\n    ps    = spawn('ps', ['ax']),\n    grep  = spawn('grep', ['ssh']);\n\nps.stdout.on('data', function (data) {\n  grep.stdin.write(data);\n});\n\nps.stderr.on('data', function (data) {\n  console.log('ps stderr: ' + data);\n});\n\nps.on('exit', function (code) {\n  if (code !== 0) {\n    console.log('ps process exited with code ' + code);\n  }\n  grep.stdin.end();\n});\n\ngrep.stdout.on('data', function (data) {\n  console.log(data);\n});\n\ngrep.stderr.on('data', function (data) {\n  console.log('grep stderr: ' + data);\n});\n\ngrep.on('exit', function (code) {\n  if (code !== 0) {\n    console.log('grep process exited with code ' + code);\n  }\n});
\n

Example of checking for failed exec:\n\n

\n
var spawn = require('child_process').spawn,\n    child = spawn('bad_command');\n\nchild.stderr.setEncoding('utf8');\nchild.stderr.on('data', function (data) {\n  if (/^execvp\\(\\)/.test(data)) {\n    console.log('Failed to start child process.');\n  }\n});
\n

Note that if spawn receives an empty options object, it will result in\nspawning the process with an empty environment rather than using\nprocess.env. This due to backwards compatibility issues with a deprecated\nAPI.\n\n

\n

There is a deprecated option called customFds which allows one to specify\nspecific file descriptors for the stdio of the child process. This API was\nnot portable to all platforms and therefore removed.\nWith customFds it was possible to hook up the new process' [stdin, stdout,\nstderr] to existing streams; -1 meant that a new stream should be created.\nUse at your own risk.\n\n

\n

There are several internal options. In particular stdinStream,\nstdoutStream, stderrStream. They are for INTERNAL USE ONLY. As with all\nundocumented APIs in Node, they should not be used.\n\n

\n

See also: child_process.exec() and child_process.fork()\n\n

\n" + }, + { + "textRaw": "child_process.exec(command, [options], callback)", + "type": "method", + "name": "exec", + "signatures": [ + { + "return": { + "textRaw": "Return: ChildProcess object ", + "name": "return", + "desc": "ChildProcess object" + }, + "params": [ + { + "textRaw": "`command` {String} The command to run, with space-separated arguments ", + "name": "command", + "type": "String", + "desc": "The command to run, with space-separated arguments" + }, + { + "textRaw": "`options` {Object} ", + "options": [ + { + "textRaw": "`cwd` {String} Current working directory of the child process ", + "name": "cwd", + "type": "String", + "desc": "Current working directory of the child process" + }, + { + "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", + "name": "customFds", + "type": "Array", + "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" + }, + { + "textRaw": "`env` {Object} Environment key-value pairs ", + "name": "env", + "type": "Object", + "desc": "Environment key-value pairs" + }, + { + "textRaw": "`encoding` {String} (Default: 'utf8') ", + "name": "encoding", + "default": "utf8", + "type": "String" + }, + { + "textRaw": "`timeout` {Number} (Default: 0) ", + "name": "timeout", + "default": "0", + "type": "Number" + }, + { + "textRaw": "`maxBuffer` {Number} (Default: 200*1024) ", + "name": "maxBuffer", + "default": "200*1024", + "type": "Number" + }, + { + "textRaw": "`killSignal` {String} (Default: 'SIGTERM') ", + "name": "killSignal", + "default": "SIGTERM", + "type": "String" + } + ], + "name": "options", + "type": "Object", + "optional": true + }, + { + "textRaw": "`callback` {Function} called with the output when process terminates ", + "options": [ + { + "textRaw": "`error` {Error} ", + "name": "error", + "type": "Error" + }, + { + "textRaw": "`stdout` {Buffer} ", + "name": "stdout", + "type": "Buffer" + }, + { + "textRaw": "`stderr` {Buffer} ", + "name": "stderr", + "type": "Buffer" + } + ], + "name": "callback", + "type": "Function", + "desc": "called with the output when process terminates" + } + ] + }, + { + "params": [ + { + "name": "command" + }, + { + "name": "options", + "optional": true + }, + { + "name": "callback" + } + ] + } + ], + "desc": "

Runs a command in a shell and buffers the output.\n\n

\n
var util = require('util'),\n    exec = require('child_process').exec,\n    child;\n\nchild = exec('cat *.js bad_file | wc -l',\n  function (error, stdout, stderr) {\n    console.log('stdout: ' + stdout);\n    console.log('stderr: ' + stderr);\n    if (error !== null) {\n      console.log('exec error: ' + error);\n    }\n});
\n

The callback gets the arguments (error, stdout, stderr). On success, error\nwill be null. On error, error will be an instance of Error and err.code\nwill be the exit code of the child process, and err.signal will be set to the\nsignal that terminated the process.\n\n

\n

There is a second optional argument to specify several options. The\ndefault options are\n\n

\n
{ encoding: 'utf8',\n  timeout: 0,\n  maxBuffer: 200*1024,\n  killSignal: 'SIGTERM',\n  cwd: null,\n  env: null }
\n

If timeout is greater than 0, then it will kill the child process\nif it runs longer than timeout milliseconds. The child process is killed with\nkillSignal (default: 'SIGTERM'). maxBuffer specifies the largest\namount of data allowed on stdout or stderr - if this value is exceeded then\nthe child process is killed.\n\n\n

\n" + }, + { + "textRaw": "child_process.execFile(file, args, options, callback)", + "type": "method", + "name": "execFile", + "signatures": [ + { + "return": { + "textRaw": "Return: ChildProcess object ", + "name": "return", + "desc": "ChildProcess object" + }, + "params": [ + { + "textRaw": "`file` {String} The filename of the program to run ", + "name": "file", + "type": "String", + "desc": "The filename of the program to run" + }, + { + "textRaw": "`args` {Array} List of string arguments ", + "name": "args", + "type": "Array", + "desc": "List of string arguments" + }, + { + "textRaw": "`options` {Object} ", + "options": [ + { + "textRaw": "`cwd` {String} Current working directory of the child process ", + "name": "cwd", + "type": "String", + "desc": "Current working directory of the child process" + }, + { + "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", + "name": "customFds", + "type": "Array", + "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" + }, + { + "textRaw": "`env` {Object} Environment key-value pairs ", + "name": "env", + "type": "Object", + "desc": "Environment key-value pairs" + }, + { + "textRaw": "`encoding` {String} (Default: 'utf8') ", + "name": "encoding", + "default": "utf8", + "type": "String" + }, + { + "textRaw": "`timeout` {Number} (Default: 0) ", + "name": "timeout", + "default": "0", + "type": "Number" + }, + { + "textRaw": "`maxBuffer` {Number} (Default: 200*1024) ", + "name": "maxBuffer", + "default": "200*1024", + "type": "Number" + }, + { + "textRaw": "`killSignal` {String} (Default: 'SIGTERM') ", + "name": "killSignal", + "default": "SIGTERM", + "type": "String" + } + ], + "name": "options", + "type": "Object" + }, + { + "textRaw": "`callback` {Function} called with the output when process terminates ", + "options": [ + { + "textRaw": "`error` {Error} ", + "name": "error", + "type": "Error" + }, + { + "textRaw": "`stdout` {Buffer} ", + "name": "stdout", + "type": "Buffer" + }, + { + "textRaw": "`stderr` {Buffer} ", + "name": "stderr", + "type": "Buffer" + } + ], + "name": "callback", + "type": "Function", + "desc": "called with the output when process terminates" + } + ] + }, + { + "params": [ + { + "name": "file" + }, + { + "name": "args" + }, + { + "name": "options" + }, + { + "name": "callback" + } + ] + } + ], + "desc": "

This is similar to child_process.exec() except it does not execute a\nsubshell but rather the specified file directly. This makes it slightly\nleaner than child_process.exec. It has the same options.\n\n\n

\n" + }, + { + "textRaw": "child_process.fork(modulePath, [args], [options])", + "type": "method", + "name": "fork", + "signatures": [ + { + "return": { + "textRaw": "Return: ChildProcess object ", + "name": "return", + "desc": "ChildProcess object" + }, + "params": [ + { + "textRaw": "`modulePath` {String} The module to run in the child ", + "name": "modulePath", + "type": "String", + "desc": "The module to run in the child" + }, + { + "textRaw": "`args` {Array} List of string arguments ", + "name": "args", + "type": "Array", + "desc": "List of string arguments", + "optional": true + }, + { + "textRaw": "`options` {Object} ", + "options": [ + { + "textRaw": "`cwd` {String} Current working directory of the child process ", + "name": "cwd", + "type": "String", + "desc": "Current working directory of the child process" + }, + { + "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", + "name": "customFds", + "type": "Array", + "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" + }, + { + "textRaw": "`env` {Object} Environment key-value pairs ", + "name": "env", + "type": "Object", + "desc": "Environment key-value pairs" + }, + { + "textRaw": "`encoding` {String} (Default: 'utf8') ", + "name": "encoding", + "default": "utf8", + "type": "String" + }, + { + "textRaw": "`timeout` {Number} (Default: 0) ", + "name": "timeout", + "default": "0", + "type": "Number" + } + ], + "name": "options", + "type": "Object", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "modulePath" + }, + { + "name": "args", + "optional": true + }, + { + "name": "options", + "optional": true + } + ] + } + ], + "desc": "

This is a special case of the spawn() functionality for spawning Node\nprocesses. In addition to having all the methods in a normal ChildProcess\ninstance, the returned object has a communication channel built-in. The\nchannel is written to with child.send(message, [sendHandle]) and messages\nare received by a 'message' event on the child.\n\n

\n

For example:\n\n

\n
var cp = require('child_process');\n\nvar n = cp.fork(__dirname + '/sub.js');\n\nn.on('message', function(m) {\n  console.log('PARENT got message:', m);\n});\n\nn.send({ hello: 'world' });
\n

And then the child script, 'sub.js' might look like this:\n\n

\n
process.on('message', function(m) {\n  console.log('CHILD got message:', m);\n});\n\nprocess.send({ foo: 'bar' });
\n

In the child the process object will have a send() method, and process\nwill emit objects each time it receives a message on its channel.\n\n

\n

By default the spawned Node process will have the stdin, stdout, stderr\nassociated with the parent's.\n\n

\n

These child Nodes are still whole new instances of V8. Assume at least 30ms\nstartup and 10mb memory for each new Node. That is, you cannot create many\nthousands of them.\n\n

\n

The sendHandle option to child.send() is for sending a handle object to\nanother process. Child will receive the handle as as second argument to the\nmessage event. Here is an example of sending a handle:\n\n

\n
var server = require('net').createServer();\nvar child = require('child_process').fork(__dirname + '/child.js');\n// Open up the server object and send the handle.\nserver.listen(1337, function() {\n  child.send({ server: true }, server._handle);\n});
\n

Here is an example of receiving the server handle and sharing it between\nprocesses:\n\n

\n
process.on('message', function(m, serverHandle) {\n  if (serverHandle) {\n    var server = require('net').createServer();\n    server.listen(serverHandle);\n  }\n});
\n" + } + ], + "type": "module", + "displayName": "Child Process" + }, + { + "textRaw": "Assert", + "name": "assert", + "stability": 5, + "stabilityText": "Locked", + "desc": "

This module is used for writing unit tests for your applications, you can\naccess it with require('assert').\n\n

\n", + "methods": [ + { + "textRaw": "assert.fail(actual, expected, message, operator)", + "type": "method", + "name": "fail", + "desc": "

Throws an exception that displays the values for actual and expected separated by the provided operator.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message" + }, + { + "name": "operator" + } + ] + } + ] + }, + { + "textRaw": "assert(value, message), assert.ok(value, [message])", + "type": "method", + "name": "ok", + "desc": "

Tests if value is a true value, it is equivalent to assert.equal(true, value, message);\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "value" + }, + { + "name": "message)" + }, + { + "name": "assert.ok(value" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.equal(actual, expected, [message])", + "type": "method", + "name": "equal", + "desc": "

Tests shallow, coercive equality with the equal comparison operator ( == ).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.notEqual(actual, expected, [message])", + "type": "method", + "name": "notEqual", + "desc": "

Tests shallow, coercive non-equality with the not equal comparison operator ( != ).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.deepEqual(actual, expected, [message])", + "type": "method", + "name": "deepEqual", + "desc": "

Tests for deep equality.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.notDeepEqual(actual, expected, [message])", + "type": "method", + "name": "notDeepEqual", + "desc": "

Tests for any deep inequality.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.strictEqual(actual, expected, [message])", + "type": "method", + "name": "strictEqual", + "desc": "

Tests strict equality, as determined by the strict equality operator ( === )\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.notStrictEqual(actual, expected, [message])", + "type": "method", + "name": "notStrictEqual", + "desc": "

Tests strict non-equality, as determined by the strict not equal operator ( !== )\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "actual" + }, + { + "name": "expected" + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.throws(block, [error], [message])", + "type": "method", + "name": "throws", + "desc": "

Expects block to throw an error. error can be constructor, regexp or \nvalidation function.\n\n

\n

Validate instanceof using constructor:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  Error\n);
\n

Validate error message using RegExp:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  /value/\n);
\n

Custom error validation:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  function(err) {\n    if ( (err instanceof Error) && /value/.test(err) ) {\n      return true;\n    }\n  },\n  "unexpected error"\n);
\n", + "signatures": [ + { + "params": [ + { + "name": "block" + }, + { + "name": "error", + "optional": true + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.doesNotThrow(block, [error], [message])", + "type": "method", + "name": "doesNotThrow", + "desc": "

Expects block not to throw an error, see assert.throws for details.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "block" + }, + { + "name": "error", + "optional": true + }, + { + "name": "message", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "assert.ifError(value)", + "type": "method", + "name": "ifError", + "desc": "

Tests if value is not a false value, throws if it is a true value. Useful when\ntesting the first argument, error in callbacks.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "value" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "Assert" + }, + { + "textRaw": "TTY", + "name": "tty", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Use require('tty') to access this module.\n\n

\n

Example:\n\n

\n
var tty = require('tty');\nprocess.stdin.resume();\ntty.setRawMode(true);\nprocess.stdin.on('keypress', function(char, key) {\n  if (key && key.ctrl && key.name == 'c') {\n    console.log('graceful exit');\n    process.exit()\n  }\n});
\n", + "methods": [ + { + "textRaw": "tty.isatty(fd)", + "type": "method", + "name": "isatty", + "desc": "

Returns true or false depending on if the fd is associated with a\nterminal.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "fd" + } + ] + } + ] + }, + { + "textRaw": "tty.setRawMode(mode)", + "type": "method", + "name": "setRawMode", + "desc": "

mode should be true or false. This sets the properties of the current\nprocess's stdin fd to act either as a raw device or default.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "mode" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "TTY" + }, + { + "textRaw": "Zlib", + "name": "zlib", + "stability": 3, + "stabilityText": "Stable", + "desc": "

You can access this module with:\n\n

\n
var zlib = require('zlib');
\n

This provides bindings to Gzip/Gunzip, Deflate/Inflate, and\nDeflateRaw/InflateRaw classes. Each class takes the same options, and\nis a readable/writable Stream.\n\n

\n

Examples

\n

Compressing or decompressing a file can be done by piping an\nfs.ReadStream into a zlib stream, then into an fs.WriteStream.\n\n

\n
var gzip = zlib.createGzip();\nvar fs = require('fs');\nvar inp = fs.createReadStream('input.txt');\nvar out = fs.createWriteStream('input.txt.gz');\n\ninp.pipe(gzip).pipe(out);
\n

Compressing or decompressing data in one step can be done by using\nthe convenience methods.\n\n

\n
var input = '.................................';\nzlib.deflate(input, function(err, buffer) {\n  if (!err) {\n    console.log(buffer.toString('base64'));\n  }\n});\n\nvar buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');\nzlib.unzip(buffer, function(err, buffer) {\n  if (!err) {\n    console.log(buffer.toString());\n  }\n});
\n

To use this module in an HTTP client or server, use the\naccept-encoding\non requests, and the\ncontent-encoding\nheader on responses.\n\n

\n

Note: these examples are drastically simplified to show\nthe basic concept. Zlib encoding can be expensive, and the results\nought to be cached. See Memory Usage Tuning\nbelow for more information on the speed/memory/compression\ntradeoffs involved in zlib usage.\n\n

\n
// client request example\nvar zlib = require('zlib');\nvar http = require('http');\nvar fs = require('fs');\nvar request = http.get({ host: 'izs.me',\n                         path: '/',\n                         port: 80,\n                         headers: { 'accept-encoding': 'gzip,deflate' } });\nrequest.on('response', function(response) {\n  var output = fs.createWriteStream('izs.me_index.html');\n\n  switch (response.headers['content-encoding']) {\n    // or, just use zlib.createUnzip() to handle both cases\n    case 'gzip':\n      response.pipe(zlib.createGunzip()).pipe(output);\n      break;\n    case 'deflate':\n      response.pipe(zlib.createInflate()).pipe(output);\n      break;\n    default:\n      response.pipe(output);\n      break;\n  }\n});\n\n// server example\n// Running a gzip operation on every request is quite expensive.\n// It would be much more efficient to cache the compressed buffer.\nvar zlib = require('zlib');\nvar http = require('http');\nvar fs = require('fs');\nhttp.createServer(function(request, response) {\n  var raw = fs.createReadStream('index.html');\n  var acceptEncoding = request.headers['accept-encoding'];\n  if (!acceptEncoding) {\n    acceptEncoding = '';\n  }\n\n  // Note: this is not a conformant accept-encoding parser.\n  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3\n  if (acceptEncoding.match(/\\bdeflate\\b/)) {\n    response.writeHead(200, { 'content-encoding': 'deflate' });\n    raw.pipe(zlib.createDeflate()).pipe(response);\n  } else if (acceptEncoding.match(/\\bgzip\\b/)) {\n    response.writeHead(200, { 'content-encoding': 'gzip' });\n    raw.pipe(zlib.createGzip()).pipe(response);\n  } else {\n    response.writeHead(200, {});\n    raw.pipe(response);\n  }\n}).listen(1337);
\n", + "miscs": [ + { + "textRaw": "Constants", + "name": "Constants", + "type": "misc", + "desc": "

All of the constants defined in zlib.h are also defined on\nrequire('zlib'). They are described in more detail in the zlib\ndocumentation. See http://zlib.net/manual.html#Constants\nfor more details.\n\n

\n" + }, + { + "textRaw": "Convenience Methods", + "name": "Convenience Methods", + "type": "misc", + "desc": "

All of these take a string or buffer as the first argument, and call the\nsupplied callback with callback(error, result). The\ncompression/decompression engine is created using the default settings\nin all convenience methods. To supply different options, use the\nzlib classes directly.\n\n

\n" + }, + { + "textRaw": "Options", + "name": "Options", + "type": "misc", + "desc": "

Each class takes an options object. All options are optional. (The\nconvenience methods use the default settings for all options.)\n\n

\n

Note that some options are only\nrelevant when compressing, and are ignored by the decompression classes.\n\n

\n
    \n
  • chunkSize (default: 16*1024)
    • \n
  • windowBits
    • \n
  • level (compression only)
    • \n
  • memLevel (compression only)
    • \n
  • strategy (compression only)
    • \n
\n

See the description of deflateInit2 and inflateInit2 at\n

\n

http://zlib.net/manual.html#Advanced for more information on these.\n\n

\n" + }, + { + "textRaw": "Memory Usage Tuning", + "name": "Memory Usage Tuning", + "type": "misc", + "desc": "

From zlib/zconf.h, modified to node's usage:\n\n

\n

The memory requirements for deflate are (in bytes):\n\n

\n
(1 << (windowBits+2)) +  (1 << (memLevel+9))
\n

that is: 128K for windowBits=15 + 128K for memLevel = 8\n(default values) plus a few kilobytes for small objects.\n\n

\n

For example, if you want to reduce\nthe default memory requirements from 256K to 128K, set the options to:\n\n

\n
{ windowBits: 14, memLevel: 7 }
\n

Of course this will generally degrade compression (there's no free lunch).\n\n

\n

The memory requirements for inflate are (in bytes)\n\n

\n
1 << windowBits
\n

that is, 32K for windowBits=15 (default value) plus a few kilobytes\nfor small objects.\n\n

\n

This is in addition to a single internal output slab buffer of size\nchunkSize, which defaults to 16K.\n\n

\n

The speed of zlib compression is affected most dramatically by the\nlevel setting. A higher level will result in better compression, but\nwill take longer to complete. A lower level will result in less\ncompression, but will be much faster.\n\n

\n

In general, greater memory usage options will mean that node has to make\nfewer calls to zlib, since it'll be able to process more data in a\nsingle write operation. So, this is another factor that affects the\nspeed, at the cost of memory usage.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "zlib.createGzip([options])", + "type": "method", + "name": "createGzip", + "desc": "

Returns a new Gzip object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createGunzip([options])", + "type": "method", + "name": "createGunzip", + "desc": "

Returns a new Gunzip object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createDeflate([options])", + "type": "method", + "name": "createDeflate", + "desc": "

Returns a new Deflate object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createInflate([options])", + "type": "method", + "name": "createInflate", + "desc": "

Returns a new Inflate object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createDeflateRaw([options])", + "type": "method", + "name": "createDeflateRaw", + "desc": "

Returns a new DeflateRaw object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createInflateRaw([options])", + "type": "method", + "name": "createInflateRaw", + "desc": "

Returns a new InflateRaw object with an options.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.createUnzip([options])", + "type": "method", + "name": "createUnzip", + "desc": "

Returns a new Unzip object with an options.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "options", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "zlib.deflate(buf, callback)", + "type": "method", + "name": "deflate", + "desc": "

Compress a string with Deflate.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.deflateRaw(buf, callback)", + "type": "method", + "name": "deflateRaw", + "desc": "

Compress a string with DeflateRaw.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.gzip(buf, callback)", + "type": "method", + "name": "gzip", + "desc": "

Compress a string with Gzip.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.gunzip(buf, callback)", + "type": "method", + "name": "gunzip", + "desc": "

Decompress a raw Buffer with Gunzip.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.inflate(buf, callback)", + "type": "method", + "name": "inflate", + "desc": "

Decompress a raw Buffer with Inflate.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.inflateRaw(buf, callback)", + "type": "method", + "name": "inflateRaw", + "desc": "

Decompress a raw Buffer with InflateRaw.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "zlib.unzip(buf, callback)", + "type": "method", + "name": "unzip", + "desc": "

Decompress a raw Buffer with Unzip.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buf" + }, + { + "name": "callback" + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: zlib.Gzip", + "type": "class", + "name": "zlib.Gzip", + "desc": "

Compress data using gzip.\n\n

\n" + }, + { + "textRaw": "Class: zlib.Gunzip", + "type": "class", + "name": "zlib.Gunzip", + "desc": "

Decompress a gzip stream.\n\n

\n" + }, + { + "textRaw": "Class: zlib.Deflate", + "type": "class", + "name": "zlib.Deflate", + "desc": "

Compress data using deflate.\n\n

\n" + }, + { + "textRaw": "Class: zlib.Inflate", + "type": "class", + "name": "zlib.Inflate", + "desc": "

Decompress a deflate stream.\n\n

\n" + }, + { + "textRaw": "Class: zlib.DeflateRaw", + "type": "class", + "name": "zlib.DeflateRaw", + "desc": "

Compress data using deflate, and do not append a zlib header.\n\n

\n" + }, + { + "textRaw": "Class: zlib.InflateRaw", + "type": "class", + "name": "zlib.InflateRaw", + "desc": "

Decompress a raw deflate stream.\n\n

\n" + }, + { + "textRaw": "Class: zlib.Unzip", + "type": "class", + "name": "zlib.Unzip", + "desc": "

Decompress either a Gzip- or Deflate-compressed stream by auto-detecting\nthe header.\n\n

\n" + } + ], + "type": "module", + "displayName": "Zlib" + }, + { + "textRaw": "os", + "name": "os", + "stability": 4, + "stabilityText": "API Frozen", + "desc": "

Provides a few basic operating-system related utility functions.\n\n

\n

Use require('os') to access this module.\n\n

\n", + "methods": [ + { + "textRaw": "os.hostname()", + "type": "method", + "name": "hostname", + "desc": "

Returns the hostname of the operating system.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.type()", + "type": "method", + "name": "type", + "desc": "

Returns the operating system name.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.platform()", + "type": "method", + "name": "platform", + "desc": "

Returns the operating system platform.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.arch()", + "type": "method", + "name": "arch", + "desc": "

Returns the operating system CPU architecture.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.release()", + "type": "method", + "name": "release", + "desc": "

Returns the operating system release.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.uptime()", + "type": "method", + "name": "uptime", + "desc": "

Returns the system uptime in seconds.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.loadavg()", + "type": "method", + "name": "loadavg", + "desc": "

Returns an array containing the 1, 5, and 15 minute load averages.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.totalmem()", + "type": "method", + "name": "totalmem", + "desc": "

Returns the total amount of system memory in bytes.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.freemem()", + "type": "method", + "name": "freemem", + "desc": "

Returns the amount of free system memory in bytes.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.cpus()", + "type": "method", + "name": "cpus", + "desc": "

Returns an array of objects containing information about each CPU/core installed: model, speed (in MHz), and times (an object containing the number of CPU ticks spent in: user, nice, sys, idle, and irq).\n\n

\n

Example inspection of os.cpus:\n\n

\n
[ { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 252020,\n       nice: 0,\n       sys: 30340,\n       idle: 1070356870,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 306960,\n       nice: 0,\n       sys: 26980,\n       idle: 1071569080,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 248450,\n       nice: 0,\n       sys: 21750,\n       idle: 1070919370,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 256880,\n       nice: 0,\n       sys: 19430,\n       idle: 1070905480,\n       irq: 20 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 511580,\n       nice: 20,\n       sys: 40900,\n       idle: 1070842510,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 291660,\n       nice: 0,\n       sys: 34360,\n       idle: 1070888000,\n       irq: 10 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 308260,\n       nice: 0,\n       sys: 55410,\n       idle: 1071129970,\n       irq: 880 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 266450,\n       nice: 1480,\n       sys: 34920,\n       idle: 1072572010,\n       irq: 30 } } ]
\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "os.networkInterfaces()", + "type": "method", + "name": "networkInterfaces", + "desc": "

Get a list of network interfaces:\n\n

\n
{ lo0: \n   [ { address: '::1', family: 'IPv6', internal: true },\n     { address: 'fe80::1', family: 'IPv6', internal: true },\n     { address: '127.0.0.1', family: 'IPv4', internal: true } ],\n  en1: \n   [ { address: 'fe80::cabc:c8ff:feef:f996', family: 'IPv6',\n       internal: false },\n     { address: '10.0.1.123', family: 'IPv4', internal: false } ],\n  vmnet1: [ { address: '10.99.99.254', family: 'IPv4', internal: false } ],\n  vmnet8: [ { address: '10.88.88.1', family: 'IPv4', internal: false } ],\n  ppp0: [ { address: '10.2.0.231', family: 'IPv4', internal: false } ] }
\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "type": "module", + "displayName": "os" + }, + { + "textRaw": "Cluster", + "name": "cluster", + "stability": 1, + "stabilityText": "Experimental - Drastic changes in future versions", + "desc": "

A single instance of Node runs in a single thread. To take advantage of\nmulti-core systems the user will sometimes want to launch a cluster of Node\nprocesses to handle the load.\n\n

\n

The cluster module allows you to easily create a network of processes that\nall share server ports.\n\n

\n
var cluster = require('cluster');\nvar http = require('http');\nvar numCPUs = require('os').cpus().length;\n\nif (cluster.isMaster) {\n  // Fork workers.\n  for (var i = 0; i < numCPUs; i++) {\n    cluster.fork();\n  }\n\n  cluster.on('death', function(worker) {\n    console.log('worker ' + worker.pid + ' died');\n  });\n} else {\n  // Worker processes have a http server.\n  http.Server(function(req, res) {\n    res.writeHead(200);\n    res.end("hello world\\n");\n  }).listen(8000);\n}
\n

Running node will now share port 8000 between the workers:\n\n

\n
% node server.js\nWorker 2438 online\nWorker 2437 online
\n

The difference between cluster.fork() and child_process.fork() is simply\nthat cluster allows TCP servers to be shared between workers. cluster.fork\nis implemented on top of child_process.fork. The message passing API that\nis available with child_process.fork is available with cluster as well.\nAs an example, here is a cluster which keeps count of the number of requests\nin the master process via message passing:\n\n

\n
var cluster = require('cluster');\nvar http = require('http');\nvar numReqs = 0;\n\nif (cluster.isMaster) {\n  // Fork workers.\n  for (var i = 0; i < 2; i++) {\n    var worker = cluster.fork();\n\n    worker.on('message', function(msg) {\n      if (msg.cmd && msg.cmd == 'notifyRequest') {\n        numReqs++;\n      }\n    });\n  }\n\n  setInterval(function() {\n    console.log("numReqs =", numReqs);\n  }, 1000);\n} else {\n  // Worker processes have a http server.\n  http.Server(function(req, res) {\n    res.writeHead(200);\n    res.end("hello world\\n");\n    // Send message to master process\n    process.send({ cmd: 'notifyRequest' });\n  }).listen(8000);\n}
\n", + "methods": [ + { + "textRaw": "cluster.fork()", + "type": "method", + "name": "fork", + "desc": "

Spawn a new worker process. This can only be called from the master process.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "properties": [ + { + "textRaw": "cluster.isMaster", + "name": "isMaster", + "desc": "

Boolean flags to determine if the current process is a master or a worker\nprocess in a cluster. A process isMaster if process.env.NODE_WORKER_ID\nis undefined.\n\n

\n" + }, + { + "textRaw": "cluster.isWorker", + "name": "isWorker", + "desc": "

Boolean flags to determine if the current process is a master or a worker\nprocess in a cluster. A process isMaster if process.env.NODE_WORKER_ID\nis undefined.\n\n

\n" + } + ], + "events": [ + { + "textRaw": "Event: 'death'", + "type": "event", + "name": "death", + "desc": "

When any of the workers die the cluster module will emit the 'death' event.\nThis can be used to restart the worker by calling fork() again.\n\n

\n
cluster.on('death', function(worker) {\n  console.log('worker ' + worker.pid + ' died. restart...');\n  cluster.fork();\n});
\n

Different techniques can be used to restart the worker depending on the\napplication.\n\n

\n", + "params": [] + } + ], + "type": "module", + "displayName": "Cluster" + }, + { + "textRaw": "Appendix 1 - Third Party Modules", + "name": "appendix_1_-_third_party_modules", + "desc": "

There are many third party modules for Node. At the time of writing, August\n2010, the master repository of modules is\nthe wiki page.\n\n

\n

This appendix is intended as a SMALL guide to new-comers to help them\nquickly find what are considered to be quality modules. It is not intended\nto be a complete list. There may be better more complete modules found\nelsewhere.\n\n

\n\n

Patches to this list are welcome.\n\n

\n", + "type": "module", + "displayName": "Appendix 1 - Third Party Modules" + } + ], + "stability": 3, + "stabilityText": "Stable" +} --- /dev/null +++ b/doc/api/dgram.html @@ -0,0 +1,339 @@ + + + + + UDP / Datagram Sockets Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

UDP / Datagram Sockets#

+
Stability: 3 - Stable
+ + +

Datagram sockets are available through require('dgram'). + +

+

dgram.createSocket(type, [callback])#

+
    +
  • type String. Either 'udp4' or 'udp6'
    • +
  • callback Function. Attached as a listener to message events. +Optional
    • +
  • Returns: Socket object
    • +
+

Creates a datagram Socket of the specified types. Valid types are udp4 +and udp6. + +

+

Takes an optional callback which is added as a listener for message events. + +

+

Call socket.bind if you want to receive datagrams. socket.bind() will bind +to the "all interfaces" address on a random port (it does the right thing for +both udp4 and udp6 sockets). You can then retrieve the address and port +with socket.address().address and socket.address().port. + +

+

Class: Socket#

+

The dgram Socket class encapsulates the datagram functionality. It +should be created via dgram.createSocket(type, [callback]). + +

+

Event: 'message'#

+
    +
  • msg Buffer object. The message
    • +
  • rinfo Object. Remote address information
    • +
+

Emitted when a new datagram is available on a socket. msg is a Buffer and rinfo is +an object with the sender's address information and the number of bytes in the datagram. + +

+

Event: 'listening'#

+

Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets +are created. + +

+

Event: 'close'#

+

Emitted when a socket is closed with close(). No new message events will be emitted +on this socket. + +

+

Event: 'error'#

+
    +
  • exception Error object
    • +
+

Emitted when an error occurs. + +

+

dgram.send(buf, offset, length, port, address, [callback])#

+
    +
  • buf Buffer object. Message to be sent
    • +
  • offset Integer. Offset in the buffer where the message starts.
    • +
  • length Integer. Number of bytes in the message.
    • +
  • port Integer. destination port
    • +
  • address String. destination IP
    • +
  • callback Function. Callback when message is done being delivered. +Optional.
    • +
+

For UDP sockets, the destination port and IP address must be specified. A string +may be supplied for the address parameter, and it will be resolved with DNS. An +optional callback may be specified to detect any DNS errors and when buf may be +re-used. Note that DNS lookups will delay the time that a send takes place, at +least until the next tick. The only way to know for sure that a send has taken place +is to use the callback. + +

+

If the socket has not been previously bound with a call to bind, it's +assigned a random port number and bound to the "all interfaces" address +(0.0.0.0 for udp4 sockets, ::0 for udp6 sockets). + +

+

Example of sending a UDP packet to a random port on localhost; + +

+
var dgram = require('dgram');
+var message = new Buffer("Some bytes");
+var client = dgram.createSocket("udp4");
+client.send(message, 0, message.length, 41234, "localhost", function(err, bytes) {
+  client.close();
+});
+

A Note about UDP datagram size + +

+

The maximum size of an IPv4/v6 datagram depends on the MTU (Maximum Transmission Unit) +and on the Payload Length field size. + +

+
    +

  • The Payload Length field is 16 bits wide, which means that a normal payload +cannot be larger than 64K octets including internet header and data +(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header); +this is generally true for loopback interfaces, but such long datagrams +are impractical for most hosts and networks.

    +
    • +

  • The MTU is the largest size a given link layer technology can support for datagrams. +For any link, IPv4 mandates a minimum MTU of 68 octets, while the recommended MTU +for IPv4 is 576 (typically recommended as the MTU for dial-up type applications), +whether they arrive whole or in fragments.

    +

    For IPv6, the minimum MTU is 1280 octets, however, the mandatory minimum +fragment reassembly buffer size is 1500 octets. +The value of 68 octets is very small, since most current link layer technologies have +a minimum MTU of 1500 (like Ethernet).

    +
    • +
+

Note that it's impossible to know in advance the MTU of each link through which +a packet might travel, and that generally sending a datagram greater than +the (receiver) MTU won't work (the packet gets silently dropped, without +informing the source that the data did not reach its intended recipient). + +

+

dgram.bind(port, [address])#

+
    +
  • port Integer
    • +
  • address String, Optional
    • +
+

For UDP sockets, listen for datagrams on a named port and optional address. If +address is not specified, the OS will try to listen on all addresses. + +

+

Example of a UDP server listening on port 41234: + +

+
var dgram = require("dgram");
+
+var server = dgram.createSocket("udp4");
+
+server.on("message", function (msg, rinfo) {
+  console.log("server got: " + msg + " from " +
+    rinfo.address + ":" + rinfo.port);
+});
+
+server.on("listening", function () {
+  var address = server.address();
+  console.log("server listening " +
+      address.address + ":" + address.port);
+});
+
+server.bind(41234);
+// server listening 0.0.0.0:41234
+

dgram.close()#

+

Close the underlying socket and stop listening for data on it. + +

+

dgram.address()#

+

Returns an object containing the address information for a socket. For UDP sockets, +this object will contain address and port. + +

+

dgram.setBroadcast(flag)#

+
    +
  • flag Boolean
    • +
+

Sets or clears the SO_BROADCAST socket option. When this option is set, UDP packets +may be sent to a local interface's broadcast address. + +

+

dgram.setTTL(ttl)#

+
    +
  • ttl Integer
    • +
+

Sets the IP_TTL socket option. TTL stands for "Time to Live," but in this context it +specifies the number of IP hops that a packet is allowed to go through. Each router or +gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a +router, it will not be forwarded. Changing TTL values is typically done for network +probes or when multicasting. + +

+

The argument to setTTL() is a number of hops between 1 and 255. The default on most +systems is 64. + +

+

dgram.setMulticastTTL(ttl)#

+
    +
  • ttl Integer
    • +
+

Sets the IP_MULTICAST_TTL socket option. TTL stands for "Time to Live," but in this +context it specifies the number of IP hops that a packet is allowed to go through, +specifically for multicast traffic. Each router or gateway that forwards a packet +decrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. + +

+

The argument to setMulticastTTL() is a number of hops between 0 and 255. The default on most +systems is 64. + +

+

dgram.setMulticastLoopback(flag)#

+
    +
  • flag Boolean
    • +
+

Sets or clears the IP_MULTICAST_LOOP socket option. When this option is set, multicast +packets will also be received on the local interface. + +

+

dgram.addMembership(multicastAddress, [multicastInterface])#

+
    +
  • multicastAddress String
    • +
  • multicastInterface String, Optional
    • +
+

Tells the kernel to join a multicast group with IP_ADD_MEMBERSHIP socket option. + +

+

If multicastInterface is not specified, the OS will try to add membership to all valid +interfaces. + +

+

dgram.dropMembership(multicastAddress, [multicastInterface])#

+
    +
  • multicastAddress String
    • +
  • multicastInterface String, Optional
    • +
+

Opposite of addMembership - tells the kernel to leave a multicast group with +IP_DROP_MEMBERSHIP socket option. This is automatically called by the kernel +when the socket is closed or process terminates, so most apps will never need to call +this. + +

+

If multicastInterface is not specified, the OS will try to drop membership to all valid +interfaces. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/stdio.json @@ -0,0 +1,129 @@ +{ + "source": "doc/api/stdio.markdown", + "globals": [ + { + "textRaw": "console", + "name": "console", + "stability": 4, + "stabilityText": "API Frozen", + "type": "global", + "desc": "

For printing to stdout and stderr. Similar to the console object functions\nprovided by most web browsers, here the output is sent to stdout or stderr.\n\n\n

\n", + "methods": [ + { + "textRaw": "console.log()", + "type": "method", + "name": "log", + "desc": "

Prints to stdout with newline. This function can take multiple arguments in a\nprintf()-like way. Example:\n\n

\n
console.log('count: %d', count);
\n

If formatting elements are not found in the first string then util.inspect\nis used on each argument.\nSee util.format() for more information.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.info()", + "type": "method", + "name": "info", + "desc": "

Same as console.log.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.warn()", + "type": "method", + "name": "warn", + "desc": "

Same as console.log but prints to stderr.\n\n

\n", + "signatures": [ + { + "params": [] + }, + { + "params": [] + } + ] + }, + { + "textRaw": "console.error()", + "type": "method", + "name": "error", + "desc": "

Same as console.log but prints to stderr.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.dir(obj)", + "type": "method", + "name": "dir", + "desc": "

Uses util.inspect on obj and prints resulting string to stderr.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "obj" + } + ] + } + ] + }, + { + "textRaw": "console.time(label)", + "type": "method", + "name": "time", + "desc": "

Mark a time.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "label" + } + ] + } + ] + }, + { + "textRaw": "console.timeEnd(label)", + "type": "method", + "name": "timeEnd", + "desc": "

Finish timer, record output. Example\n\n

\n
console.time('100-elements');\nfor (var i = 0; i < 100; i++) {\n  ;\n}\nconsole.timeEnd('100-elements');
\n", + "signatures": [ + { + "params": [ + { + "name": "label" + } + ] + } + ] + }, + { + "textRaw": "console.trace()", + "type": "method", + "name": "trace", + "desc": "

Print a stack trace to stderr of the current position.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "console.assert()", + "type": "method", + "name": "assert", + "desc": "

Same as assert.ok().\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + } + ] +} --- /dev/null +++ b/doc/api/child_process.json @@ -0,0 +1,498 @@ +{ + "source": "doc/api/child_process.markdown", + "modules": [ + { + "textRaw": "Child Process", + "name": "child_process", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Node provides a tri-directional popen(3) facility through the\nchild_process module.\n\n

\n

It is possible to stream data through a child's stdin, stdout, and\nstderr in a fully non-blocking way.\n\n

\n

To create a child process use require('child_process').spawn() or\nrequire('child_process').fork(). The semantics of each are slightly\ndifferent, and explained below.\n\n

\n", + "classes": [ + { + "textRaw": "Class: ChildProcess", + "type": "class", + "name": "ChildProcess", + "desc": "

ChildProcess is an EventEmitter.\n\n

\n

Child processes always have three streams associated with them. child.stdin,\nchild.stdout, and child.stderr. These may be shared with the stdio\nstreams of the parent process, or they may be separate stream objects\nwhich can be piped to and from.\n\n

\n

The ChildProcess class is not intended to be used directly. Use the\nspawn() or fork() methods to create a Child Process instance.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'exit'", + "type": "event", + "name": "exit", + "params": [], + "desc": "

This event is emitted after the child process ends. If the process terminated\nnormally, code is the final exit code of the process, otherwise null. If\nthe process terminated due to receipt of a signal, signal is the string name\nof the signal, otherwise null.\n\n

\n

See waitpid(2).\n\n

\n" + } + ], + "properties": [ + { + "textRaw": "`stdin` {Stream object} ", + "name": "stdin", + "desc": "

A Writable Stream that represents the child process's stdin.\nClosing this stream via end() often causes the child process to terminate.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" + }, + { + "textRaw": "`stdout` {Stream object} ", + "name": "stdout", + "desc": "

A Readable Stream that represents the child process's stdout.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" + }, + { + "textRaw": "`stderr` {Stream object} ", + "name": "stderr", + "desc": "

A Readable Stream that represents the child process's stderr.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" + }, + { + "textRaw": "`pid` {Integer} ", + "name": "pid", + "desc": "

The PID of the child process.\n\n

\n

Example:\n\n

\n
var spawn = require('child_process').spawn,\n    grep  = spawn('grep', ['ssh']);\n\nconsole.log('Spawned child pid: ' + grep.pid);\ngrep.stdin.end();
\n" + } + ], + "methods": [ + { + "textRaw": "child.kill([signal])", + "type": "method", + "name": "kill", + "signatures": [ + { + "params": [ + { + "textRaw": "`signal` {String} ", + "name": "signal", + "type": "String", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "signal", + "optional": true + } + ] + } + ], + "desc": "

Send a signal to the child process. If no argument is given, the process will\nbe sent 'SIGTERM'. See signal(7) for a list of available signals.\n\n

\n
var spawn = require('child_process').spawn,\n    grep  = spawn('grep', ['ssh']);\n\ngrep.on('exit', function (code, signal) {\n  console.log('child process terminated due to receipt of signal '+signal);\n});\n\n// send SIGHUP to process\ngrep.kill('SIGHUP');
\n

Note that while the function is called kill, the signal delivered to the child\nprocess may not actually kill it. kill really just sends a signal to a process.\n\n

\n

See kill(2)\n\n

\n" + }, + { + "textRaw": "child.send(message, [sendHandle])", + "type": "method", + "name": "send", + "signatures": [ + { + "params": [ + { + "textRaw": "`message` {Object} ", + "name": "message", + "type": "Object" + }, + { + "textRaw": "`sendHandle` {Handle object} ", + "name": "sendHandle", + "type": "Handle object", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "message" + }, + { + "name": "sendHandle", + "optional": true + } + ] + } + ], + "desc": "

Send a message (and, optionally, a handle object) to a child process.\n\n

\n

See child_process.fork() for details.\n\n

\n" + } + ] + } + ], + "methods": [ + { + "textRaw": "child_process.spawn(command, [args], [options])", + "type": "method", + "name": "spawn", + "signatures": [ + { + "return": { + "textRaw": "return: {ChildProcess object} ", + "name": "return", + "type": "ChildProcess object" + }, + "params": [ + { + "textRaw": "`command` {String} The command to run ", + "name": "command", + "type": "String", + "desc": "The command to run" + }, + { + "textRaw": "`args` {Array} List of string arguments ", + "name": "args", + "type": "Array", + "desc": "List of string arguments", + "optional": true + }, + { + "textRaw": "`options` {Object} ", + "options": [ + { + "textRaw": "`cwd` {String} Current working directory of the child process ", + "name": "cwd", + "type": "String", + "desc": "Current working directory of the child process" + }, + { + "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", + "name": "customFds", + "type": "Array", + "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" + }, + { + "textRaw": "`env` {Object} Environment key-value pairs ", + "name": "env", + "type": "Object", + "desc": "Environment key-value pairs" + } + ], + "name": "options", + "type": "Object", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "command" + }, + { + "name": "args", + "optional": true + }, + { + "name": "options", + "optional": true + } + ] + } + ], + "desc": "

Launches a new process with the given command, with command line arguments in args.\nIf omitted, args defaults to an empty Array.\n\n

\n

The third argument is used to specify additional options, which defaults to:\n\n

\n
{ cwd: undefined,\n  env: process.env\n}
\n

cwd allows you to specify the working directory from which the process is spawned.\nUse env to specify environment variables that will be visible to the new process.\n\n

\n

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:\n\n

\n
var util  = require('util'),\n    spawn = require('child_process').spawn,\n    ls    = spawn('ls', ['-lh', '/usr']);\n\nls.stdout.on('data', function (data) {\n  console.log('stdout: ' + data);\n});\n\nls.stderr.on('data', function (data) {\n  console.log('stderr: ' + data);\n});\n\nls.on('exit', function (code) {\n  console.log('child process exited with code ' + code);\n});
\n

Example: A very elaborate way to run 'ps ax | grep ssh'\n\n

\n
var util  = require('util'),\n    spawn = require('child_process').spawn,\n    ps    = spawn('ps', ['ax']),\n    grep  = spawn('grep', ['ssh']);\n\nps.stdout.on('data', function (data) {\n  grep.stdin.write(data);\n});\n\nps.stderr.on('data', function (data) {\n  console.log('ps stderr: ' + data);\n});\n\nps.on('exit', function (code) {\n  if (code !== 0) {\n    console.log('ps process exited with code ' + code);\n  }\n  grep.stdin.end();\n});\n\ngrep.stdout.on('data', function (data) {\n  console.log(data);\n});\n\ngrep.stderr.on('data', function (data) {\n  console.log('grep stderr: ' + data);\n});\n\ngrep.on('exit', function (code) {\n  if (code !== 0) {\n    console.log('grep process exited with code ' + code);\n  }\n});
\n

Example of checking for failed exec:\n\n

\n
var spawn = require('child_process').spawn,\n    child = spawn('bad_command');\n\nchild.stderr.setEncoding('utf8');\nchild.stderr.on('data', function (data) {\n  if (/^execvp\\(\\)/.test(data)) {\n    console.log('Failed to start child process.');\n  }\n});
\n

Note that if spawn receives an empty options object, it will result in\nspawning the process with an empty environment rather than using\nprocess.env. This due to backwards compatibility issues with a deprecated\nAPI.\n\n

\n

There is a deprecated option called customFds which allows one to specify\nspecific file descriptors for the stdio of the child process. This API was\nnot portable to all platforms and therefore removed.\nWith customFds it was possible to hook up the new process' [stdin, stdout,\nstderr] to existing streams; -1 meant that a new stream should be created.\nUse at your own risk.\n\n

\n

There are several internal options. In particular stdinStream,\nstdoutStream, stderrStream. They are for INTERNAL USE ONLY. As with all\nundocumented APIs in Node, they should not be used.\n\n

\n

See also: child_process.exec() and child_process.fork()\n\n

\n" + }, + { + "textRaw": "child_process.exec(command, [options], callback)", + "type": "method", + "name": "exec", + "signatures": [ + { + "return": { + "textRaw": "Return: ChildProcess object ", + "name": "return", + "desc": "ChildProcess object" + }, + "params": [ + { + "textRaw": "`command` {String} The command to run, with space-separated arguments ", + "name": "command", + "type": "String", + "desc": "The command to run, with space-separated arguments" + }, + { + "textRaw": "`options` {Object} ", + "options": [ + { + "textRaw": "`cwd` {String} Current working directory of the child process ", + "name": "cwd", + "type": "String", + "desc": "Current working directory of the child process" + }, + { + "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", + "name": "customFds", + "type": "Array", + "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" + }, + { + "textRaw": "`env` {Object} Environment key-value pairs ", + "name": "env", + "type": "Object", + "desc": "Environment key-value pairs" + }, + { + "textRaw": "`encoding` {String} (Default: 'utf8') ", + "name": "encoding", + "default": "utf8", + "type": "String" + }, + { + "textRaw": "`timeout` {Number} (Default: 0) ", + "name": "timeout", + "default": "0", + "type": "Number" + }, + { + "textRaw": "`maxBuffer` {Number} (Default: 200*1024) ", + "name": "maxBuffer", + "default": "200*1024", + "type": "Number" + }, + { + "textRaw": "`killSignal` {String} (Default: 'SIGTERM') ", + "name": "killSignal", + "default": "SIGTERM", + "type": "String" + } + ], + "name": "options", + "type": "Object", + "optional": true + }, + { + "textRaw": "`callback` {Function} called with the output when process terminates ", + "options": [ + { + "textRaw": "`error` {Error} ", + "name": "error", + "type": "Error" + }, + { + "textRaw": "`stdout` {Buffer} ", + "name": "stdout", + "type": "Buffer" + }, + { + "textRaw": "`stderr` {Buffer} ", + "name": "stderr", + "type": "Buffer" + } + ], + "name": "callback", + "type": "Function", + "desc": "called with the output when process terminates" + } + ] + }, + { + "params": [ + { + "name": "command" + }, + { + "name": "options", + "optional": true + }, + { + "name": "callback" + } + ] + } + ], + "desc": "

Runs a command in a shell and buffers the output.\n\n

\n
var util = require('util'),\n    exec = require('child_process').exec,\n    child;\n\nchild = exec('cat *.js bad_file | wc -l',\n  function (error, stdout, stderr) {\n    console.log('stdout: ' + stdout);\n    console.log('stderr: ' + stderr);\n    if (error !== null) {\n      console.log('exec error: ' + error);\n    }\n});
\n

The callback gets the arguments (error, stdout, stderr). On success, error\nwill be null. On error, error will be an instance of Error and err.code\nwill be the exit code of the child process, and err.signal will be set to the\nsignal that terminated the process.\n\n

\n

There is a second optional argument to specify several options. The\ndefault options are\n\n

\n
{ encoding: 'utf8',\n  timeout: 0,\n  maxBuffer: 200*1024,\n  killSignal: 'SIGTERM',\n  cwd: null,\n  env: null }
\n

If timeout is greater than 0, then it will kill the child process\nif it runs longer than timeout milliseconds. The child process is killed with\nkillSignal (default: 'SIGTERM'). maxBuffer specifies the largest\namount of data allowed on stdout or stderr - if this value is exceeded then\nthe child process is killed.\n\n\n

\n" + }, + { + "textRaw": "child_process.execFile(file, args, options, callback)", + "type": "method", + "name": "execFile", + "signatures": [ + { + "return": { + "textRaw": "Return: ChildProcess object ", + "name": "return", + "desc": "ChildProcess object" + }, + "params": [ + { + "textRaw": "`file` {String} The filename of the program to run ", + "name": "file", + "type": "String", + "desc": "The filename of the program to run" + }, + { + "textRaw": "`args` {Array} List of string arguments ", + "name": "args", + "type": "Array", + "desc": "List of string arguments" + }, + { + "textRaw": "`options` {Object} ", + "options": [ + { + "textRaw": "`cwd` {String} Current working directory of the child process ", + "name": "cwd", + "type": "String", + "desc": "Current working directory of the child process" + }, + { + "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", + "name": "customFds", + "type": "Array", + "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" + }, + { + "textRaw": "`env` {Object} Environment key-value pairs ", + "name": "env", + "type": "Object", + "desc": "Environment key-value pairs" + }, + { + "textRaw": "`encoding` {String} (Default: 'utf8') ", + "name": "encoding", + "default": "utf8", + "type": "String" + }, + { + "textRaw": "`timeout` {Number} (Default: 0) ", + "name": "timeout", + "default": "0", + "type": "Number" + }, + { + "textRaw": "`maxBuffer` {Number} (Default: 200*1024) ", + "name": "maxBuffer", + "default": "200*1024", + "type": "Number" + }, + { + "textRaw": "`killSignal` {String} (Default: 'SIGTERM') ", + "name": "killSignal", + "default": "SIGTERM", + "type": "String" + } + ], + "name": "options", + "type": "Object" + }, + { + "textRaw": "`callback` {Function} called with the output when process terminates ", + "options": [ + { + "textRaw": "`error` {Error} ", + "name": "error", + "type": "Error" + }, + { + "textRaw": "`stdout` {Buffer} ", + "name": "stdout", + "type": "Buffer" + }, + { + "textRaw": "`stderr` {Buffer} ", + "name": "stderr", + "type": "Buffer" + } + ], + "name": "callback", + "type": "Function", + "desc": "called with the output when process terminates" + } + ] + }, + { + "params": [ + { + "name": "file" + }, + { + "name": "args" + }, + { + "name": "options" + }, + { + "name": "callback" + } + ] + } + ], + "desc": "

This is similar to child_process.exec() except it does not execute a\nsubshell but rather the specified file directly. This makes it slightly\nleaner than child_process.exec. It has the same options.\n\n\n

\n" + }, + { + "textRaw": "child_process.fork(modulePath, [args], [options])", + "type": "method", + "name": "fork", + "signatures": [ + { + "return": { + "textRaw": "Return: ChildProcess object ", + "name": "return", + "desc": "ChildProcess object" + }, + "params": [ + { + "textRaw": "`modulePath` {String} The module to run in the child ", + "name": "modulePath", + "type": "String", + "desc": "The module to run in the child" + }, + { + "textRaw": "`args` {Array} List of string arguments ", + "name": "args", + "type": "Array", + "desc": "List of string arguments", + "optional": true + }, + { + "textRaw": "`options` {Object} ", + "options": [ + { + "textRaw": "`cwd` {String} Current working directory of the child process ", + "name": "cwd", + "type": "String", + "desc": "Current working directory of the child process" + }, + { + "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", + "name": "customFds", + "type": "Array", + "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" + }, + { + "textRaw": "`env` {Object} Environment key-value pairs ", + "name": "env", + "type": "Object", + "desc": "Environment key-value pairs" + }, + { + "textRaw": "`encoding` {String} (Default: 'utf8') ", + "name": "encoding", + "default": "utf8", + "type": "String" + }, + { + "textRaw": "`timeout` {Number} (Default: 0) ", + "name": "timeout", + "default": "0", + "type": "Number" + } + ], + "name": "options", + "type": "Object", + "optional": true + } + ] + }, + { + "params": [ + { + "name": "modulePath" + }, + { + "name": "args", + "optional": true + }, + { + "name": "options", + "optional": true + } + ] + } + ], + "desc": "

This is a special case of the spawn() functionality for spawning Node\nprocesses. In addition to having all the methods in a normal ChildProcess\ninstance, the returned object has a communication channel built-in. The\nchannel is written to with child.send(message, [sendHandle]) and messages\nare received by a 'message' event on the child.\n\n

\n

For example:\n\n

\n
var cp = require('child_process');\n\nvar n = cp.fork(__dirname + '/sub.js');\n\nn.on('message', function(m) {\n  console.log('PARENT got message:', m);\n});\n\nn.send({ hello: 'world' });
\n

And then the child script, 'sub.js' might look like this:\n\n

\n
process.on('message', function(m) {\n  console.log('CHILD got message:', m);\n});\n\nprocess.send({ foo: 'bar' });
\n

In the child the process object will have a send() method, and process\nwill emit objects each time it receives a message on its channel.\n\n

\n

By default the spawned Node process will have the stdin, stdout, stderr\nassociated with the parent's.\n\n

\n

These child Nodes are still whole new instances of V8. Assume at least 30ms\nstartup and 10mb memory for each new Node. That is, you cannot create many\nthousands of them.\n\n

\n

The sendHandle option to child.send() is for sending a handle object to\nanother process. Child will receive the handle as as second argument to the\nmessage event. Here is an example of sending a handle:\n\n

\n
var server = require('net').createServer();\nvar child = require('child_process').fork(__dirname + '/child.js');\n// Open up the server object and send the handle.\nserver.listen(1337, function() {\n  child.send({ server: true }, server._handle);\n});
\n

Here is an example of receiving the server handle and sharing it between\nprocesses:\n\n

\n
process.on('message', function(m, serverHandle) {\n  if (serverHandle) {\n    var server = require('net').createServer();\n    server.listen(serverHandle);\n  }\n});
\n" + } + ], + "type": "module", + "displayName": "Child Process" + } + ] +} --- /dev/null +++ b/doc/api/net.html @@ -0,0 +1,607 @@ + + + + + net Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

net#

+
Stability: 3 - Stable
+

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'); + +

+

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

+

Creates a new TCP server. The connectionListener argument is +automatically set as a listener for the 'connection' +event. + +

+

options is an object with the following defaults: + +

+
{ allowHalfOpen: false
+}
+

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. + +

+

Here is an example of a echo server which listens for connections +on port 8124: + +

+
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');
+});
+

Test this by using telnet: + +

+
telnet localhost 8124
+

To listen on the socket /tmp/echo.sock the third line from the last would +just be changed to + +

+
server.listen('/tmp/echo.sock', function() { //'listening' listener
+

Use nc to connect to a UNIX domain socket server: + +

+
nc -U /tmp/echo.sock
+

net.connect(arguments...)#

+

net.createConnection(arguments...)#

+

Construct a new socket object and opens a socket to the given location. When +the socket is established the 'connect' event will be +emitted. + +

+

The arguments for these methods change the type of connection: + +

+
    +
  • net.connect(port, [host], [connectListener])
    • +

  • net.createConnection(port, [host], [connectListener])

    +

    Creates a TCP connection to port on host. If host is omitted, +'localhost' will be assumed.

    +
    • +

  • net.connect(path, [connectListener])

    +
    • +

  • net.createConnection(path, [connectListener])

    +

    Creates unix socket connection to path.

    +
    • +
+

The connectListener parameter will be added as an listener for the +'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 connect on the socket /tmp/echo.sock the second line would just be +changed to + +

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

Class: net.Server#

+

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. When the server has been bound, +'listening' event will be emitted. +the last parameter listeningListener will be added as an listener for the +'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 +would be to wait a second and then try again. This can be done with + +

+
server.on('error', function (e) {
+  if (e.code == 'EADDRINUSE') {
+    console.log('Address in use, retrying...');
+    setTimeout(function () {
+      server.close();
+      server.listen(PORT, HOST);
+    }, 1000);
+  }
+});
+

(Note: All sockets in Node set SO_REUSEADDR already) + + +

+

server.listen(path, [listeningListener])#

+

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

+

This function is asynchronous. When the server has been bound, +'listening' event will be emitted. +the last parameter listeningListener will be added as an listener for the +'listening' event. + +

+

server.close()#

+

Stops the server from accepting new connections. This function is +asynchronous, the server is finally closed when the server emits a 'close' +event. + + +

+

server.address()#

+

Returns the bound address and port of the server as reported by the operating system. +Useful to find which port was assigned when giving getting an OS-assigned address. +Returns an object with two properties, e.g. {"address":"127.0.0.1", "port":2121} + +

+

Example: + +

+
var server = net.createServer(function (socket) {
+  socket.end("goodbye\n");
+});
+
+// grab a random port.
+server.listen(function() {
+  address = server.address();
+  console.log("opened server on %j", address);
+});
+

Don't call server.address() until the 'listening' event has been emitted. + +

+

server.maxConnections#

+

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

+

server.connections#

+

The number of concurrent connections on the server. + + +

+

net.Server is an EventEmitter with the following events: + +

+

Event: 'listening'#

+

Emitted when the server has been bound after calling server.listen. + +

+

Event: 'connection'#

+
    +
  • Socket object The connection object
    • +
+

Emitted when a new connection is made. socket is an instance of +net.Socket. + +

+

Event: 'close'#

+

Emitted when the server closes. + +

+

Event: 'error'#

+
    +
  • Error Object
    • +
+

Emitted when an error occurs. The 'close' event will be called directly +following this event. See example in discussion of server.listen. + +

+

Class: net.Socket#

+

This object is an abstraction of a TCP or UNIX socket. net.Socket +instances implement a duplex Stream interface. They can be created by the +user and used as a client (with connect()) or they can be created by Node +and passed to the user through the 'connection' event of a server. + +

+

new net.Socket([options])#

+

Construct a new socket object. + +

+

options is an object with the following defaults: + +

+
{ fd: null
+  type: null
+  allowHalfOpen: false
+}
+

fd allows you to specify the existing file descriptor of socket. type +specified underlying protocol. It can be 'tcp4', 'tcp6', or 'unix'. +About allowHalfOpen, refer to createServer() and 'end' event. + +

+

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, +localhost will be assumed. If a path is given, the socket will be +opened as a unix socket to that path. + +

+

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 +the exception. + +

+

The connectListener parameter will be added as an listener for the +'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). + +

+

The consequence of this internal buffering is that memory may grow. This +property shows the number of characters currently buffered to be written. +(Number of characters is approximately equal to the number of bytes to be +written, but the buffer may contain strings, and the strings are lazily +encoded, so the exact number of bytes is not known.) + +

+

Users who experience large or growing bufferSize should attempt to +"throttle" the data flows in their program with pause() and resume(). + + +

+

socket.setEncoding([encoding])#

+

Sets the encoding (either 'ascii', 'utf8', or 'base64') for data that is +received. Defaults to null. + +

+

socket.setSecure()#

+

This function has been removed in v0.3. It used to upgrade the connection to +SSL/TLS. See the TLS section for the new API. + + +

+

socket.write(data, [encoding], [callback])#

+

Sends data on the socket. The second parameter specifies the encoding in the +case of a string--it defaults to UTF8 encoding. + +

+

Returns true if the entire data was flushed successfully to the kernel +buffer. Returns false if all or part of the data was queued in user memory. +'drain' will be emitted when the buffer is again free. + +

+

The optional callback parameter will be executed when the data is finally +written out - this may not be immediately. + +

+

socket.end([data], [encoding])#

+

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(). + +

+

socket.destroy()#

+

Ensures that no more I/O activity happens on this socket. Only necessary in +case of errors (parse error or so). + +

+

socket.pause()#

+

Pauses the reading of data. That is, 'data' events will not be emitted. +Useful to throttle back an upload. + +

+

socket.resume()#

+

Resumes reading after a call to pause(). + +

+

socket.setTimeout(timeout, [callback])#

+

Sets the socket to timeout after timeout milliseconds of inactivity on +the socket. By default net.Socket do not have a timeout. + +

+

When an idle timeout is triggered the socket will receive a 'timeout' +event but the connection will not be severed. The user must manually end() +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. + +

+

socket.setNoDelay([noDelay])#

+

Disables the Nagle algorithm. By default TCP connections use the Nagle +algorithm, they buffer data before sending it off. Setting true for +noDelay will immediately fire off data each time socket.write() is called. +noDelay defaults to true. + +

+

socket.setKeepAlive([enable], [initialDelay])#

+

Enable/disable keep-alive functionality, and optionally set the initial +delay before the first keepalive probe is sent on an idle socket. +enable defaults to false. + +

+

Set initialDelay (in milliseconds) to set the delay between the last +data packet received and the first keepalive probe. Setting 0 for +initialDelay will leave the value unchanged from the default +(or previous) setting. Defaults to 0. + +

+

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} + +

+

socket.remoteAddress#

+

The string representation of the remote IP address. For example, +'74.125.127.100' or '2001:4860:a005::68'. + +

+

socket.remotePort#

+

The numeric representation of the remote port. For example, +80 or 21. + +

+

socket.bytesRead#

+

The amount of received bytes. + +

+

socket.bytesWritten#

+

The amount of bytes sent. + + +

+

net.Socket instances are EventEmitters with the following events: + +

+

Event: 'connect'#

+

Emitted when a socket connection is successfully established. +See connect(). + +

+

Event: 'data'#

+
    +
  • Buffer object
    • +
+

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 section for more +information.) + +

+

Note that the data will be lost if there is no listener when a Socket +emits a 'data' event. + +

+

Event: 'end'#

+

Emitted when the other end of the socket sends a FIN packet. + +

+

By default (allowHalfOpen == false) the socket will destroy its file +descriptor once it has written out its pending write queue. However, by +setting allowHalfOpen == true the socket will not automatically end() +its side allowing the user to write arbitrary amounts of data, with the +caveat that the user is required to end() their side now. + + +

+

Event: 'timeout'#

+

Emitted if the socket times out from inactivity. This is only to notify that +the socket has been idle. The user must manually close the connection. + +

+

See also: socket.setTimeout() + + +

+

Event: 'drain'#

+

Emitted when the write buffer becomes empty. Can be used to throttle uploads. + +

+

See also: the return values of socket.write() + +

+

Event: 'error'#

+
    +
  • Error object
    • +
+

Emitted when an error occurs. The 'close' event will be called directly +following this event. + +

+

Event: 'close'#

+
    +
  • had_error Boolean true if the socket had a transmission error
    • +
+

Emitted once the socket is fully closed. The argument had_error is a boolean +which says if the socket was closed due to a transmission error. + +

+

net.isIP(input)#

+

Tests if input is an IP address. Returns 0 for invalid strings, +returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses. + + +

+

net.isIPv4(input)#

+

Returns true if input is a version 4 IP address, otherwise returns false. + + +

+

net.isIPv6(input)#

+

Returns true if input is a version 6 IP address, otherwise returns false. + +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/addons.json @@ -0,0 +1,79 @@ +{ + "source": "doc/api/addons.markdown", + "modules": [ + { + "textRaw": "Addons", + "name": "addons", + "desc": "

Addons are dynamically linked shared objects. They can provide glue to C and\nC++ libraries. The API (at the moment) is rather complex, involving\nknowledge of several libraries:\n\n

\n
    \n

  • V8 JavaScript, a C++ library. Used for interfacing with JavaScript:\ncreating objects, calling functions, etc. Documented mostly in the\nv8.h header file (deps/v8/include/v8.h in the Node source tree),\nwhich is also available online.

    \n
    • \n

  • libuv, C event loop library. Anytime one\nneeds to wait for a file descriptor to become readable, wait for a timer, or\nwait for a signal to received one will need to interface with libuv. That is,\nif you perform any I/O, libuv will need to be used.

    \n
    • \n

  • Internal Node libraries. Most importantly is the node::ObjectWrap\nclass which you will likely want to derive from.

    \n
    • \n

  • Others. Look in deps/ for what else is available.

    \n
    • \n
\n

Node statically compiles all its dependencies into the executable. When\ncompiling your module, you don't need to worry about linking to any of these\nlibraries.\n\n\n

\n", + "modules": [ + { + "textRaw": "Hello world", + "name": "hello_world", + "desc": "

To get started let's make a small Addon which is the C++ equivalent of\nthe following Javascript code:\n\n

\n
exports.hello = function() { return 'world'; };
\n

First we create a file hello.cc:\n\n

\n
#include <node.h>\n#include <v8.h>\n\nusing namespace v8;\n\nHandle<Value> Method(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(String::New("world"));\n}\n\nvoid init(Handle<Object> target) {\n  target->Set(String::NewSymbol("hello"),\n      FunctionTemplate::New(Method)->GetFunction());\n}\nNODE_MODULE(hello, init)
\n

Note that all Node addons must export an initialization function:\n\n

\n
void Initialize (Handle<Object> target);\nNODE_MODULE(module_name, Initialize)
\n

There is no semi-colon after NODE_MODULE as it's not a function (see node.h).\n\n

\n

The module_name needs to match the filename of the final binary (minus the\n.node suffix).\n\n

\n

The source code needs to be built into hello.node, the binary Addon. To\ndo this we create a file called wscript which is python code and looks\nlike this:\n\n

\n
srcdir = '.'\nblddir = 'build'\nVERSION = '0.0.1'\n\ndef set_options(opt):\n  opt.tool_options('compiler_cxx')\n\ndef configure(conf):\n  conf.check_tool('compiler_cxx')\n  conf.check_tool('node_addon')\n\ndef build(bld):\n  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')\n  obj.target = 'hello'\n  obj.source = 'hello.cc'
\n

Running node-waf configure build will create a file\nbuild/default/hello.node which is our Addon.\n\n

\n

node-waf is just WAF, the python-based build system. node-waf is\nprovided for the ease of users.\n\n

\n

You can now use the binary addon in a Node project hello.js by pointing require to\nthe recently built module:\n\n

\n
var addon = require('./build/Release/hello');\n\nconsole.log(addon.hello()); // 'world'
\n

Please see patterns below for further information or\n

\n

https://github.com/pietern/hiredis-node for an example in production.\n\n\n

\n", + "type": "module", + "displayName": "Hello world" + }, + { + "textRaw": "Addon patterns", + "name": "addon_patterns", + "desc": "

Below are some addon patterns to help you get started. Consult the online\nv8 reference for help with the various v8\ncalls, and v8's Embedder's Guide\nfor an explanation of several concepts used such as handles, scopes,\nfunction templates, etc.\n\n

\n

To compile these examples, create the wscript file below and run\nnode-waf configure build:\n\n

\n
srcdir = '.'\nblddir = 'build'\nVERSION = '0.0.1'\n\ndef set_options(opt):\n  opt.tool_options('compiler_cxx')\n\ndef configure(conf):\n  conf.check_tool('compiler_cxx')\n  conf.check_tool('node_addon')\n\ndef build(bld):\n  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')\n  obj.target = 'addon'\n  obj.source = ['addon.cc']
\n

In cases where there is more than one .cc file, simply add the file name to the\nobj.source array, e.g.:\n\n

\n
obj.source = ['addon.cc', 'myexample.cc']
\n", + "modules": [ + { + "textRaw": "Function arguments", + "name": "function_arguments", + "desc": "

The following pattern illustrates how to read arguments from JavaScript\nfunction calls and return a result. This is the main and only needed source\naddon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> Add(const Arguments& args) {\n  HandleScope scope;\n\n  if (args.Length() < 2) {\n    ThrowException(Exception::TypeError(String::New("Wrong number of arguments")));\n    return scope.Close(Undefined());\n  }\n\n  if (!args[0]->IsNumber() || !args[1]->IsNumber()) {\n    ThrowException(Exception::TypeError(String::New("Wrong arguments")));\n    return scope.Close(Undefined());\n  }\n\n  Local<Number> num = Number::New(args[0]->NumberValue() +\n      args[1]->NumberValue());\n  return scope.Close(num);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("add"),\n      FunctionTemplate::New(Add)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

You can test it with the following JavaScript snippet:\n\n

\n
var addon = require('./build/Release/addon');\n\nconsole.log( 'This should be eight:', addon.add(3,5) );
\n", + "type": "module", + "displayName": "Function arguments" + }, + { + "textRaw": "Callbacks", + "name": "callbacks", + "desc": "

You can pass JavaScript functions to a C++ function and execute them from\nthere. Here's addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> RunCallback(const Arguments& args) {\n  HandleScope scope;\n\n  Local<Function> cb = Local<Function>::Cast(args[0]);\n  const unsigned argc = 1;\n  Local<Value> argv[argc] = { Local<Value>::New(String::New("hello world")) };\n  cb->Call(Context::GetCurrent()->Global(), argc, argv);\n\n  return scope.Close(Undefined());\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("runCallback"),\n      FunctionTemplate::New(RunCallback)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test it run the following JavaScript snippet:\n\n

\n
var addon = require('./build/Release/addon');\n\naddon.runCallback(function(msg){\n  console.log(msg); // 'hello world'\n});
\n", + "type": "module", + "displayName": "Callbacks" + }, + { + "textRaw": "Object factory", + "name": "object_factory", + "desc": "

You can create and return new objects from within a C++ function with this\naddon.cc pattern, which returns an object with property msg that echoes\nthe string passed to createObject():\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n\n  Local<Object> obj = Object::New();\n  obj->Set(String::NewSymbol("msg"), args[0]->ToString());\n\n  return scope.Close(obj);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test it in JavaScript:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj1 = addon.createObject('hello');\nvar obj2 = addon.createObject('world');\nconsole.log(obj1.msg+' '+obj2.msg); // 'hello world'
\n", + "type": "module", + "displayName": "Object factory" + }, + { + "textRaw": "Function factory", + "name": "function_factory", + "desc": "

This pattern illustrates how to create and return a JavaScript function that\nwraps a C++ function:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> MyFunction(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(String::New("hello world"));\n}\n\nHandle<Value> CreateFunction(const Arguments& args) {\n  HandleScope scope;\n\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(MyFunction);\n  Local<Function> fn = tpl->GetFunction();\n  fn->SetName(String::NewSymbol("theFunction")); // omit this to make it anonymous\n\n  return scope.Close(fn);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("createFunction"),\n      FunctionTemplate::New(CreateFunction)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar fn = addon.createFunction();\nconsole.log(fn()); // 'hello world'
\n", + "type": "module", + "displayName": "Function factory" + }, + { + "textRaw": "Wrapping C++ objects", + "name": "wrapping_c++_objects", + "desc": "

Here we will create a wrapper for a C++ object/class MyObject that can be\ninstantiated in JavaScript through the new operator. First prepare the main\nmodule addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init(target);\n}\n\nNODE_MODULE(addon, InitAll)
\n

Then in myobject.h make your wrapper inherit from node::ObjectWrap:\n\n

\n
#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init(v8::Handle<v8::Object> target);\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);\n  double counter_;\n};\n\n#endif
\n

And in myobject.cc implement the various methods that you want to expose.\nHere we expose the method plusOne by adding it to the constructor's\nprototype:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nvoid MyObject::Init(Handle<Object> target) {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n  // Prototype\n  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),\n      FunctionTemplate::New(PlusOne)->GetFunction());\n\n  Persistent<Function> constructor = Persistent<Function>::New(tpl->GetFunction());\n  target->Set(String::NewSymbol("MyObject"), constructor);\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::PlusOne(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n  obj->counter_ += 1;\n\n  return scope.Close(Number::New(obj->counter_));\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj = new addon.MyObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13
\n", + "type": "module", + "displayName": "Wrapping C++ objects" + }, + { + "textRaw": "Factory of wrapped objects", + "name": "factory_of_wrapped_objects", + "desc": "

This is useful when you want to be able to create native objects without\nexplicitly instantiating them with the new operator in JavaScript, e.g.\n\n

\n
var obj = addon.createObject();\n// instead of:\n// var obj = new addon.Object();
\n

Let's register our createObject method in addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(MyObject::NewInstance(args));\n}\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init();\n\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n}\n\nNODE_MODULE(addon, InitAll)
\n

In myobject.h we now introduce the static method NewInstance that takes\ncare of instantiating the object (i.e. it does the job of new in JavaScript):\n\n

\n
#define BUILDING_NODE_EXTENSION\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init();\n  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Persistent<v8::Function> constructor;\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);\n  double counter_;\n};\n\n#endif
\n

The implementation is similar to the above in myobject.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nPersistent<Function> MyObject::constructor;\n\nvoid MyObject::Init() {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n  // Prototype\n  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),\n      FunctionTemplate::New(PlusOne)->GetFunction());\n\n  constructor = Persistent<Function>::New(tpl->GetFunction());\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::NewInstance(const Arguments& args) {\n  HandleScope scope;\n\n  const unsigned argc = 1;\n  Handle<Value> argv[argc] = { args[0] };\n  Local<Object> instance = constructor->NewInstance(argc, argv);\n\n  return scope.Close(instance);\n}\n\nHandle<Value> MyObject::PlusOne(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n  obj->counter_ += 1;\n\n  return scope.Close(Number::New(obj->counter_));\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj = addon.createObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13\n\nvar obj2 = addon.createObject(20);\nconsole.log( obj2.plusOne() ); // 21\nconsole.log( obj2.plusOne() ); // 22\nconsole.log( obj2.plusOne() ); // 23
\n", + "type": "module", + "displayName": "Factory of wrapped objects" + }, + { + "textRaw": "Passing wrapped objects around", + "name": "passing_wrapped_objects_around", + "desc": "

In addition to wrapping and returning C++ objects, you can pass them around\nby unwrapping them with Node's node::ObjectWrap::Unwrap helper function.\nIn the following addon.cc we introduce a function add() that can take on two\nMyObject objects:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(MyObject::NewInstance(args));\n}\n\nHandle<Value> Add(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(\n      args[0]->ToObject());\n  MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(\n      args[1]->ToObject());\n\n  double sum = obj1->Val() + obj2->Val();\n  return scope.Close(Number::New(sum));\n}\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init();\n\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n\n  target->Set(String::NewSymbol("add"),\n      FunctionTemplate::New(Add)->GetFunction());\n}\n\nNODE_MODULE(addon, InitAll)
\n

To make things interesting we introduce a public method in myobject.h so we\ncan probe private values after unwrapping the object:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init();\n  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);\n  double Val() const { return val_; }\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Persistent<v8::Function> constructor;\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  double val_;\n};\n\n#endif
\n

The implementation of myobject.cc is similar as before:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nPersistent<Function> MyObject::constructor;\n\nvoid MyObject::Init() {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n\n  constructor = Persistent<Function>::New(tpl->GetFunction());\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->val_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::NewInstance(const Arguments& args) {\n  HandleScope scope;\n\n  const unsigned argc = 1;\n  Handle<Value> argv[argc] = { args[0] };\n  Local<Object> instance = constructor->NewInstance(argc, argv);\n\n  return scope.Close(instance);\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj1 = addon.createObject(10);\nvar obj2 = addon.createObject(20);\nvar result = addon.add(obj1, obj2);\n\nconsole.log(result); // 30
\n", + "type": "module", + "displayName": "Passing wrapped objects around" + } + ], + "type": "module", + "displayName": "Addon patterns" + } + ], + "type": "module", + "displayName": "Addons" + } + ] +} --- /dev/null +++ b/doc/api/tty.html @@ -0,0 +1,121 @@ + + + + + TTY Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ +
+

Table of Contents

+ + +
+ +
+

TTY#

+
Stability: 3 - Stable
+

Use require('tty') to access this module. + +

+

Example: + +

+
var tty = require('tty');
+process.stdin.resume();
+tty.setRawMode(true);
+process.stdin.on('keypress', function(char, key) {
+  if (key && key.ctrl && key.name == 'c') {
+    console.log('graceful exit');
+    process.exit()
+  }
+});
+

tty.isatty(fd)#

+

Returns true or false depending on if the fd is associated with a +terminal. + + +

+

tty.setRawMode(mode)#

+

mode should be true or false. This sets the properties of the current +process's stdin fd to act either as a raw device or default. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/all.html @@ -0,0 +1,9093 @@ + + + + + About this Documentation Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ +
+

Table of Contents

+ + +
+ +
+

About this Documentation#

+ + +

The goal of this documentation is to comprehensively explain the Node.js +API, both from a reference as well as a conceptual point of view. Each +section describes a built-in module or high-level concept. + +

+

Where appropriate, property types, method arguments, and the arguments +provided to event handlers are detailed in a list underneath the topic +heading. + +

+

Every .html document has a corresponding .json document presenting +the same information in a structured manner. This feature is +experimental, and added for the benefit of IDEs and other utilities that +wish to do programmatic things with the documentation. + +

+

Every .html and .json file is generated based on the corresponding +.markdown file in the doc/api/ folder in node's source tree. The +documentation is generated using the tools/doc/generate.js program. +The HTML template is located at doc/template.html. + +

+

Stability Index#

+ + +

Throughout the documentation, you will see indications of a section's +stability. The Node.js API is still somewhat changing, and as it +matures, certain parts are more reliable than others. Some are so +proven, and so relied upon, that they are unlikely to ever change at +all. Others are brand new and experimental, or known to be hazardous +and in the process of being redesigned. + +

+

The notices look like this: + +

+
Stability: 1 Experimental
+

The stability indices are as follows: + +

+
    +
  • 0 - Deprecated This feature is known to be problematic, and changes are +planned. Do not rely on it. Use of the feature may cause warnings. Backwards +compatibility should not be expected.
    • +
+
    +
  • 1 - Experimental This feature was introduced recently, and may change +or be removed in future versions. Please try it out and provide feedback. +If it addresses a use-case that is important to you, tell the node core team.
    • +
+
    +
  • 2 - Unstable The API is in the process of settling, but has not yet had +sufficient real-world testing to be considered stable. Backwards-compatibility +will be maintained if reasonable.
    • +
+
    +
  • 3 - Stable The API has proven satisfactory, but cleanup in the underlying +code may cause minor changes. Backwards-compatibility is guaranteed.
    • +
+
    +
  • 4 - API Frozen This API has been tested extensively in production and is +unlikely to ever have to change.
    • +
+
    +
  • 5 - Locked Unless serious bugs are found, this code will not ever +change. Please do not suggest changes in this area; they will be refused.
    • +
+

JSON Output#

+
Stability: 1 - Experimental
+

Every HTML file in the markdown has a corresponding JSON file with the +same data. + +

+

This feature is new as of node v0.6.12. It is experimental. + +

+

Synopsis#

+ + +

An example of a web server written with Node which responds with 'Hello +World': + +

+
var http = require('http');
+
+http.createServer(function (request, response) {
+  response.writeHead(200, {'Content-Type': 'text/plain'});
+  response.end('Hello World\n');
+}).listen(8124);
+
+console.log('Server running at http://127.0.0.1:8124/');
+

To run the server, put the code into a file called example.js and execute +it with the node program + +

+
> node example.js
+Server running at http://127.0.0.1:8124/
+

All of the examples in the documentation can be run similarly. + +

+

Global Objects#

+ + +

These objects are available in all modules. Some of these objects aren't +actually in the global scope but in the module scope - this will be noted. + +

+

global#

+ + +
    +
  • {Object} The global namespace object.
    • +
+

In browsers, the top-level scope is the global scope. That means that in +browsers if you're in the global scope var something will define a global +variable. In Node this is different. The top-level scope is not the global +scope; var something inside a Node module will be local to that module. + +

+

process#

+ + +
    +
  • {Object}
    • +
+

The process object. See the process object section. + +

+

console#

+ + +
    +
  • {Object}
    • +
+

Used to print to stdout and stderr. See the stdio section. + +

+

Buffer#

+ + +
    +
  • {Object}
    • +
+

Used to handle binary data. See the buffer section. + +

+

require()#

+ + +
    +
  • {Function}
    • +
+

To require modules. See the Modules section. +require isn't actually a global but rather local to each module. + + +

+

require.resolve()#

+

Use the internal require() machinery to look up the location of a module, +but rather than loading the module, just return the resolved filename. + +

+

require.cache#

+
    +
  • Object
    • +
+

Modules are cached in this object when they are required. By deleting a key +value from this object, the next require will reload the module. + +

+

__filename#

+ + +
    +
  • {String}
    • +
+

The filename of the code being executed. This is the resolved absolute path +of this code file. For a main program this is not necessarily the same +filename used in the command line. The value inside a module is the path +to that module file. + +

+

Example: running node example.js from /Users/mjr + +

+
console.log(__filename);
+// /Users/mjr/example.js
+

__filename isn't actually a global but rather local to each module. + +

+

__dirname#

+ + +
    +
  • {String}
    • +
+

The name of the directory that the currently executing script resides in. + +

+

Example: running node example.js from /Users/mjr + +

+
console.log(__dirname);
+// /Users/mjr
+

__dirname isn't actually a global but rather local to each module. + + +

+

module#

+ + +
    +
  • {Object}
    • +
+

A reference to the current module. In particular +module.exports is the same as the exports object. See src/node.js +for more information. +module isn't actually a global but rather local to each module. + + +

+

exports#

+ + +

An object which is shared between all instances of the current module and +made accessible through require(). +exports is the same as the module.exports object. See src/node.js +for more information. +exports isn't actually a global but rather local to each module. + +

+

See the module system documentation for more +information. + +

+

See the module section for more information. + +

+

setTimeout(cb, ms)#

+

clearTimeout(t)#

+

setInterval(cb, ms)#

+

clearInterval(t)#

+ + +

The timer functions are global variables. See the timers section. + +

+

console#

+
Stability: 4 - API Frozen
+
    +
  • {Object}
    • +
+ + +

For printing to stdout and stderr. Similar to the console object functions +provided by most web browsers, here the output is sent to stdout or stderr. + + +

+

console.log()#

+

Prints to stdout with newline. This function can take multiple arguments in a +printf()-like way. Example: + +

+
console.log('count: %d', count);
+

If formatting elements are not found in the first string then util.inspect +is used on each argument. +See util.format() for more information. + +

+

console.info()#

+

Same as console.log. + +

+

console.warn()#

+

console.error()#

+

Same as console.log but prints to stderr. + +

+

console.dir(obj)#

+

Uses util.inspect on obj and prints resulting string to stderr. + +

+

console.time(label)#

+

Mark a time. + + +

+

console.timeEnd(label)#

+

Finish timer, record output. Example + +

+
console.time('100-elements');
+for (var i = 0; i < 100; i++) {
+  ;
+}
+console.timeEnd('100-elements');
+

console.trace()#

+

Print a stack trace to stderr of the current position. + +

+

console.assert()#

+

Same as assert.ok(). + + +

+

Timers#

+
Stability: 5 - Locked
+

All of the timer functions are globals. You do not need to require() +this module in order to use them. + +

+

setTimeout(callback, delay, [arg], [...])#

+

To schedule execution of a one-time callback after delay milliseconds. Returns a +timeoutId for possible use with clearTimeout(). Optionally you can +also pass arguments to the callback. + +

+

It is important to note that your callback will probably not be called in exactly +delay milliseconds - Node.js makes no guarantees about the exact timing of when +the callback will fire, nor of the ordering things will fire in. The callback will +be called as close as possible to the time specified. + +

+

clearTimeout(timeoutId)#

+

Prevents a timeout from triggering. + +

+

setInterval(callback, delay, [arg], [...])#

+

To schedule the repeated execution of callback every delay milliseconds. +Returns a intervalId for possible use with clearInterval(). Optionally +you can also pass arguments to the callback. + +

+

clearInterval(intervalId)#

+

Stops a interval from triggering. + +

+

Modules#

+
Stability: 5 - Locked
+ + +

Node has a simple module loading system. In Node, files and modules are in +one-to-one correspondence. As an example, foo.js loads the module +circle.js in the same directory. + +

+

The contents of foo.js: + +

+
var circle = require('./circle.js');
+console.log( 'The area of a circle of radius 4 is '
+           + circle.area(4));
+

The contents of circle.js: + +

+
var PI = Math.PI;
+
+exports.area = function (r) {
+  return PI * r * r;
+};
+
+exports.circumference = function (r) {
+  return 2 * PI * r;
+};
+

The module circle.js has exported the functions area() and +circumference(). To export an object, add to the special exports +object. + +

+

Variables +local to the module will be private. In this example the variable PI is +private to circle.js. + +

+

The module system is implemented in the require("module") module. + +

+

Cycles#

+ + +

When there are circular require() calls, a module might not be +done being executed when it is returned. + +

+

Consider this situation: + +

+

a.js: + +

+
console.log('a starting');
+exports.done = false;
+var b = require('./b.js');
+console.log('in a, b.done = %j', b.done);
+exports.done = true;
+console.log('a done');
+

b.js: + +

+
console.log('b starting');
+exports.done = false;
+var a = require('./a.js');
+console.log('in b, a.done = %j', a.done);
+exports.done = true;
+console.log('b done');
+

main.js: + +

+
console.log('main starting');
+var a = require('./a.js');
+var b = require('./b.js');
+console.log('in main, a.done=%j, b.done=%j', a.done, b.done);
+

When main.js loads a.js, then a.js in turn loads b.js. At that +point, b.js tries to load a.js. In order to prevent an infinite +loop an unfinished copy of the a.js exports object is returned to the +b.js module. b.js then finishes loading, and its exports object is +provided to the a.js module. + +

+

By the time main.js has loaded both modules, they're both finished. +The output of this program would thus be: + +

+
$ node main.js
+main starting
+a starting
+b starting
+in b, a.done = false
+b done
+in a, b.done = true
+a done
+in main, a.done=true, b.done=true
+

If you have cyclic module dependencies in your program, make sure to +plan accordingly. + +

+

Core Modules#

+ + +

Node has several modules compiled into the binary. These modules are +described in greater detail elsewhere in this documentation. + +

+

The core modules are defined in node's source in the lib/ folder. + +

+

Core modules are always preferentially loaded if their identifier is +passed to require(). For instance, require('http') will always +return the built in HTTP module, even if there is a file by that name. + +

+

File Modules#

+ + +

If the exact filename is not found, then node will attempt to load the +required filename with the added extension of .js, .json, and then .node. + +

+

.js files are interpreted as JavaScript text files, and .json files are +parsed as JSON text files. .node files are interpreted as compiled addon +modules loaded with dlopen. + +

+

A module prefixed with '/' is an absolute path to the file. For +example, require('/home/marco/foo.js') will load the file at +/home/marco/foo.js. + +

+

A module prefixed with './' is relative to the file calling require(). +That is, circle.js must be in the same directory as foo.js for +require('./circle') to find it. + +

+

Without a leading '/' or './' to indicate a file, the module is either a +"core module" or is loaded from a node_modules folder. + +

+

Loading from node_modules Folders#

+ + +

If the module identifier passed to require() is not a native module, +and does not begin with '/', '../', or './', then node starts at the +parent directory of the current module, and adds /node_modules, and +attempts to load the module from that location. + +

+

If it is not found there, then it moves to the parent directory, and so +on, until the root of the tree is reached. + +

+

For example, if the file at '/home/ry/projects/foo.js' called +require('bar.js'), then node would look in the following locations, in +this order: + +

+
    +
  • /home/ry/projects/node_modules/bar.js
    • +
  • /home/ry/node_modules/bar.js
    • +
  • /home/node_modules/bar.js
    • +
  • /node_modules/bar.js
    • +
+

This allows programs to localize their dependencies, so that they do not +clash. + +

+

Folders as Modules#

+ + +

It is convenient to organize programs and libraries into self-contained +directories, and then provide a single entry point to that library. +There are three ways in which a folder may be passed to require() as +an argument. + +

+

The first is to create a package.json file in the root of the folder, +which specifies a main module. An example package.json file might +look like this: + +

+
{ "name" : "some-library",
+  "main" : "./lib/some-library.js" }
+

If this was in a folder at ./some-library, then +require('./some-library') would attempt to load +./some-library/lib/some-library.js. + +

+

This is the extent of Node's awareness of package.json files. + +

+

If there is no package.json file present in the directory, then node +will attempt to load an index.js or index.node file out of that +directory. For example, if there was no package.json file in the above +example, then require('./some-library') would attempt to load: + +

+
    +
  • ./some-library/index.js
    • +
  • ./some-library/index.node
    • +
+

Caching#

+ + +

Modules are cached after the first time they are loaded. This means +(among other things) that every call to require('foo') will get +exactly the same object returned, if it would resolve to the same file. + +

+

Multiple calls to require('foo') may not cause the module code to be +executed multiple times. This is an important feature. With it, +"partially done" objects can be returned, thus allowing transitive +dependencies to be loaded even when they would cause cycles. + +

+

If you want to have a module execute code multiple times, then export a +function, and call that function. + +

+

Module Caching Caveats#

+ + +

Modules are cached based on their resolved filename. Since modules may +resolve to a different filename based on the location of the calling +module (loading from node_modules folders), it is not a guarantee +that require('foo') will always return the exact same object, if it +would resolve to different files. + +

+

The module Object#

+ + + +
    +
  • {Object}
    • +
+

In each module, the module free variable is a reference to the object +representing the current module. In particular +module.exports is the same as the exports object. +module isn't actually a global but rather local to each module. + +

+

module.exports#

+
    +
  • Object
    • +
+

The exports object is created by the Module system. Sometimes this is not +acceptable, many want their module to be an instance of some class. To do this +assign the desired export object to module.exports. For example suppose we +were making a module called a.js + +

+
var EventEmitter = require('events').EventEmitter;
+
+module.exports = new EventEmitter();
+
+// Do some work, and after some time emit
+// the 'ready' event from the module itself.
+setTimeout(function() {
+  module.exports.emit('ready');
+}, 1000);
+

Then in another file we could do + +

+
var a = require('./a');
+a.on('ready', function() {
+  console.log('module a is ready');
+});
+

Note that assignment to module.exports must be done immediately. It cannot be +done in any callbacks. This does not work: + +

+

x.js: + +

+
setTimeout(function() {
+  module.exports = { a: "hello" };
+}, 0);
+

y.js: + +

+
var x = require('./x');
+console.log(x.a);
+

module.require(id)#

+
    +
  • id String
    • +
  • Return: Object exports from the resolved module
    • +
+

The module.require method provides a way to load a module as if +require() was called from the original module. + +

+

Note that in order to do this, you must get a reference to the module +object. Since require() returns the exports, and the module is +typically only available within a specific module's code, it must be +explicitly exported in order to be used. + + +

+

module.id#

+
    +
  • String
    • +
+

The identifier for the module. Typically this is the fully resolved +filename. + + +

+

module.filename#

+
    +
  • String
    • +
+

The fully resolved filename to the module. + + +

+

module.loaded#

+
    +
  • Boolean
    • +
+

Whether or not the module is done loading, or is in the process of +loading. + + +

+

module.parent#

+
    +
  • Module Object
    • +
+

The module that required this one. + + +

+

module.children#

+
    +
  • Array
    • +
+

The module objects required by this one. + + + +

+

All Together...#

+ + +

To get the exact filename that will be loaded when require() is called, use +the require.resolve() function. + +

+

Putting together all of the above, here is the high-level algorithm +in pseudocode of what require.resolve does: + +

+
require(X) from module at path Y
+1. If X is a core module,
+   a. return the core module
+   b. STOP
+2. If X begins with './' or '/' or '../'
+   a. LOAD_AS_FILE(Y + X)
+   b. LOAD_AS_DIRECTORY(Y + X)
+3. LOAD_NODE_MODULES(X, dirname(Y))
+4. THROW "not found"
+
+LOAD_AS_FILE(X)
+1. If X is a file, load X as JavaScript text.  STOP
+2. If X.js is a file, load X.js as JavaScript text.  STOP
+3. If X.node is a file, load X.node as binary addon.  STOP
+
+LOAD_AS_DIRECTORY(X)
+1. If X/package.json is a file,
+   a. Parse X/package.json, and look for "main" field.
+   b. let M = X + (json main field)
+   c. LOAD_AS_FILE(M)
+2. If X/index.js is a file, load X/index.js as JavaScript text.  STOP
+3. If X/index.node is a file, load X/index.node as binary addon.  STOP
+
+LOAD_NODE_MODULES(X, START)
+1. let DIRS=NODE_MODULES_PATHS(START)
+2. for each DIR in DIRS:
+   a. LOAD_AS_FILE(DIR/X)
+   b. LOAD_AS_DIRECTORY(DIR/X)
+
+NODE_MODULES_PATHS(START)
+1. let PARTS = path split(START)
+2. let ROOT = index of first instance of "node_modules" in PARTS, or 0
+3. let I = count of PARTS - 1
+4. let DIRS = []
+5. while I > ROOT,
+   a. if PARTS[I] = "node_modules" CONTINUE
+   c. DIR = path join(PARTS[0 .. I] + "node_modules")
+   b. DIRS = DIRS + DIR
+   c. let I = I - 1
+6. return DIRS
+

Loading from the global folders#

+ + +

If the NODE_PATH environment variable is set to a colon-delimited list +of absolute paths, then node will search those paths for modules if they +are not found elsewhere. (Note: On Windows, NODE_PATH is delimited by +semicolons instead of colons.) + +

+

Additionally, node will search in the following locations: + +

+
    +
  • 1: $HOME/.node_modules
    • +
  • 2: $HOME/.node_libraries
    • +
  • 3: $PREFIX/lib/node
    • +
+

Where $HOME is the user's home directory, and $PREFIX is node's +configured installPrefix. + +

+

These are mostly for historic reasons. You are highly encouraged to +place your dependencies locally in node_modules folders. They will be +loaded faster, and more reliably. + +

+

Accessing the main module#

+ + +

When a file is run directly from Node, require.main is set to its +module. That means that you can determine whether a file has been run +directly by testing + +

+
require.main === module
+

For a file foo.js, this will be true if run via node foo.js, but +false if run by require('./foo'). + +

+

Because module provides a filename property (normally equivalent to +__filename), the entry point of the current application can be obtained +by checking require.main.filename. + +

+

Addenda: Package Manager Tips#

+ + +

The semantics of Node's require() function were designed to be general +enough to support a number of sane directory structures. Package manager +programs such as dpkg, rpm, and npm will hopefully find it possible to +build native packages from Node modules without modification. + +

+

Below we give a suggested directory structure that could work: + +

+

Let's say that we wanted to have the folder at +/usr/lib/node/<some-package>/<some-version> hold the contents of a +specific version of a package. + +

+

Packages can depend on one another. In order to install package foo, you +may have to install a specific version of package bar. The bar package +may itself have dependencies, and in some cases, these dependencies may even +collide or form cycles. + +

+

Since Node looks up the realpath of any modules it loads (that is, +resolves symlinks), and then looks for their dependencies in the +node_modules folders as described above, this situation is very simple to +resolve with the following architecture: + +

+
    +
  • /usr/lib/node/foo/1.2.3/ - Contents of the foo package, version 1.2.3.
    • +
  • /usr/lib/node/bar/4.3.2/ - Contents of the bar package that foo +depends on.
    • +
  • /usr/lib/node/foo/1.2.3/node_modules/bar - Symbolic link to +/usr/lib/node/bar/4.3.2/.
    • +
  • /usr/lib/node/bar/4.3.2/node_modules/* - Symbolic links to the packages +that bar depends on.
    • +
+

Thus, even if a cycle is encountered, or if there are dependency +conflicts, every module will be able to get a version of its dependency +that it can use. + +

+

When the code in the foo package does require('bar'), it will get the +version that is symlinked into /usr/lib/node/foo/1.2.3/node_modules/bar. +Then, when the code in the bar package calls require('quux'), it'll get +the version that is symlinked into +/usr/lib/node/bar/4.3.2/node_modules/quux. + +

+

Furthermore, to make the module lookup process even more optimal, rather +than putting packages directly in /usr/lib/node, we could put them in +/usr/lib/node_modules/<name>/<version>. Then node will not bother +looking for missing dependencies in /usr/node_modules or /node_modules. + +

+

In order to make modules available to the node REPL, it might be useful to +also add the /usr/lib/node_modules folder to the $NODE_PATH environment +variable. Since the module lookups using node_modules folders are all +relative, and based on the real path of the files making the calls to +require(), the packages themselves can be anywhere. + +

+

Addons#

+

Addons are dynamically linked shared objects. They can provide glue to C and +C++ libraries. The API (at the moment) is rather complex, involving +knowledge of several libraries: + +

+
    +

  • V8 JavaScript, a C++ library. Used for interfacing with JavaScript: +creating objects, calling functions, etc. Documented mostly in the +v8.h header file (deps/v8/include/v8.h in the Node source tree), +which is also available online.

    +
    • +

  • libuv, C event loop library. Anytime one +needs to wait for a file descriptor to become readable, wait for a timer, or +wait for a signal to received one will need to interface with libuv. That is, +if you perform any I/O, libuv will need to be used.

    +
    • +

  • Internal Node libraries. Most importantly is the node::ObjectWrap +class which you will likely want to derive from.

    +
    • +

  • Others. Look in deps/ for what else is available.

    +
    • +
+

Node statically compiles all its dependencies into the executable. When +compiling your module, you don't need to worry about linking to any of these +libraries. + + +

+

Hello world#

+

To get started let's make a small Addon which is the C++ equivalent of +the following Javascript code: + +

+
exports.hello = function() { return 'world'; };
+

First we create a file hello.cc: + +

+
#include <node.h>
+#include <v8.h>
+
+using namespace v8;
+
+Handle<Value> Method(const Arguments& args) {
+  HandleScope scope;
+  return scope.Close(String::New("world"));
+}
+
+void init(Handle<Object> target) {
+  target->Set(String::NewSymbol("hello"),
+      FunctionTemplate::New(Method)->GetFunction());
+}
+NODE_MODULE(hello, init)
+

Note that all Node addons must export an initialization function: + +

+
void Initialize (Handle<Object> target);
+NODE_MODULE(module_name, Initialize)
+

There is no semi-colon after NODE_MODULE as it's not a function (see node.h). + +

+

The module_name needs to match the filename of the final binary (minus the +.node suffix). + +

+

The source code needs to be built into hello.node, the binary Addon. To +do this we create a file called wscript which is python code and looks +like this: + +

+
srcdir = '.'
+blddir = 'build'
+VERSION = '0.0.1'
+
+def set_options(opt):
+  opt.tool_options('compiler_cxx')
+
+def configure(conf):
+  conf.check_tool('compiler_cxx')
+  conf.check_tool('node_addon')
+
+def build(bld):
+  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
+  obj.target = 'hello'
+  obj.source = 'hello.cc'
+

Running node-waf configure build will create a file +build/default/hello.node which is our Addon. + +

+

node-waf is just WAF, the python-based build system. node-waf is +provided for the ease of users. + +

+

You can now use the binary addon in a Node project hello.js by pointing require to +the recently built module: + +

+
var addon = require('./build/Release/hello');
+
+console.log(addon.hello()); // 'world'
+

Please see patterns below for further information or +

+

https://github.com/pietern/hiredis-node for an example in production. + + +

+

Addon patterns#

+

Below are some addon patterns to help you get started. Consult the online +v8 reference for help with the various v8 +calls, and v8's Embedder's Guide +for an explanation of several concepts used such as handles, scopes, +function templates, etc. + +

+

To compile these examples, create the wscript file below and run +node-waf configure build: + +

+
srcdir = '.'
+blddir = 'build'
+VERSION = '0.0.1'
+
+def set_options(opt):
+  opt.tool_options('compiler_cxx')
+
+def configure(conf):
+  conf.check_tool('compiler_cxx')
+  conf.check_tool('node_addon')
+
+def build(bld):
+  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
+  obj.target = 'addon'
+  obj.source = ['addon.cc']
+

In cases where there is more than one .cc file, simply add the file name to the +obj.source array, e.g.: + +

+
obj.source = ['addon.cc', 'myexample.cc']
+

Function arguments#

+

The following pattern illustrates how to read arguments from JavaScript +function calls and return a result. This is the main and only needed source +addon.cc: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+
+using namespace v8;
+
+Handle<Value> Add(const Arguments& args) {
+  HandleScope scope;
+
+  if (args.Length() < 2) {
+    ThrowException(Exception::TypeError(String::New("Wrong number of arguments")));
+    return scope.Close(Undefined());
+  }
+
+  if (!args[0]->IsNumber() || !args[1]->IsNumber()) {
+    ThrowException(Exception::TypeError(String::New("Wrong arguments")));
+    return scope.Close(Undefined());
+  }
+
+  Local<Number> num = Number::New(args[0]->NumberValue() +
+      args[1]->NumberValue());
+  return scope.Close(num);
+}
+
+void Init(Handle<Object> target) {
+  target->Set(String::NewSymbol("add"),
+      FunctionTemplate::New(Add)->GetFunction());
+}
+
+NODE_MODULE(addon, Init)
+

You can test it with the following JavaScript snippet: + +

+
var addon = require('./build/Release/addon');
+
+console.log( 'This should be eight:', addon.add(3,5) );
+

Callbacks#

+

You can pass JavaScript functions to a C++ function and execute them from +there. Here's addon.cc: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+
+using namespace v8;
+
+Handle<Value> RunCallback(const Arguments& args) {
+  HandleScope scope;
+
+  Local<Function> cb = Local<Function>::Cast(args[0]);
+  const unsigned argc = 1;
+  Local<Value> argv[argc] = { Local<Value>::New(String::New("hello world")) };
+  cb->Call(Context::GetCurrent()->Global(), argc, argv);
+
+  return scope.Close(Undefined());
+}
+
+void Init(Handle<Object> target) {
+  target->Set(String::NewSymbol("runCallback"),
+      FunctionTemplate::New(RunCallback)->GetFunction());
+}
+
+NODE_MODULE(addon, Init)
+

To test it run the following JavaScript snippet: + +

+
var addon = require('./build/Release/addon');
+
+addon.runCallback(function(msg){
+  console.log(msg); // 'hello world'
+});
+

Object factory#

+

You can create and return new objects from within a C++ function with this +addon.cc pattern, which returns an object with property msg that echoes +the string passed to createObject(): + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+
+using namespace v8;
+
+Handle<Value> CreateObject(const Arguments& args) {
+  HandleScope scope;
+
+  Local<Object> obj = Object::New();
+  obj->Set(String::NewSymbol("msg"), args[0]->ToString());
+
+  return scope.Close(obj);
+}
+
+void Init(Handle<Object> target) {
+  target->Set(String::NewSymbol("createObject"),
+      FunctionTemplate::New(CreateObject)->GetFunction());
+}
+
+NODE_MODULE(addon, Init)
+

To test it in JavaScript: + +

+
var addon = require('./build/Release/addon');
+
+var obj1 = addon.createObject('hello');
+var obj2 = addon.createObject('world');
+console.log(obj1.msg+' '+obj2.msg); // 'hello world'
+

Function factory#

+

This pattern illustrates how to create and return a JavaScript function that +wraps a C++ function: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+
+using namespace v8;
+
+Handle<Value> MyFunction(const Arguments& args) {
+  HandleScope scope;
+  return scope.Close(String::New("hello world"));
+}
+
+Handle<Value> CreateFunction(const Arguments& args) {
+  HandleScope scope;
+
+  Local<FunctionTemplate> tpl = FunctionTemplate::New(MyFunction);
+  Local<Function> fn = tpl->GetFunction();
+  fn->SetName(String::NewSymbol("theFunction")); // omit this to make it anonymous
+
+  return scope.Close(fn);
+}
+
+void Init(Handle<Object> target) {
+  target->Set(String::NewSymbol("createFunction"),
+      FunctionTemplate::New(CreateFunction)->GetFunction());
+}
+
+NODE_MODULE(addon, Init)
+

To test: + +

+
var addon = require('./build/Release/addon');
+
+var fn = addon.createFunction();
+console.log(fn()); // 'hello world'
+

Wrapping C++ objects#

+

Here we will create a wrapper for a C++ object/class MyObject that can be +instantiated in JavaScript through the new operator. First prepare the main +module addon.cc: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+void InitAll(Handle<Object> target) {
+  MyObject::Init(target);
+}
+
+NODE_MODULE(addon, InitAll)
+

Then in myobject.h make your wrapper inherit from node::ObjectWrap: + +

+
#ifndef MYOBJECT_H
+#define MYOBJECT_H
+
+#include <node.h>
+
+class MyObject : public node::ObjectWrap {
+ public:
+  static void Init(v8::Handle<v8::Object> target);
+
+ private:
+  MyObject();
+  ~MyObject();
+
+  static v8::Handle<v8::Value> New(const v8::Arguments& args);
+  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);
+  double counter_;
+};
+
+#endif
+

And in myobject.cc implement the various methods that you want to expose. +Here we expose the method plusOne by adding it to the constructor's +prototype: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+MyObject::MyObject() {};
+MyObject::~MyObject() {};
+
+void MyObject::Init(Handle<Object> target) {
+  // Prepare constructor template
+  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
+  tpl->SetClassName(String::NewSymbol("MyObject"));
+  tpl->InstanceTemplate()->SetInternalFieldCount(1);
+  // Prototype
+  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),
+      FunctionTemplate::New(PlusOne)->GetFunction());
+
+  Persistent<Function> constructor = Persistent<Function>::New(tpl->GetFunction());
+  target->Set(String::NewSymbol("MyObject"), constructor);
+}
+
+Handle<Value> MyObject::New(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj = new MyObject();
+  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
+  obj->Wrap(args.This());
+
+  return args.This();
+}
+
+Handle<Value> MyObject::PlusOne(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());
+  obj->counter_ += 1;
+
+  return scope.Close(Number::New(obj->counter_));
+}
+

Test it with: + +

+
var addon = require('./build/Release/addon');
+
+var obj = new addon.MyObject(10);
+console.log( obj.plusOne() ); // 11
+console.log( obj.plusOne() ); // 12
+console.log( obj.plusOne() ); // 13
+

Factory of wrapped objects#

+

This is useful when you want to be able to create native objects without +explicitly instantiating them with the new operator in JavaScript, e.g. + +

+
var obj = addon.createObject();
+// instead of:
+// var obj = new addon.Object();
+

Let's register our createObject method in addon.cc: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+Handle<Value> CreateObject(const Arguments& args) {
+  HandleScope scope;
+  return scope.Close(MyObject::NewInstance(args));
+}
+
+void InitAll(Handle<Object> target) {
+  MyObject::Init();
+
+  target->Set(String::NewSymbol("createObject"),
+      FunctionTemplate::New(CreateObject)->GetFunction());
+}
+
+NODE_MODULE(addon, InitAll)
+

In myobject.h we now introduce the static method NewInstance that takes +care of instantiating the object (i.e. it does the job of new in JavaScript): + +

+
#define BUILDING_NODE_EXTENSION
+#ifndef MYOBJECT_H
+#define MYOBJECT_H
+
+#include <node.h>
+
+class MyObject : public node::ObjectWrap {
+ public:
+  static void Init();
+  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);
+
+ private:
+  MyObject();
+  ~MyObject();
+
+  static v8::Persistent<v8::Function> constructor;
+  static v8::Handle<v8::Value> New(const v8::Arguments& args);
+  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);
+  double counter_;
+};
+
+#endif
+

The implementation is similar to the above in myobject.cc: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+MyObject::MyObject() {};
+MyObject::~MyObject() {};
+
+Persistent<Function> MyObject::constructor;
+
+void MyObject::Init() {
+  // Prepare constructor template
+  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
+  tpl->SetClassName(String::NewSymbol("MyObject"));
+  tpl->InstanceTemplate()->SetInternalFieldCount(1);
+  // Prototype
+  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),
+      FunctionTemplate::New(PlusOne)->GetFunction());
+
+  constructor = Persistent<Function>::New(tpl->GetFunction());
+}
+
+Handle<Value> MyObject::New(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj = new MyObject();
+  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
+  obj->Wrap(args.This());
+
+  return args.This();
+}
+
+Handle<Value> MyObject::NewInstance(const Arguments& args) {
+  HandleScope scope;
+
+  const unsigned argc = 1;
+  Handle<Value> argv[argc] = { args[0] };
+  Local<Object> instance = constructor->NewInstance(argc, argv);
+
+  return scope.Close(instance);
+}
+
+Handle<Value> MyObject::PlusOne(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());
+  obj->counter_ += 1;
+
+  return scope.Close(Number::New(obj->counter_));
+}
+

Test it with: + +

+
var addon = require('./build/Release/addon');
+
+var obj = addon.createObject(10);
+console.log( obj.plusOne() ); // 11
+console.log( obj.plusOne() ); // 12
+console.log( obj.plusOne() ); // 13
+
+var obj2 = addon.createObject(20);
+console.log( obj2.plusOne() ); // 21
+console.log( obj2.plusOne() ); // 22
+console.log( obj2.plusOne() ); // 23
+

Passing wrapped objects around#

+

In addition to wrapping and returning C++ objects, you can pass them around +by unwrapping them with Node's node::ObjectWrap::Unwrap helper function. +In the following addon.cc we introduce a function add() that can take on two +MyObject objects: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+Handle<Value> CreateObject(const Arguments& args) {
+  HandleScope scope;
+  return scope.Close(MyObject::NewInstance(args));
+}
+
+Handle<Value> Add(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(
+      args[0]->ToObject());
+  MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(
+      args[1]->ToObject());
+
+  double sum = obj1->Val() + obj2->Val();
+  return scope.Close(Number::New(sum));
+}
+
+void InitAll(Handle<Object> target) {
+  MyObject::Init();
+
+  target->Set(String::NewSymbol("createObject"),
+      FunctionTemplate::New(CreateObject)->GetFunction());
+
+  target->Set(String::NewSymbol("add"),
+      FunctionTemplate::New(Add)->GetFunction());
+}
+
+NODE_MODULE(addon, InitAll)
+

To make things interesting we introduce a public method in myobject.h so we +can probe private values after unwrapping the object: + +

+
#define BUILDING_NODE_EXTENSION
+#ifndef MYOBJECT_H
+#define MYOBJECT_H
+
+#include <node.h>
+
+class MyObject : public node::ObjectWrap {
+ public:
+  static void Init();
+  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);
+  double Val() const { return val_; }
+
+ private:
+  MyObject();
+  ~MyObject();
+
+  static v8::Persistent<v8::Function> constructor;
+  static v8::Handle<v8::Value> New(const v8::Arguments& args);
+  double val_;
+};
+
+#endif
+

The implementation of myobject.cc is similar as before: + +

+
#define BUILDING_NODE_EXTENSION
+#include <node.h>
+#include "myobject.h"
+
+using namespace v8;
+
+MyObject::MyObject() {};
+MyObject::~MyObject() {};
+
+Persistent<Function> MyObject::constructor;
+
+void MyObject::Init() {
+  // Prepare constructor template
+  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
+  tpl->SetClassName(String::NewSymbol("MyObject"));
+  tpl->InstanceTemplate()->SetInternalFieldCount(1);
+
+  constructor = Persistent<Function>::New(tpl->GetFunction());
+}
+
+Handle<Value> MyObject::New(const Arguments& args) {
+  HandleScope scope;
+
+  MyObject* obj = new MyObject();
+  obj->val_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
+  obj->Wrap(args.This());
+
+  return args.This();
+}
+
+Handle<Value> MyObject::NewInstance(const Arguments& args) {
+  HandleScope scope;
+
+  const unsigned argc = 1;
+  Handle<Value> argv[argc] = { args[0] };
+  Local<Object> instance = constructor->NewInstance(argc, argv);
+
+  return scope.Close(instance);
+}
+

Test it with: + +

+
var addon = require('./build/Release/addon');
+
+var obj1 = addon.createObject(10);
+var obj2 = addon.createObject(20);
+var result = addon.add(obj1, obj2);
+
+console.log(result); // 30
+

process#

+ + +

The process object is a global object and can be accessed from anywhere. +It is an instance of EventEmitter. + + +

+

Event: 'exit'#

+

Emitted when the process is about to exit. This is a good hook to perform +constant time checks of the module's state (like for unit tests). The main +event loop will no longer be run after the 'exit' callback finishes, so +timers may not be scheduled. + +

+

Example of listening for exit: + +

+
process.on('exit', function () {
+  process.nextTick(function () {
+   console.log('This will not run');
+  });
+  console.log('About to exit.');
+});
+

Event: 'uncaughtException'#

+

Emitted when an exception bubbles all the way back to the event loop. If a +listener is added for this exception, the default action (which is to print +a stack trace and exit) will not occur. + +

+

Example of listening for uncaughtException: + +

+
process.on('uncaughtException', function (err) {
+  console.log('Caught exception: ' + err);
+});
+
+setTimeout(function () {
+  console.log('This will still run.');
+}, 500);
+
+// Intentionally cause an exception, but don't catch it.
+nonexistentFunc();
+console.log('This will not run.');
+

Note that uncaughtException is a very crude mechanism for exception +handling. Using try / catch in your program will give you more control over +your program's flow. Especially for server programs that are designed to +stay running forever, uncaughtException can be a useful safety mechanism. + + +

+

Signal Events#

+ + + +

Emitted when the processes receives a signal. See sigaction(2) for a list of +standard POSIX signal names such as SIGINT, SIGUSR1, etc. + +

+

Example of listening for SIGINT: + +

+
// Start reading from stdin so we don't exit.
+process.stdin.resume();
+
+process.on('SIGINT', function () {
+  console.log('Got SIGINT.  Press Control-D to exit.');
+});
+

An easy way to send the SIGINT signal is with Control-C in most terminal +programs. + + +

+

process.stdout#

+

A Writable Stream to stdout. + +

+

Example: the definition of console.log + +

+
console.log = function (d) {
+  process.stdout.write(d + '\n');
+};
+

process.stderr and process.stdout are unlike other streams in Node in +that writes to them are usually blocking. They are blocking in the case +that they refer to regular files or TTY file descriptors. In the case they +refer to pipes, they are non-blocking like other streams. + + +

+

process.stderr#

+

A writable stream to stderr. + +

+

process.stderr and process.stdout are unlike other streams in Node in +that writes to them are usually blocking. They are blocking in the case +that they refer to regular files or TTY file descriptors. In the case they +refer to pipes, they are non-blocking like other streams. + + +

+

process.stdin#

+

A Readable Stream for stdin. The stdin stream is paused by default, so one +must call process.stdin.resume() to read from it. + +

+

Example of opening standard input and listening for both events: + +

+
process.stdin.resume();
+process.stdin.setEncoding('utf8');
+
+process.stdin.on('data', function (chunk) {
+  process.stdout.write('data: ' + chunk);
+});
+
+process.stdin.on('end', function () {
+  process.stdout.write('end');
+});
+

process.argv#

+

An array containing the command line arguments. The first element will be +'node', the second element will be the name of the JavaScript file. The +next elements will be any additional command line arguments. + +

+
// print process.argv
+process.argv.forEach(function (val, index, array) {
+  console.log(index + ': ' + val);
+});
+

This will generate: + +

+
$ node process-2.js one two=three four
+0: node
+1: /Users/mjr/work/node/process-2.js
+2: one
+3: two=three
+4: four
+

process.execPath#

+

This is the absolute pathname of the executable that started the process. + +

+

Example: + +

+
/usr/local/bin/node
+

process.chdir(directory)#

+

Changes the current working directory of the process or throws an exception if that fails. + +

+
console.log('Starting directory: ' + process.cwd());
+try {
+  process.chdir('/tmp');
+  console.log('New directory: ' + process.cwd());
+}
+catch (err) {
+  console.log('chdir: ' + err);
+}
+

process.cwd()#

+

Returns the current working directory of the process. + +

+
console.log('Current directory: ' + process.cwd());
+

process.env#

+

An object containing the user environment. See environ(7). + + +

+

process.exit([code])#

+

Ends the process with the specified code. If omitted, exit uses the +'success' code 0. + +

+

To exit with a 'failure' code: + +

+
process.exit(1);
+

The shell that executed node should see the exit code as 1. + + +

+

process.getgid()#

+

Gets the group identity of the process. (See getgid(2).) +This is the numerical group id, not the group name. + +

+
console.log('Current gid: ' + process.getgid());
+

process.setgid(id)#

+

Sets the group identity of the process. (See setgid(2).) This accepts either +a numerical ID or a groupname string. If a groupname is specified, this method +blocks while resolving it to a numerical ID. + +

+
console.log('Current gid: ' + process.getgid());
+try {
+  process.setgid(501);
+  console.log('New gid: ' + process.getgid());
+}
+catch (err) {
+  console.log('Failed to set gid: ' + err);
+}
+

process.getuid()#

+

Gets the user identity of the process. (See getuid(2).) +This is the numerical userid, not the username. + +

+
console.log('Current uid: ' + process.getuid());
+

process.setuid(id)#

+

Sets the user identity of the process. (See setuid(2).) This accepts either +a numerical ID or a username string. If a username is specified, this method +blocks while resolving it to a numerical ID. + +

+
console.log('Current uid: ' + process.getuid());
+try {
+  process.setuid(501);
+  console.log('New uid: ' + process.getuid());
+}
+catch (err) {
+  console.log('Failed to set uid: ' + err);
+}
+

process.version#

+

A compiled-in property that exposes NODE_VERSION. + +

+
console.log('Version: ' + process.version);
+

process.versions#

+

A property exposing version strings of node and its dependencies. + +

+
console.log(process.versions);
+

Will output: + +

+
{ node: '0.4.12',
+  v8: '3.1.8.26',
+  ares: '1.7.4',
+  ev: '4.4',
+  openssl: '1.0.0e-fips' }
+

process.installPrefix#

+

A compiled-in property that exposes NODE_PREFIX. + +

+
console.log('Prefix: ' + process.installPrefix);
+

process.kill(pid, [signal])#

+

Send a signal to a process. pid is the process id and signal is the +string describing the signal to send. Signal names are strings like +'SIGINT' or 'SIGUSR1'. If omitted, the signal will be 'SIGTERM'. +See kill(2) for more information. + +

+

Note that just because the name of this function is process.kill, it is +really just a signal sender, like the kill system call. The signal sent +may do something other than kill the target process. + +

+

Example of sending a signal to yourself: + +

+
process.on('SIGHUP', function () {
+  console.log('Got SIGHUP signal.');
+});
+
+setTimeout(function () {
+  console.log('Exiting.');
+  process.exit(0);
+}, 100);
+
+process.kill(process.pid, 'SIGHUP');
+

process.pid#

+

The PID of the process. + +

+
console.log('This process is pid ' + process.pid);
+

process.title#

+

Getter/setter to set what is displayed in 'ps'. + + +

+

process.arch#

+

What processor architecture you're running on: 'arm', 'ia32', or 'x64'. + +

+
console.log('This processor architecture is ' + process.arch);
+

process.platform#

+

What platform you're running on. 'linux2', 'darwin', etc. + +

+
console.log('This platform is ' + process.platform);
+

process.memoryUsage()#

+

Returns an object describing the memory usage of the Node process +measured in bytes. + +

+
var util = require('util');
+
+console.log(util.inspect(process.memoryUsage()));
+

This will generate: + +

+
{ rss: 4935680,
+  heapTotal: 1826816,
+  heapUsed: 650472 }
+

heapTotal and heapUsed refer to V8's memory usage. + + +

+

process.nextTick(callback)#

+

On the next loop around the event loop call this callback. +This is not a simple alias to setTimeout(fn, 0), it's much more +efficient. + +

+
process.nextTick(function () {
+  console.log('nextTick callback');
+});
+

process.umask([mask])#

+

Sets or reads the process's file mode creation mask. Child processes inherit +the mask from the parent process. Returns the old mask if mask argument is +given, otherwise returns the current mask. + +

+
var oldmask, newmask = 0644;
+
+oldmask = process.umask(newmask);
+console.log('Changed umask from: ' + oldmask.toString(8) +
+            ' to ' + newmask.toString(8));
+

process.uptime()#

+

Number of seconds Node has been running. + +

+

util#

+
Stability: 5 - Locked
+

These functions are in the module 'util'. Use require('util') to access +them. + + +

+

util.format()#

+

Returns a formatted string using the first argument as a printf-like format. + +

+

The first argument is a string that contains zero or more placeholders. +Each placeholder is replaced with the converted value from its corresponding +argument. Supported placeholders are: + +

+
    +
  • %s - String.
    • +
  • %d - Number (both integer and float).
    • +
  • %j - JSON.
    • +
  • %% - single percent sign ('%'). This does not consume an argument.
    • +
+

If the placeholder does not have a corresponding argument, the placeholder is +not replaced. + +

+
util.format('%s:%s', 'foo'); // 'foo:%s'
+

If there are more arguments than placeholders, the extra arguments are +converted to strings with util.inspect() and these strings are concatenated, +delimited by a space. + +

+
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
+

If the first argument is not a format string then util.format() returns +a string that is the concatenation of all its arguments separated by spaces. +Each argument is converted to a string with util.inspect(). + +

+
util.format(1, 2, 3); // '1 2 3'
+

util.debug(string)#

+

A synchronous output function. Will block the process and +output string immediately to stderr. + +

+
require('util').debug('message on stderr');
+

util.log(string)#

+

Output with timestamp on stdout. + +

+
require('util').log('Timestamped message.');
+

util.inspect(object, [showHidden], [depth], [colors])#

+

Return a string representation of object, which is useful for debugging. + +

+

If showHidden is true, then the object's non-enumerable properties will be +shown too. Defaults to false. + +

+

If depth is provided, it tells inspect how many times to recurse while +formatting the object. This is useful for inspecting large complicated objects. + +

+

The default is to only recurse twice. To make it recurse indefinitely, pass +in null for depth. + +

+

If colors is true, the output will be styled with ANSI color codes. +Defaults to false. + +

+

Example of inspecting all properties of the util object: + +

+
var util = require('util');
+
+console.log(util.inspect(util, true, null));
+

util.isArray(object)#

+

Returns true if the given "object" is an Array. false otherwise. + +

+
var util = require('util');
+
+util.isArray([])
+  // true
+util.isArray(new Array)
+  // true
+util.isArray({})
+  // false
+

util.isRegExp(object)#

+

Returns true if the given "object" is a RegExp. false otherwise. + +

+
var util = require('util');
+
+util.isRegExp(/some regexp/)
+  // true
+util.isRegExp(new RegExp('another regexp'))
+  // true
+util.isRegExp({})
+  // false
+

util.isDate(object)#

+

Returns true if the given "object" is a Date. false otherwise. + +

+
var util = require('util');
+
+util.isDate(new Date())
+  // true
+util.isDate(Date())
+  // false (without 'new' returns a String)
+util.isDate({})
+  // false
+

util.isError(object)#

+

Returns true if the given "object" is an Error. false otherwise. + +

+
var util = require('util');
+
+util.isError(new Error())
+  // true
+util.isError(new TypeError())
+  // true
+util.isError({ name: 'Error', message: 'an error occurred' })
+  // false
+

util.pump(readableStream, writableStream, [callback])#

+

Experimental + +

+

Read the data from readableStream and send it to the writableStream. +When writableStream.write(data) returns false readableStream will be +paused until the drain event occurs on the writableStream. callback gets +an error as its only argument and is called when writableStream is closed or +when an error occurs. + + +

+

util.inherits(constructor, superConstructor)#

+

Inherit the prototype methods from one +constructor +into another. The prototype of constructor will be set to a new +object created from superConstructor. + +

+

As an additional convenience, superConstructor will be accessible +through the constructor.super_ property. + +

+
var util = require("util");
+var events = require("events");
+
+function MyStream() {
+    events.EventEmitter.call(this);
+}
+
+util.inherits(MyStream, events.EventEmitter);
+
+MyStream.prototype.write = function(data) {
+    this.emit("data", data);
+}
+
+var stream = new MyStream();
+
+console.log(stream instanceof events.EventEmitter); // true
+console.log(MyStream.super_ === events.EventEmitter); // true
+
+stream.on("data", function(data) {
+    console.log('Received data: "' + data + '"');
+})
+stream.write("It works!"); // Received data: "It works!"
+

Events#

+
Stability: 4 - API Frozen
+ + +

Many objects in Node emit events: a net.Server emits an event each time +a peer connects to it, a fs.readStream emits an event when the file is +opened. All objects which emit events are instances of events.EventEmitter. +You can access this module by doing: require("events"); + +

+

Typically, event names are represented by a camel-cased string, however, +there aren't any strict restrictions on that, as any string will be accepted. + +

+

Functions can then be attached to objects, to be executed when an event +is emitted. These functions are called listeners. + + +

+

Class: events.EventEmitter#

+

To access the EventEmitter class, require('events').EventEmitter. + +

+

When an EventEmitter instance experiences an error, the typical action is +to emit an 'error' event. Error events are treated as a special case in node. +If there is no listener for it, then the default action is to print a stack +trace and exit the program. + +

+

All EventEmitters emit the event 'newListener' when new listeners are +added. + +

+

emitter.addListener(event, listener)#

+

emitter.on(event, listener)#

+

Adds a listener to the end of the listeners array for the specified event. + +

+
server.on('connection', function (stream) {
+  console.log('someone connected!');
+});
+

emitter.once(event, listener)#

+

Adds a one time listener for the event. This listener is +invoked only the next time the event is fired, after which +it is removed. + +

+
server.once('connection', function (stream) {
+  console.log('Ah, we have our first user!');
+});
+

emitter.removeListener(event, listener)#

+

Remove a listener from the listener array for the specified event. +Caution: changes array indices in the listener array behind the listener. + +

+
var callback = function(stream) {
+  console.log('someone connected!');
+};
+server.on('connection', callback);
+// ...
+server.removeListener('connection', callback);
+

emitter.removeAllListeners([event])#

+

Removes all listeners, or those of the specified event. + + +

+

emitter.setMaxListeners(n)#

+

By default EventEmitters will print a warning if more than 10 listeners are +added for a particular event. This is a useful default which helps finding memory leaks. +Obviously not all Emitters should be limited to 10. This function allows +that to be increased. Set to zero for unlimited. + + +

+

emitter.listeners(event)#

+

Returns an array of listeners for the specified event. This array can be +manipulated, e.g. to remove listeners. + +

+
server.on('connection', function (stream) {
+  console.log('someone connected!');
+});
+console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
+

emitter.emit(event, [arg1], [arg2], [...])#

+

Execute each of the listeners in order with the supplied arguments. + +

+

Event: 'newListener'#

+
    +
  • event String The event name
    • +
  • listener Function The event handler function
    • +
+

This event is emitted any time someone adds a new listener. + +

+

Buffer#

+
Stability: 3 - Stable
+

Pure Javascript is Unicode friendly but not nice to binary data. When +dealing with TCP streams or the file system, it's necessary to handle octet +streams. Node has several strategies for manipulating, creating, and +consuming octet streams. + +

+

Raw data is stored in instances of the Buffer class. A Buffer is similar +to an array of integers but corresponds to a raw memory allocation outside +the V8 heap. A Buffer cannot be resized. + +

+

The Buffer class is a global, making it very rare that one would need +to ever require('buffer'). + +

+

Converting between Buffers and JavaScript string objects requires an explicit +encoding method. Here are the different string encodings. + +

+
    +

  • 'ascii' - for 7 bit ASCII data only. This encoding method is very fast, and +will strip the high bit if set. +Note that this encoding converts a null character ('\0' or '\u0000') into +0x20 (character code of a space). If you want to convert a null character +into 0x00, you should use 'utf8'.

    +
    • +

  • 'utf8' - Multi byte encoded Unicode characters. Many web pages and other document formats use UTF-8.

    +
    • +

  • 'ucs2' - 2-bytes, little endian encoded Unicode characters. It can encode +only BMP(Basic Multilingual Plane, U+0000 - U+FFFF).

    +
    • +

  • 'base64' - Base64 string encoding.

    +
    • +

  • 'binary' - A way of encoding raw binary data into strings by using only +the first 8 bits of each character. This encoding method is deprecated and +should be avoided in favor of Buffer objects where possible. This encoding +will be removed in future versions of Node.

    +
    • +

  • 'hex' - Encode each byte as two hexidecimal characters.

    +
    • +
+

Class: Buffer#

+

The Buffer class is a global type for dealing with binary data directly. +It can be constructed in a variety of ways. + +

+

new Buffer(size)#

+
    +
  • size Number
    • +
+

Allocates a new buffer of size octets. + +

+

new Buffer(array)#

+
    +
  • array Array
    • +
+

Allocates a new buffer using an array of octets. + +

+

new Buffer(str, [encoding])#

+
    +
  • str String - string to encode.
    • +
  • encoding String - encoding to use, Optional.
    • +
+

Allocates a new buffer containing the given str. +encoding defaults to 'utf8'. + +

+

buf.write(string, [offset], [length], [encoding])#

+
    +
  • string String - data to be written to buffer
    • +
  • offset Number, Optional, Default: 0
    • +
  • length Number, Optional, Default: buffer.length - offset
    • +
  • encoding String, Optional, Default: 'utf8'
    • +
+

Writes string to the buffer at offset using the given encoding. +offset defaults to 0, encoding defaults to 'utf8'. length is +the number of bytes to write. Returns number of octets written. If buffer did +not contain enough space to fit the entire string, it will write a partial +amount of the string. length defaults to buffer.length - offset. +The method will not write partial characters. + +

+
buf = new Buffer(256);
+len = buf.write('\u00bd + \u00bc = \u00be', 0);
+console.log(len + " bytes: " + buf.toString('utf8', 0, len));
+

The number of characters written (which may be different than the number of +bytes written) is set in Buffer._charsWritten and will be overwritten the +next time buf.write() is called. + + +

+

buf.toString([encoding], [start], [end])#

+
    +
  • encoding String, Optional, Default: 'utf8'
    • +
  • start Number, Optional, Default: 0
    • +
  • end Number, Optional, Default: buffer.length
    • +
+

Decodes and returns a string from buffer data encoded with encoding +(defaults to 'utf8') beginning at start (defaults to 0) and ending at +end (defaults to buffer.length). + +

+

See buffer.write() example, above. + + +

+

buf[index]#

+ + + +

Get and set the octet at index. The values refer to individual bytes, +so the legal range is between 0x00 and 0xFF hex or 0 and 255. + +

+

Example: copy an ASCII string into a buffer, one byte at a time: + +

+
str = "node.js";
+buf = new Buffer(str.length);
+
+for (var i = 0; i < str.length ; i++) {
+  buf[i] = str.charCodeAt(i);
+}
+
+console.log(buf);
+
+// node.js
+

Class Method: Buffer.isBuffer(obj)#

+
    +
  • obj Object
    • +
  • Return: Boolean
    • +
+

Tests if obj is a Buffer. + +

+

Class Method: Buffer.byteLength(string, [encoding])#

+
    +
  • string String
    • +
  • encoding String, Optional, Default: 'utf8'
    • +
  • Return: Number
    • +
+

Gives the actual byte length of a string. encoding defaults to 'utf8'. +This is not the same as String.prototype.length since that returns the +number of characters in a string. + +

+

Example: + +

+
str = '\u00bd + \u00bc = \u00be';
+
+console.log(str + ": " + str.length + " characters, " +
+  Buffer.byteLength(str, 'utf8') + " bytes");
+
+// ½ + ¼ = ¾: 9 characters, 12 bytes
+

buf.length#

+
    +
  • Number
    • +
+

The size of the buffer in bytes. Note that this is not necessarily the size +of the contents. length refers to the amount of memory allocated for the +buffer object. It does not change when the contents of the buffer are changed. + +

+
buf = new Buffer(1234);
+
+console.log(buf.length);
+buf.write("some string", "ascii", 0);
+console.log(buf.length);
+
+// 1234
+// 1234
+

buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])#

+
    +
  • targetBuffer Buffer object - Buffer to copy into
    • +
  • targetStart Number, Optional, Default: 0
    • +
  • sourceStart Number, Optional, Default: 0
    • +
  • sourceEnd Number, Optional, Default: buffer.length
    • +
+

Does copy between buffers. The source and target regions can be overlapped. +targetStart and sourceStart default to 0. +sourceEnd defaults to buffer.length. + +

+

Example: build two Buffers, then copy buf1 from byte 16 through byte 19 +into buf2, starting at the 8th byte in buf2. + +

+
buf1 = new Buffer(26);
+buf2 = new Buffer(26);
+
+for (var i = 0 ; i < 26 ; i++) {
+  buf1[i] = i + 97; // 97 is ASCII a
+  buf2[i] = 33; // ASCII !
+}
+
+buf1.copy(buf2, 8, 16, 20);
+console.log(buf2.toString('ascii', 0, 25));
+
+// !!!!!!!!qrst!!!!!!!!!!!!!
+

buf.slice([start], [end])#

+
    +
  • start Number, Optional, Default: 0
    • +
  • end Number, Optional, Default: buffer.length
    • +
+

Returns a new buffer which references the same memory as the old, but offset +and cropped by the start (defaults to 0) and end (defaults to +buffer.length) indexes. + +

+

Modifying the new buffer slice will modify memory in the original buffer! + +

+

Example: build a Buffer with the ASCII alphabet, take a slice, then modify one +byte from the original Buffer. + +

+
var buf1 = new Buffer(26);
+
+for (var i = 0 ; i < 26 ; i++) {
+  buf1[i] = i + 97; // 97 is ASCII a
+}
+
+var buf2 = buf1.slice(0, 3);
+console.log(buf2.toString('ascii', 0, buf2.length));
+buf1[0] = 33;
+console.log(buf2.toString('ascii', 0, buf2.length));
+
+// abc
+// !bc
+

buf.readUInt8(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads an unsigned 8 bit integer from the buffer at the specified offset. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+
+buf[0] = 0x3;
+buf[1] = 0x4;
+buf[2] = 0x23;
+buf[3] = 0x42;
+
+for (ii = 0; ii < buf.length; ii++) {
+  console.log(buf.readUInt8(ii));
+}
+
+// 0x3
+// 0x4
+// 0x23
+// 0x42
+

buf.readUInt16LE(offset, [noAssert])#

+

buf.readUInt16BE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads an unsigned 16 bit integer from the buffer at the specified offset with +specified endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+
+buf[0] = 0x3;
+buf[1] = 0x4;
+buf[2] = 0x23;
+buf[3] = 0x42;
+
+console.log(buf.readUInt16BE(0));
+console.log(buf.readUInt16LE(0));
+console.log(buf.readUInt16BE(1));
+console.log(buf.readUInt16LE(1));
+console.log(buf.readUInt16BE(2));
+console.log(buf.readUInt16LE(2));
+
+// 0x0304
+// 0x0403
+// 0x0423
+// 0x2304
+// 0x2342
+// 0x4223
+

buf.readUInt32LE(offset, [noAssert])#

+

buf.readUInt32BE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads an unsigned 32 bit integer from the buffer at the specified offset with +specified endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+
+buf[0] = 0x3;
+buf[1] = 0x4;
+buf[2] = 0x23;
+buf[3] = 0x42;
+
+console.log(buf.readUInt32BE(0));
+console.log(buf.readUInt32LE(0));
+
+// 0x03042342
+// 0x42230403
+

buf.readInt8(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads a signed 8 bit integer from the buffer at the specified offset. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Works as buffer.readUInt8, except buffer contents are treated as two's +complement signed values. + +

+

buf.readInt16LE(offset, [noAssert])#

+

buf.readInt16BE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads a signed 16 bit integer from the buffer at the specified offset with +specified endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Works as buffer.readUInt16*, except buffer contents are treated as two's +complement signed values. + +

+

buf.readInt32LE(offset, [noAssert])#

+

buf.readInt32BE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads a signed 32 bit integer from the buffer at the specified offset with +specified endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Works as buffer.readUInt32*, except buffer contents are treated as two's +complement signed values. + +

+

buf.readFloatLE(offset, [noAssert])#

+

buf.readFloatBE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads a 32 bit float from the buffer at the specified offset with specified +endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+
+buf[0] = 0x00;
+buf[1] = 0x00;
+buf[2] = 0x80;
+buf[3] = 0x3f;
+
+console.log(buf.readFloatLE(0));
+
+// 0x01
+

buf.readDoubleLE(offset, [noAssert])#

+

buf.readDoubleBE(offset, [noAssert])#

+
    +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
  • Return: Number
    • +
+

Reads a 64 bit double from the buffer at the specified offset with specified +endian format. + +

+

Set noAssert to true to skip validation of offset. This means that offset +may be beyond the end of the buffer. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(8);
+
+buf[0] = 0x55;
+buf[1] = 0x55;
+buf[2] = 0x55;
+buf[3] = 0x55;
+buf[4] = 0x55;
+buf[5] = 0x55;
+buf[6] = 0xd5;
+buf[7] = 0x3f;
+
+console.log(buf.readDoubleLE(0));
+
+// 0.3333333333333333
+

buf.writeUInt8(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset. Note, value must be a +valid unsigned 8 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+buf.writeUInt8(0x3, 0);
+buf.writeUInt8(0x4, 1);
+buf.writeUInt8(0x23, 2);
+buf.writeUInt8(0x42, 3);
+
+console.log(buf);
+
+// <Buffer 03 04 23 42>
+

buf.writeUInt16LE(value, offset, [noAssert])#

+

buf.writeUInt16BE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid unsigned 16 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+buf.writeUInt16BE(0xdead, 0);
+buf.writeUInt16BE(0xbeef, 2);
+
+console.log(buf);
+
+buf.writeUInt16LE(0xdead, 0);
+buf.writeUInt16LE(0xbeef, 2);
+
+console.log(buf);
+
+// <Buffer de ad be ef>
+// <Buffer ad de ef be>
+

buf.writeUInt32LE(value, offset, [noAssert])#

+

buf.writeUInt32BE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid unsigned 32 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+buf.writeUInt32BE(0xfeedface, 0);
+
+console.log(buf);
+
+buf.writeUInt32LE(0xfeedface, 0);
+
+console.log(buf);
+
+// <Buffer fe ed fa ce>
+// <Buffer ce fa ed fe>
+

buf.writeInt8(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset. Note, value must be a +valid signed 8 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Works as buffer.writeUInt8, except value is written out as a two's complement +signed integer into buffer. + +

+

buf.writeInt16LE(value, offset, [noAssert])#

+

buf.writeInt16BE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid signed 16 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Works as buffer.writeUInt16*, except value is written out as a two's +complement signed integer into buffer. + +

+

buf.writeInt32LE(value, offset, [noAssert])#

+

buf.writeInt32BE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid signed 32 bit integer. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Works as buffer.writeUInt32*, except value is written out as a two's +complement signed integer into buffer. + +

+

buf.writeFloatLE(value, offset, [noAssert])#

+

buf.writeFloatBE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid 32 bit float. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(4);
+buf.writeFloatBE(0xcafebabe, 0);
+
+console.log(buf);
+
+buf.writeFloatLE(0xcafebabe, 0);
+
+console.log(buf);
+
+// <Buffer 4f 4a fe bb>
+// <Buffer bb fe 4a 4f>
+

buf.writeDoubleLE(value, offset, [noAssert])#

+

buf.writeDoubleBE(value, offset, [noAssert])#

+
    +
  • value Number
    • +
  • offset Number
    • +
  • noAssert Boolean, Optional, Default: false
    • +
+

Writes value to the buffer at the specified offset with specified endian +format. Note, value must be a valid 64 bit double. + +

+

Set noAssert to true to skip validation of value and offset. This means +that value may be too large for the specific function and offset may be +beyond the end of the buffer leading to the values being silently dropped. This +should not be used unless you are certain of correctness. Defaults to false. + +

+

Example: + +

+
var buf = new Buffer(8);
+buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
+
+console.log(buf);
+
+buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
+
+console.log(buf);
+
+// <Buffer 43 eb d5 b7 dd f9 5f d7>
+// <Buffer d7 5f f9 dd b7 d5 eb 43>
+

buf.fill(value, [offset], [end])#

+
    +
  • value
    • +
  • offset Number, Optional
    • +
  • end Number, Optional
    • +
+

Fills the buffer with the specified value. If the offset (defaults to 0) +and end (defaults to buffer.length) are not given it will fill the entire +buffer. + +

+
var b = new Buffer(50);
+b.fill("h");
+

buffer.INSPECT_MAX_BYTES#

+
    +
  • Number, Default: 50
    • +
+

How many bytes will be returned when buffer.inspect() is called. This can +be overridden by user modules. + +

+

Note that this is a property on the buffer module returned by +require('buffer'), not on the Buffer global, or a buffer instance. + +

+

Class: SlowBuffer#

+

This class is primarily for internal use. JavaScript programs should +use Buffer instead of using SlowBuffer. + +

+

In order to avoid the overhead of allocating many C++ Buffer objects for +small blocks of memory in the lifetime of a server, Node allocates memory +in 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it +will be backed by a parent SlowBuffer object. If it is larger than this, +then Node will allocate a SlowBuffer slab for it directly. + +

+

Stream#

+
Stability: 2 - Unstable
+

A stream is an abstract interface implemented by various objects in Node. +For example a request to an HTTP server is a stream, as is stdout. Streams +are readable, writable, or both. All streams are instances of EventEmitter. + +

+

You can load up the Stream base class by doing require('stream'). + +

+

Readable Stream#

+ + +

A Readable Stream has the following methods, members, and events. + +

+

Event: 'data'#

+

function (data) { } + +

+

The 'data' event emits either a Buffer (by default) or a string if +setEncoding() was used. + +

+

Note that the data will be lost if there is no listener when a +Readable Stream emits a 'data' event. + +

+

Event: 'end'#

+

function () { } + +

+

Emitted when the stream has received an EOF (FIN in TCP terminology). +Indicates that no more 'data' events will happen. If the stream is also +writable, it may be possible to continue writing. + +

+

Event: 'error'#

+

function (exception) { } + +

+

Emitted if there was an error receiving data. + +

+

Event: 'close'#

+

function () { } + +

+

Emitted when the underlying file descriptor has been closed. Not all streams +will emit this. (For example, an incoming HTTP request will not emit +'close'.) + +

+

stream.readable#

+

A boolean that is true by default, but turns false after an 'error' +occurred, the stream came to an 'end', or destroy() was called. + +

+

stream.setEncoding(encoding)#

+

Makes the data event emit a string instead of a Buffer. encoding can be +'utf8', 'ascii', or 'base64'. + +

+

stream.pause()#

+

Pauses the incoming 'data' events. + +

+

stream.resume()#

+

Resumes the incoming 'data' events after a pause(). + +

+

stream.destroy()#

+

Closes the underlying file descriptor. Stream will not emit any more events. + +

+

stream.pipe(destination, [options])#

+

This is a Stream.prototype method available on all Streams. + +

+

Connects this read stream to destination WriteStream. Incoming +data on this stream gets written to destination. The destination and source +streams are kept in sync by pausing and resuming as necessary. + +

+

This function returns the destination stream. + +

+

Emulating the Unix cat command: + +

+
process.stdin.resume();
+process.stdin.pipe(process.stdout);
+

By default end() is called on the destination when the source stream emits +end, so that destination is no longer writable. Pass { end: false } as +options to keep the destination stream open. + +

+

This keeps process.stdout open so that "Goodbye" can be written at the end. + +

+
process.stdin.resume();
+
+process.stdin.pipe(process.stdout, { end: false });
+
+process.stdin.on("end", function() {
+  process.stdout.write("Goodbye\n");
+});
+

Writable Stream#

+ + +

A Writable Stream has the following methods, members, and events. + +

+

Event: 'drain'#

+

function () { } + +

+

After a write() method returned false, this event is emitted to +indicate that it is safe to write again. + +

+

Event: 'error'#

+

function (exception) { } + +

+

Emitted on error with the exception exception. + +

+

Event: 'close'#

+

function () { } + +

+

Emitted when the underlying file descriptor has been closed. + +

+

Event: 'pipe'#

+

function (src) { } + +

+

Emitted when the stream is passed to a readable stream's pipe method. + +

+

stream.writable#

+

A boolean that is true by default, but turns false after an 'error' +occurred or end() / destroy() was called. + +

+

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)#

+

Same as the above except with a raw buffer. + +

+

stream.end()#

+

Terminates the stream with EOF or FIN. +This call will allow queued write data to be sent before closing the stream. + +

+

stream.end(string, encoding)#

+

Sends string with the given encoding and terminates the stream with EOF +or FIN. This is useful to reduce the number of packets sent. + +

+

stream.end(buffer)#

+

Same as above but with a buffer. + +

+

stream.destroy()#

+

Closes the underlying file descriptor. Stream will not emit any more events. +Any queued write data will not be sent. + +

+

stream.destroySoon()#

+

After the write queue is drained, close the file descriptor. destroySoon() +can still destroy straight away, as long as there is no data left in the queue +for writes. + +

+

Crypto#

+
Stability: 3 - Stable
+

Use require('crypto') to access this module. + +

+

The crypto module requires OpenSSL to be available on the underlying platform. +It offers a way of encapsulating secure credentials to be used as part +of a secure HTTPS net or http connection. + +

+

It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods. + +

+

crypto.createCredentials(details)#

+

Creates a credentials object, with the optional details being a dictionary with keys: + +

+
    +
  • pfx : A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
    • +
  • key : a string holding the PEM encoded private key
    • +
  • cert : a string holding the PEM encoded certificate
    • +
  • passphrase : A string of passphrase for the private key or pfx
    • +
  • ca : either a string or list of strings of PEM encoded CA certificates to trust.
    • +
  • ciphers: a string describing the ciphers to use or exclude. Consult +http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details +on the format.
    • +
+

If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in +

+

http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt. + + +

+

crypto.createHash(algorithm)#

+

Creates and returns a hash object, a cryptographic hash with the given algorithm +which can be used to generate hash digests. + +

+

algorithm is dependent on the available algorithms supported by the version +of OpenSSL on the platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', etc. +On recent releases, openssl list-message-digest-algorithms will display the available digest algorithms. + +

+

Example: this program that takes the sha1 sum of a file + +

+
var filename = process.argv[2];
+var crypto = require('crypto');
+var fs = require('fs');
+
+var shasum = crypto.createHash('sha1');
+
+var s = fs.ReadStream(filename);
+s.on('data', function(d) {
+  shasum.update(d);
+});
+
+s.on('end', function() {
+  var d = shasum.digest('hex');
+  console.log(d + '  ' + filename);
+});
+

Class: Hash#

+

The class for creating hash digests of data. + +

+

Returned by crypto.createHash. + +

+

hash.update(data, [input_encoding])#

+

Updates the hash content with the given data, the encoding of which is given +in input_encoding and can be 'utf8', 'ascii' or 'binary'. +Defaults to 'binary'. +This can be called many times with new data as it is streamed. + +

+

hash.digest([encoding])#

+

Calculates the digest of all of the passed data to be hashed. +The encoding can be 'hex', 'binary' or 'base64'. +Defaults to 'binary'. + +

+

Note: hash object can not be used after digest() method been called. + + +

+

crypto.createHmac(algorithm, key)#

+

Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key. + +

+

algorithm is dependent on the available algorithms supported by OpenSSL - see createHash above. +key is the hmac key to be used. + +

+

Class: Hmac#

+

Class for creating cryptographic hmac content. + +

+

Returned by crypto.createHmac. + +

+

hmac.update(data)#

+

Update the hmac content with the given data. +This can be called many times with new data as it is streamed. + +

+

hmac.digest([encoding])#

+

Calculates the digest of all of the passed data to the hmac. +The encoding can be 'hex', 'binary' or 'base64'. +Defaults to 'binary'. + +

+

Note: hmac object can not be used after digest() method been called. + + +

+

crypto.createCipher(algorithm, password)#

+

Creates and returns a cipher object, with the given algorithm and password. + +

+

algorithm is dependent on OpenSSL, examples are 'aes192', etc. +On recent releases, openssl list-cipher-algorithms will display the +available cipher algorithms. +password is used to derive key and IV, which must be 'binary' encoded +string (See the Buffer section for more information). + +

+

crypto.createCipheriv(algorithm, key, iv)#

+

Creates and returns a cipher object, with the given algorithm, key and iv. + +

+

algorithm is the same as the createCipher(). key is a raw key used in +algorithm. iv is an Initialization vector. key and iv must be 'binary' +encoded string (See the Buffer section for more information). + +

+

Class: Cipher#

+

Class for encrypting data. + +

+

Returned by crypto.createCipher and crypto.createCipheriv. + +

+

cipher.update(data, [input_encoding], [output_encoding])#

+

Updates the cipher with data, the encoding of which is given in +input_encoding and can be 'utf8', 'ascii' or 'binary'. +Defaults to 'binary'. + +

+

The output_encoding specifies the output format of the enciphered data, +and can be 'binary', 'base64' or 'hex'. Defaults to 'binary'. + +

+

Returns the enciphered contents, and can be called many times with new data as it is streamed. + +

+

cipher.final([output_encoding])#

+

Returns any remaining enciphered contents, with output_encoding being one of: +'binary', 'base64' or 'hex'. Defaults to 'binary'. + +

+

Note: cipher object can not be used after final() method been called. + + +

+

crypto.createDecipher(algorithm, password)#

+

Creates and returns a decipher object, with the given algorithm and key. +This is the mirror of the createCipher() above. + +

+

crypto.createDecipheriv(algorithm, key, iv)#

+

Creates and returns a decipher object, with the given algorithm, key and iv. +This is the mirror of the createCipheriv() above. + +

+

Class: Decipher#

+

Class for decrypting data. + +

+

Returned by crypto.createDecipher and crypto.createDecipheriv. + +

+

decipher.update(data, [input_encoding], [output_encoding])#

+

Updates the decipher with data, which is encoded in 'binary', 'base64' +or 'hex'. Defaults to 'binary'. + +

+

The output_decoding specifies in what format to return the deciphered +plaintext: 'binary', 'ascii' or 'utf8'. Defaults to 'binary'. + +

+

decipher.final([output_encoding])#

+

Returns any remaining plaintext which is deciphered, +with output_encoding being one of: 'binary', 'ascii' or 'utf8'. +Defaults to 'binary'. + +

+

Note: decipher object can not be used after final() method been called. + + +

+

crypto.createSign(algorithm)#

+

Creates and returns a signing object, with the given algorithm. +On recent OpenSSL releases, openssl list-public-key-algorithms will display +the available signing algorithms. Examples are 'RSA-SHA256'. + +

+

Class: Signer#

+

Class for generating signatures. + +

+

Returned by crypto.createSign. + +

+

signer.update(data)#

+

Updates the signer object with data. +This can be called many times with new data as it is streamed. + +

+

signer.sign(private_key, [output_format])#

+

Calculates the signature on all the updated data passed through the signer. +private_key is a string containing the PEM encoded private key for signing. + +

+

Returns the signature in output_format which can be 'binary', 'hex' or +'base64'. Defaults to 'binary'. + +

+

Note: signer object can not be used after sign() method been called. + +

+

crypto.createVerify(algorithm)#

+

Creates and returns a verification object, with the given algorithm. +This is the mirror of the signing object above. + +

+

Class: Verify#

+

Class for verifying signatures. + +

+

Returned by crypto.createVerify. + +

+

verifier.update(data)#

+

Updates the verifier object with data. +This can be called many times with new data as it is streamed. + +

+

verifier.verify(object, signature, [signature_format])#

+

Verifies the signed data by using the object and signature. object is a +string containing a PEM encoded object, which can be one of RSA public key, +DSA public key, or X.509 certificate. signature is the previously calculated +signature for the data, in the signature_format which can be 'binary', +'hex' or 'base64'. Defaults to 'binary'. + +

+

Returns true or false depending on the validity of the signature for the data and public key. + +

+

Note: verifier object can not be used after verify() method been called. + +

+

crypto.createDiffieHellman(prime_length)#

+

Creates a Diffie-Hellman key exchange object and generates a prime of the +given bit length. The generator used is 2. + +

+

crypto.createDiffieHellman(prime, [encoding])#

+

Creates a Diffie-Hellman key exchange object using the supplied prime. The +generator used is 2. Encoding can be 'binary', 'hex', or 'base64'. +Defaults to 'binary'. + +

+

Class: DiffieHellman#

+

The class for creating Diffie-Hellman key exchanges. + +

+

Returned by crypto.createDiffieHellman. + +

+

diffieHellman.generateKeys([encoding])#

+

Generates private and public Diffie-Hellman key values, and returns the +public key in the specified encoding. This key should be transferred to the +other party. Encoding can be 'binary', 'hex', or 'base64'. +Defaults to 'binary'. + +

+

diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])#

+

Computes the shared secret using other_public_key as the other party's +public key and returns the computed shared secret. Supplied key is +interpreted using specified input_encoding, and secret is encoded using +specified output_encoding. Encodings can be 'binary', 'hex', or +'base64'. The input encoding defaults to 'binary'. +If no output encoding is given, the input encoding is used as output encoding. + +

+

diffieHellman.getPrime([encoding])#

+

Returns the Diffie-Hellman prime in the specified encoding, which can be +'binary', 'hex', or 'base64'. Defaults to 'binary'. + +

+

diffieHellman.getGenerator([encoding])#

+

Returns the Diffie-Hellman prime in the specified encoding, which can be +'binary', 'hex', or 'base64'. Defaults to 'binary'. + +

+

diffieHellman.getPublicKey([encoding])#

+

Returns the Diffie-Hellman public key in the specified encoding, which can +be 'binary', 'hex', or 'base64'. Defaults to 'binary'. + +

+

diffieHellman.getPrivateKey([encoding])#

+

Returns the Diffie-Hellman private key in the specified encoding, which can +be 'binary', 'hex', or 'base64'. Defaults to 'binary'. + +

+

diffieHellman.setPublicKey(public_key, [encoding])#

+

Sets the Diffie-Hellman public key. Key encoding can be 'binary', 'hex', +or 'base64'. Defaults to 'binary'. + +

+

diffieHellman.setPrivateKey(public_key, [encoding])#

+

Sets the Diffie-Hellman private key. Key encoding can be 'binary', 'hex', +or 'base64'. Defaults to 'binary'. + +

+

crypto.pbkdf2(password, salt, iterations, keylen, callback)#

+

Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive +a key of given length from the given password, salt and iterations. +The callback gets two arguments (err, derivedKey). + +

+

crypto.randomBytes(size, [callback])#

+

Generates cryptographically strong pseudo-random data. Usage: + +

+
// async
+crypto.randomBytes(256, function(ex, buf) {
+  if (ex) throw ex;
+  console.log('Have %d bytes of random data: %s', buf.length, buf);
+});
+
+// sync
+try {
+  var buf = crypto.randomBytes(256);
+  console.log('Have %d bytes of random data: %s', buf.length, buf);
+} catch (ex) {
+  // handle error
+}
+

TLS (SSL)#

+
Stability: 3 - Stable
+

Use require('tls') to access this module. + +

+

The tls module uses OpenSSL to provide Transport Layer Security and/or +Secure Socket Layer: encrypted stream communication. + +

+

TLS/SSL is a public/private key infrastructure. Each client and each +server must have a private key. A private key is created like this + +

+
openssl genrsa -out ryans-key.pem 1024
+

All severs and some clients need to have a certificate. Certificates are public +keys signed by a Certificate Authority or self-signed. The first step to +getting a certificate is to create a "Certificate Signing Request" (CSR) +file. This is done with: + +

+
openssl req -new -key ryans-key.pem -out ryans-csr.pem
+

To create a self-signed certificate with the CSR, do this: + +

+
openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem
+

Alternatively you can send the CSR to a Certificate Authority for signing. + +

+

(TODO: docs on creating a CA, for now interested users should just look at +test/fixtures/keys/Makefile in the Node source code) + +

+

To create .pfx or .p12, do this: + +

+
openssl pkcs12 -export -in agent5-cert.pem -inkey agent5-key.pem \
+    -certfile ca-cert.pem -out agent5.pfx
+
    +
  • in: certificate
    • +
  • inkey: private key
    • +
  • certfile: all CA certs concatenated in one file like +cat ca1-cert.pem ca2-cert.pem > ca-cert.pem
    • +
+

Client-initiated renegotiation attack mitigation#

+ + +

The TLS protocol lets the client renegotiate certain aspects of the TLS session. +Unfortunately, session renegotiation requires a disproportional amount of +server-side resources, which makes it a potential vector for denial-of-service +attacks. + +

+

To mitigate this, renegotiations are limited to three times every 10 minutes. An +error is emitted on the CleartextStream instance when +the threshold is exceeded. The limits are configurable: + +

+
    +

  • tls.CLIENT_RENEG_LIMIT: renegotiation limit, default is 3.

    +
    • +

  • tls.CLIENT_RENEG_WINDOW: renegotiation window in seconds, default is

    +
                           10 minutes.
    +
    • +
+

Don't change the defaults unless you know what you are doing. + +

+

To test your server, connect to it with openssl s_client -connect address:port +and tap R<CR> (that's the letter R followed by a carriage return) a few +times. + + +

+

NPN and SNI#

+ + +

NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS +handshake extensions allowing you: + +

+
    +
  • NPN - to use one TLS server for multiple protocols (HTTP, SPDY)
    • +
  • SNI - to use one TLS server for multiple hostnames with different SSL +certificates.
    • +
+

tls.createServer(options, [secureConnectionListener])#

+

Creates a new tls.Server. +The connectionListener argument is automatically set as a listener for the +secureConnection event. +The options object has these possibilities: + +

+
    +

  • pfx: A string or Buffer containing the private key, certificate and +CA certs of the server in PFX or PKCS12 format. (Mutually exclusive with +the key, cert and ca options.)

    +
    • +

  • key: A string or Buffer containing the private key of the server in +PEM format. (Required)

    +
    • +

  • passphrase: A string of passphrase for the private key or pfx.

    +
    • +

  • cert: A string or Buffer containing the certificate key of the server in +PEM format. (Required)

    +
    • +

  • ca: An array of strings or Buffers of trusted certificates. If this is +omitted several well known "root" CAs will be used, like VeriSign. +These are used to authorize connections.

    +
    • +

  • ciphers: A string describing the ciphers to use or exclude. Consult +http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for +details on the format.

    +
    • +

  • requestCert: If true the server will request a certificate from +clients that connect and attempt to verify that certificate. Default: +false.

    +
    • +

  • rejectUnauthorized: If true the server will reject any connection +which is not authorized with the list of supplied CAs. This option only +has an effect if requestCert is true. Default: false.

    +
    • +

  • NPNProtocols: An array or Buffer of possible NPN protocols. (Protocols +should be ordered by their priority).

    +
    • +

  • SNICallback: A function that will be called if client supports SNI TLS +extension. Only one argument will be passed to it: servername. And +SNICallback should return SecureContext instance. +(You can use crypto.createCredentials(...).context to get proper +SecureContext). If SNICallback wasn't provided - default callback with +high-level API will be used (see below).

    +
    • +

  • sessionIdContext: A string containing a opaque identifier for session +resumption. If requestCert is true, the default is MD5 hash value +generated from command-line. Otherwise, the default is not provided.

    +
    • +
+

Here is a simple example echo server: + +

+
var tls = require('tls');
+var fs = require('fs');
+
+var options = {
+  key: fs.readFileSync('server-key.pem'),
+  cert: fs.readFileSync('server-cert.pem'),
+
+  // This is necessary only if using the client certificate authentication.
+  requestCert: true,
+
+  // This is necessary only if the client uses the self-signed certificate.
+  ca: [ fs.readFileSync('client-cert.pem') ]
+};
+
+var server = tls.createServer(options, function(cleartextStream) {
+  console.log('server connected',
+              cleartextStream.authorized ? 'authorized' : 'unauthorized');
+  cleartextStream.write("welcome!\n");
+  cleartextStream.setEncoding('utf8');
+  cleartextStream.pipe(cleartextStream);
+});
+server.listen(8000, function() {
+  console.log('server bound');
+});
+

Or + +

+
var tls = require('tls');
+var fs = require('fs');
+
+var options = {
+  pfx: fs.readFileSync('server.pfx'),
+
+  // This is necessary only if using the client certificate authentication.
+  requestCert: true,
+
+};
+
+var server = tls.createServer(options, function(cleartextStream) {
+  console.log('server connected',
+              cleartextStream.authorized ? 'authorized' : 'unauthorized');
+  cleartextStream.write("welcome!\n");
+  cleartextStream.setEncoding('utf8');
+  cleartextStream.pipe(cleartextStream);
+});
+server.listen(8000, function() {
+  console.log('server bound');
+});
+

You can test this server by connecting to it with openssl s_client: + + +

+
openssl s_client -connect 127.0.0.1:8000
+

tls.connect(port, [host], [options], [secureConnectListener])#

+

Creates a new client connection to the given port and host. (If host +defaults to localhost.) options should be an object which specifies + +

+
    +

  • pfx: A string or Buffer containing the private key, certificate and +CA certs of the server in PFX or PKCS12 format.

    +
    • +

  • key: A string or Buffer containing the private key of the client in +PEM format.

    +
    • +

  • passphrase: A string of passphrase for the private key or pfx.

    +
    • +

  • cert: A string or Buffer containing the certificate key of the client in +PEM format.

    +
    • +

  • ca: An array of strings or Buffers of trusted certificates. If this is +omitted several well known "root" CAs will be used, like VeriSign. +These are used to authorize connections.

    +
    • +

  • NPNProtocols: An array of string or Buffer containing supported NPN +protocols. Buffer should have following format: 0x05hello0x05world, +where first byte is next protocol name's length. (Passing array should +usually be much simpler: ['hello', 'world'].)

    +
    • +

  • servername: Servername for SNI (Server Name Indication) TLS extension.

    +
    • +

  • socket: Establish secure connection on a given socket rather than +creating a new socket. If this option is specified, host and port +are ignored. This is intended FOR INTERNAL USE ONLY. As with all +undocumented APIs in Node, they should not be used.

    +
    • +
+

The secureConnectListener parameter will be added as a listener for the +'secureConnect' event. + +

+

tls.connect() returns a CleartextStream object. + +

+

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

+
var tls = require('tls');
+var fs = require('fs');
+
+var options = {
+  // These are necessary only if using the client certificate authentication
+  key: fs.readFileSync('client-key.pem'),
+  cert: fs.readFileSync('client-cert.pem'),
+
+  // This is necessary only if the server uses the self-signed certificate
+  ca: [ fs.readFileSync('server-cert.pem') ]
+};
+
+var cleartextStream = tls.connect(8000, options, function() {
+  console.log('client connected',
+              cleartextStream.authorized ? 'authorized' : 'unauthorized');
+  process.stdin.pipe(cleartextStream);
+  process.stdin.resume();
+});
+cleartextStream.setEncoding('utf8');
+cleartextStream.on('data', function(data) {
+  console.log(data);
+});
+cleartextStream.on('end', function() {
+  server.close();
+});
+

Or + +

+
var tls = require('tls');
+var fs = require('fs');
+
+var options = {
+  pfx: fs.readFileSync('client.pfx')
+};
+
+var cleartextStream = tls.connect(8000, options, function() {
+  console.log('client connected',
+              cleartextStream.authorized ? 'authorized' : 'unauthorized');
+  process.stdin.pipe(cleartextStream);
+  process.stdin.resume();
+});
+cleartextStream.setEncoding('utf8');
+cleartextStream.on('data', function(data) {
+  console.log(data);
+});
+cleartextStream.on('end', function() {
+  server.close();
+});
+

tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])#

+

Creates a new secure pair object with two streams, one of which reads/writes +encrypted data, and one reads/writes cleartext data. +Generally the encrypted one is piped to/from an incoming encrypted data stream, +and the cleartext one is used as a replacement for the initial encrypted stream. + +

+
    +

  • credentials: A credentials object from crypto.createCredentials( ... )

    +
    • +

  • isServer: A boolean indicating whether this tls connection should be +opened as a server or a client.

    +
    • +

  • requestCert: A boolean indicating whether a server should request a +certificate from a connecting client. Only applies to server connections.

    +
    • +

  • rejectUnauthorized: A boolean indicating whether a server should +automatically reject clients with invalid certificates. Only applies to +servers with requestCert enabled.

    +
    • +
+

tls.createSecurePair() returns a SecurePair object with +cleartext and encrypted stream properties. + +

+

Class: SecurePair#

+

Returned by tls.createSecurePair. + +

+

Event: 'secure'#

+

The event is emitted from the SecurePair once the pair has successfully +established a secure connection. + +

+

Similarly to the checking for the server 'secureConnection' event, +pair.cleartext.authorized should be checked to confirm whether the certificate +used properly authorized. + +

+

Class: tls.Server#

+

This class is a subclass of net.Server and has the same methods on it. +Instead of accepting just raw TCP connections, this accepts encrypted +connections using TLS or SSL. + +

+

Event: 'secureConnection'#

+

function (cleartextStream) {} + +

+

This event is emitted after a new connection has been successfully +handshaked. The argument is a instance of +CleartextStream. It has all the common stream methods +and events. + +

+

cleartextStream.authorized is a boolean value which indicates if the +client has verified by one of the supplied certificate authorities for the +server. If cleartextStream.authorized is false, then +cleartextStream.authorizationError is set to describe how authorization +failed. Implied but worth mentioning: depending on the settings of the TLS +server, you unauthorized connections may be accepted. +cleartextStream.npnProtocol is a string containing selected NPN protocol. +cleartextStream.servername is a string containing servername requested with +SNI. + + +

+

Event: 'clientError'#

+

function (exception) { } + +

+

When a client connection emits an 'error' event before secure connection is +established - it will be forwarded here. + + +

+

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

+

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). + +

+

This function is asynchronous. The last parameter callback will be called +when the server has been bound. + +

+

See net.Server for more information. + + +

+

server.close()#

+

Stops the server from accepting new connections. This function is +asynchronous, the server is finally closed when the server emits a 'close' +event. + +

+

server.address()#

+

Returns the bound address and port of the server as reported by the operating +system. +See net.Server.address() for more information. + +

+

server.addContext(hostname, credentials)#

+

Add secure context that will be used if client request's SNI hostname is +matching passed hostname (wildcards can be used). credentials can contain +key, cert and ca. + +

+

server.maxConnections#

+

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

+

server.connections#

+

The number of concurrent connections on the server. + + +

+

Class: tls.CleartextStream#

+

This is a stream on top of the Encrypted stream that makes it possible to +read/write an encrypted data as a cleartext data. + +

+

This instance implements a duplex Stream interfaces. +It has all the common stream methods and events. + +

+

A ClearTextStream is the clear member of a SecurePair object. + +

+

Event: 'secureConnect'#

+

This event is emitted after a new connection has been successfully handshaked. +The listener will be called no matter if the server's certificate was +authorized or not. It is up to the user to test cleartextStream.authorized +to see if the server certificate was signed by one of the specified CAs. +If cleartextStream.authorized === false then the error can be found in +cleartextStream.authorizationError. Also if NPN was used - you can check +cleartextStream.npnProtocol for negotiated protocol. + +

+

cleartextStream.authorized#

+

A boolean that is true if the peer certificate was signed by one of the +specified CAs, otherwise false + +

+

cleartextStream.authorizationError#

+

The reason why the peer's certificate has not been verified. This property +becomes available only when cleartextStream.authorized === false. + +

+

cleartextStream.getPeerCertificate()#

+

Returns an object representing the peer's certificate. The returned object has +some properties corresponding to the field of the certificate. + +

+

Example: + +

+
{ subject: 
+   { C: 'UK',
+     ST: 'Acknack Ltd',
+     L: 'Rhys Jones',
+     O: 'node.js',
+     OU: 'Test TLS Certificate',
+     CN: 'localhost' },
+  issuer: 
+   { C: 'UK',
+     ST: 'Acknack Ltd',
+     L: 'Rhys Jones',
+     O: 'node.js',
+     OU: 'Test TLS Certificate',
+     CN: 'localhost' },
+  valid_from: 'Nov 11 09:52:22 2009 GMT',
+  valid_to: 'Nov  6 09:52:22 2029 GMT',
+  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF' }
+

If the peer does not provide a certificate, it returns null or an empty +object. + +

+

cleartextStream.address()#

+

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

+

cleartextStream.remoteAddress#

+

The string representation of the remote IP address. For example, +'74.125.127.100' or '2001:4860:a005::68'. + +

+

cleartextStream.remotePort#

+

The numeric representation of the remote port. For example, 443. + + +

+

File System#

+
Stability: 3 - Stable
+ + +

File I/O is provided by simple wrappers around standard POSIX functions. To +use this module do require('fs'). All the methods have asynchronous and +synchronous forms. + +

+

The asynchronous form always take a completion callback as its last argument. +The arguments passed to the completion callback depend on the method, but the +first argument is always reserved for an exception. If the operation was +completed successfully, then the first argument will be null or undefined. + +

+

When using the synchronous form any exceptions are immediately thrown. +You can use try/catch to handle exceptions or allow them to bubble up. + +

+

Here is an example of the asynchronous version: + +

+
var fs = require('fs');
+
+fs.unlink('/tmp/hello', function (err) {
+  if (err) throw err;
+  console.log('successfully deleted /tmp/hello');
+});
+

Here is the synchronous version: + +

+
var fs = require('fs');
+
+fs.unlinkSync('/tmp/hello')
+console.log('successfully deleted /tmp/hello');
+

With the asynchronous methods there is no guaranteed ordering. So the +following is prone to error: + +

+
fs.rename('/tmp/hello', '/tmp/world', function (err) {
+  if (err) throw err;
+  console.log('renamed complete');
+});
+fs.stat('/tmp/world', function (err, stats) {
+  if (err) throw err;
+  console.log('stats: ' + JSON.stringify(stats));
+});
+

It could be that fs.stat is executed before fs.rename. +The correct way to do this is to chain the callbacks. + +

+
fs.rename('/tmp/hello', '/tmp/world', function (err) {
+  if (err) throw err;
+  fs.stat('/tmp/world', function (err, stats) {
+    if (err) throw err;
+    console.log('stats: ' + JSON.stringify(stats));
+  });
+});
+

In busy processes, the programmer is strongly encouraged to use the +asynchronous versions of these calls. The synchronous versions will block +the entire process until they complete--halting all connections. + +

+

Relative path to filename can be used, remember however that this path will be relative +to process.cwd(). + +

+

fs.rename(path1, path2, [callback])#

+

Asynchronous rename(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.renameSync(path1, path2)#

+

Synchronous rename(2). + +

+

fs.truncate(fd, len, [callback])#

+

Asynchronous ftruncate(2). No arguments other than a possible exception are +given to the completion callback. + +

+

fs.truncateSync(fd, len)#

+

Synchronous ftruncate(2). + +

+

fs.chown(path, uid, gid, [callback])#

+

Asynchronous chown(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.chownSync(path, uid, gid)#

+

Synchronous chown(2). + +

+

fs.fchown(fd, uid, gid, [callback])#

+

Asynchronous fchown(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.fchownSync(fd, uid, gid)#

+

Synchronous fchown(2). + +

+

fs.lchown(path, uid, gid, [callback])#

+

Asynchronous lchown(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.lchownSync(path, uid, gid)#

+

Synchronous lchown(2). + +

+

fs.chmod(path, mode, [callback])#

+

Asynchronous chmod(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.chmodSync(path, mode)#

+

Synchronous chmod(2). + +

+

fs.fchmod(fd, mode, [callback])#

+

Asynchronous fchmod(2). No arguments other than a possible exception +are given to the completion callback. + +

+

fs.fchmodSync(fd, mode)#

+

Synchronous fchmod(2). + +

+

fs.lchmod(path, mode, [callback])#

+

Asynchronous lchmod(2). No arguments other than a possible exception +are given to the completion callback. + +

+

fs.lchmodSync(path, mode)#

+

Synchronous lchmod(2). + +

+

fs.stat(path, [callback])#

+

Asynchronous stat(2). The callback gets two arguments (err, stats) where +stats is a fs.Stats object. See the fs.Stats +section below for more information. + +

+

fs.lstat(path, [callback])#

+

Asynchronous lstat(2). The callback gets two arguments (err, stats) where +stats is a fs.Stats object. lstat() is identical to stat(), except that if +path is a symbolic link, then the link itself is stat-ed, not the file that it +refers to. + +

+

fs.fstat(fd, [callback])#

+

Asynchronous fstat(2). The callback gets two arguments (err, stats) where +stats is a fs.Stats object. fstat() is identical to stat(), except that +the file to be stat-ed is specified by the file descriptor fd. + +

+

fs.statSync(path)#

+

Synchronous stat(2). Returns an instance of fs.Stats. + +

+

fs.lstatSync(path)#

+

Synchronous lstat(2). Returns an instance of fs.Stats. + +

+

fs.fstatSync(fd)#

+

Synchronous fstat(2). Returns an instance of fs.Stats. + +

+

fs.link(srcpath, dstpath, [callback])#

+

Asynchronous link(2). No arguments other than a possible exception are given to +the completion callback. + +

+

fs.linkSync(srcpath, dstpath)#

+

Synchronous link(2). + +

+

fs.symlink(linkdata, path, [type], [callback])#

+

Asynchronous symlink(2). No arguments other than a possible exception are given +to the completion callback. +type argument can be either 'dir' or 'file' (default is 'file'). It is only +used on Windows (ignored on other platforms). + +

+

fs.symlinkSync(linkdata, path, [type])#

+

Synchronous symlink(2). + +

+

fs.readlink(path, [callback])#

+

Asynchronous readlink(2). The callback gets two arguments (err, +linkString). + +

+

fs.readlinkSync(path)#

+

Synchronous readlink(2). Returns the symbolic link's string value. + +

+

fs.realpath(path, [callback])#

+

Asynchronous realpath(2). The callback gets two arguments (err, +resolvedPath). May use process.cwd to resolve relative paths. + +

+

fs.realpathSync(path)#

+

Synchronous realpath(2). Returns the resolved path. + +

+

fs.unlink(path, [callback])#

+

Asynchronous unlink(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.unlinkSync(path)#

+

Synchronous unlink(2). + +

+

fs.rmdir(path, [callback])#

+

Asynchronous rmdir(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.rmdirSync(path)#

+

Synchronous rmdir(2). + +

+

fs.mkdir(path, [mode], [callback])#

+

Asynchronous mkdir(2). No arguments other than a possible exception are given +to the completion callback. mode defaults to 0777. + +

+

fs.mkdirSync(path, [mode])#

+

Synchronous mkdir(2). + +

+

fs.readdir(path, [callback])#

+

Asynchronous readdir(3). Reads the contents of a directory. +The callback gets two arguments (err, files) where files is an array of +the names of the files in the directory excluding '.' and '..'. + +

+

fs.readdirSync(path)#

+

Synchronous readdir(3). Returns an array of filenames excluding '.' and +'..'. + +

+

fs.close(fd, [callback])#

+

Asynchronous close(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.closeSync(fd)#

+

Synchronous close(2). + +

+

fs.open(path, flags, [mode], [callback])#

+

Asynchronous file open. See open(2). flags can be: + +

+
    +

  • 'r' - Open file for reading. +An exception occurs if the file does not exist.

    +
    • +

  • 'r+' - Open file for reading and writing. +An exception occurs if the file does not exist.

    +
    • +

  • 'w' - Open file for writing. +The file is created (if it does not exist) or truncated (if it exists).

    +
    • +

  • 'w+' - Open file for reading and writing. +The file is created (if it does not exist) or truncated (if it exists).

    +
    • +

  • 'a' - Open file for appending. +The file is created if it does not exist.

    +
    • +

  • 'a+' - Open file for reading and appending. +The file is created if it does not exist.

    +
    • +
+

mode defaults to 0666. The callback gets two arguments (err, fd). + +

+

fs.openSync(path, flags, [mode])#

+

Synchronous open(2). + +

+

fs.utimes(path, atime, mtime, [callback])#

+

fs.utimesSync(path, atime, mtime)#

+

Change file timestamps of the file referenced by the supplied path. + +

+

fs.futimes(fd, atime, mtime, [callback])#

+

fs.futimesSync(fd, atime, mtime)#

+

Change the file timestamps of a file referenced by the supplied file +descriptor. + +

+

fs.fsync(fd, [callback])#

+

Asynchronous fsync(2). No arguments other than a possible exception are given +to the completion callback. + +

+

fs.fsyncSync(fd)#

+

Synchronous fsync(2). + +

+

fs.write(fd, buffer, offset, length, position, [callback])#

+

Write buffer to the file specified by fd. + +

+

offset and length determine the part of the buffer to be written. + +

+

position refers to the offset from the beginning of the file where this data +should be written. If position is null, the data will be written at the +current position. +See pwrite(2). + +

+

The callback will be given three arguments (err, written, buffer) where written +specifies how many bytes were written from buffer. + +

+

Note that it is unsafe to use fs.write multiple times on the same file +without waiting for the callback. For this scenario, +fs.createWriteStream is strongly recommended. + +

+

fs.writeSync(fd, buffer, offset, length, position)#

+

Synchronous version of buffer-based fs.write(). Returns the number of bytes +written. + +

+

fs.writeSync(fd, str, position, [encoding])#

+

Synchronous version of string-based fs.write(). encoding defaults to +'utf8'. Returns the number of bytes written. + +

+

fs.read(fd, buffer, offset, length, position, [callback])#

+

Read data from the file specified by fd. + +

+

buffer is the buffer that the data will be written to. + +

+

offset is offset within the buffer where writing will start. + +

+

length is an integer specifying the number of bytes to read. + +

+

position is an integer specifying where to begin reading from in the file. +If position is null, data will be read from the current file position. + +

+

The callback is given the three arguments, (err, bytesRead, buffer). + +

+

fs.readSync(fd, buffer, offset, length, position)#

+

Synchronous version of buffer-based fs.read. Returns the number of +bytesRead. + +

+

fs.readSync(fd, length, position, encoding)#

+

Synchronous version of string-based fs.read. Returns the number of +bytesRead. + +

+

fs.readFile(filename, [encoding], [callback])#

+

Asynchronously reads the entire contents of a file. Example: + +

+
fs.readFile('/etc/passwd', function (err, data) {
+  if (err) throw err;
+  console.log(data);
+});
+

The callback is passed two arguments (err, data), where data is the +contents of the file. + +

+

If no encoding is specified, then the raw buffer is returned. + + +

+

fs.readFileSync(filename, [encoding])#

+

Synchronous version of fs.readFile. Returns the contents of the filename. + +

+

If encoding is specified then this function returns a string. Otherwise it +returns a buffer. + + +

+

fs.writeFile(filename, data, [encoding], [callback])#

+

Asynchronously writes data to a file, replacing the file if it already exists. +data can be a string or a buffer. The encoding argument is ignored if +data is a buffer. It defaults to 'utf8'. + +

+

Example: + +

+
fs.writeFile('message.txt', 'Hello Node', function (err) {
+  if (err) throw err;
+  console.log('It\'s saved!');
+});
+

fs.writeFileSync(filename, data, [encoding])#

+

The synchronous version of fs.writeFile. + +

+

fs.watchFile(filename, [options], listener)#

+
Stability: 2 - Unstable.  Use fs.watch instead, if available.
+

Watch for changes on filename. The callback listener will be called each +time the file is accessed. + +

+

The second argument is optional. The options if provided should be an object +containing two members a boolean, persistent, and interval. persistent +indicates whether the process should continue to run as long as files are +being watched. interval indicates how often the target should be polled, +in milliseconds. (On Linux systems with inotify, interval is ignored.) The +default is { persistent: true, interval: 0 }. + +

+

The listener gets two arguments the current stat object and the previous +stat object: + +

+
fs.watchFile('message.text', function (curr, prev) {
+  console.log('the current mtime is: ' + curr.mtime);
+  console.log('the previous mtime was: ' + prev.mtime);
+});
+

These stat objects are instances of fs.Stat. + +

+

If you want to be notified when the file was modified, not just accessed +you need to compare curr.mtime and prev.mtime. + + +

+

fs.unwatchFile(filename)#

+
Stability: 2 - Unstable.  Use fs.watch instead, if available.
+

Stop watching for changes on filename. + +

+

fs.watch(filename, [options], listener)#

+
Stability: 2 - Unstable.  Not available on all platforms.
+

Watch for changes on filename, where filename is either a file or a +directory. The returned object is a fs.FSWatcher. + +

+

The second argument is optional. The options if provided should be an object +containing a boolean member persistent, which indicates whether the process +should continue to run as long as files are being watched. The default is +{ persistent: true }. + +

+

The listener callback gets two arguments (event, filename). event is either +'rename' or 'change', and filename is the name of the file which triggered +the event. + +

+

Caveats#

+ + +

The fs.watch API is not 100% consistent across platforms, and is +unavailable in some situations. + +

+

Availability#

+ + +

This feature depends on the underlying operating system providing a way +to be notified of filesystem changes. + +

+
    +
  • On Linux systems, this uses inotify.
    • +
  • On BSD systems (including OS X), this uses kqueue.
    • +
  • On SunOS systems (including Solaris and SmartOS), this uses event ports.
    • +
  • On Windows systems, this feature depends on ReadDirectoryChangesW.
    • +
+

If the underlying functionality is not available for some reason, then +fs.watch will not be able to function. You can still use +fs.watchFile, which uses stat polling, but it is slower and less +reliable. + +

+

Filename Argument#

+ + +

Providing filename argument in the callback is not supported +on every platform (currently it's only supported on Linux and Windows). Even +on supported platforms filename is not always guaranteed to be provided. +Therefore, don't assume that filename argument is always provided in the +callback, and have some fallback logic if it is null. + +

+
fs.watch('somedir', function (event, filename) {
+  console.log('event is: ' + event);
+  if (filename) {
+    console.log('filename provided: ' + filename);
+  } else {
+    console.log('filename not provided');
+  }
+});
+

Class: fs.Stats#

+

Objects returned from fs.stat(), fs.lstat() and fs.fstat() and their +synchronous counterparts are of this type. + +

+
    +
  • stats.isFile()
    • +
  • stats.isDirectory()
    • +
  • stats.isBlockDevice()
    • +
  • stats.isCharacterDevice()
    • +
  • stats.isSymbolicLink() (only valid with fs.lstat())
    • +
  • stats.isFIFO()
    • +
  • stats.isSocket()
    • +
+

For a regular file util.inspect(stats) would return a string very +similar to this: + +

+
{ dev: 2114,
+  ino: 48064969,
+  mode: 33188,
+  nlink: 1,
+  uid: 85,
+  gid: 100,
+  rdev: 0,
+  size: 527,
+  blksize: 4096,
+  blocks: 8,
+  atime: Mon, 10 Oct 2011 23:24:11 GMT,
+  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
+  ctime: Mon, 10 Oct 2011 23:24:11 GMT }
+

Please note that atime, mtime and ctime are instances +of Date object and to compare the values of +these objects you should use appropriate methods. For most +general uses getTime() will return +the number of milliseconds elapsed since 1 January 1970 +00:00:00 UTC and this integer should be sufficient for +any comparison, however there additional methods which can +be used for displaying fuzzy information. More details can +be found in the MDN JavaScript Reference page. + +

+

fs.createReadStream(path, [options])#

+

Returns a new ReadStream object (See Readable Stream). + +

+

options is an object with the following defaults: + +

+
{ flags: 'r',
+  encoding: null,
+  fd: null,
+  mode: 0666,
+  bufferSize: 64 * 1024
+}
+

options can include start and end values to read a range of bytes from +the file instead of the entire file. Both start and end are inclusive and +start at 0. + +

+

An example to read the last 10 bytes of a file which is 100 bytes long: + +

+
fs.createReadStream('sample.txt', {start: 90, end: 99});
+

Class: fs.ReadStream#

+

ReadStream is a Readable Stream. + +

+

Event: 'open'#

+
    +
  • fd Integer file descriptor used by the ReadStream.
    • +
+

Emitted when the ReadStream's file is opened. + + +

+

fs.createWriteStream(path, [options])#

+

Returns a new WriteStream object (See Writable Stream). + +

+

options is an object with the following defaults: + +

+
{ flags: 'w',
+  encoding: null,
+  mode: 0666 }
+

options may also include a start option to allow writing data at +some position past the beginning of the file. Modifying a file rather +than replacing it may require a flags mode of r+ rather than the +default mode w. + +

+

fs.WriteStream#

+

WriteStream is a Writable Stream. + +

+

Event: 'open'#

+
    +
  • fd Integer file descriptor used by the ReadStream.
    • +
+

Emitted when the WriteStream's file is opened. + +

+

file.bytesWritten#

+

The number of bytes written so far. Does not include data that is still queued +for writing. + +

+

Class: fs.FSWatcher#

+

Objects returned from fs.watch() are of this type. + +

+

watcher.close()#

+

Stop watching for changes on the given fs.FSWatcher. + +

+

Event: 'change'#

+
    +
  • event String The type of fs change
    • +
  • filename String The filename that changed (if relevant/available)
    • +
+

Emitted when something changes in a watched directory or file. +See more details in fs.watch. + +

+

Event: 'error'#

+
    +
  • error Error object
    • +
+

Emitted when an error occurs. + +

+

Path#

+
Stability: 3 - Stable
+

This module contains utilities for handling and transforming file +paths. Almost all these methods perform only string transformations. +The file system is not consulted to check whether paths are valid. + +

+

path.exists and path.existsSync are the exceptions, and should +logically be found in the fs module as they do access the file system. + +

+

Use require('path') to use this module. The following methods are provided: + +

+

path.normalize(p)#

+

Normalize a string path, taking care of '..' and '.' parts. + +

+

When multiple slashes are found, they're replaced by a single one; +when the path contains a trailing slash, it is preserved. +On windows backslashes are used. + +

+

Example: + +

+
path.normalize('/foo/bar//baz/asdf/quux/..')
+// returns
+'/foo/bar/baz/asdf'
+

path.join([path1], [path2], [...])#

+

Join all arguments together and normalize the resulting path. +Non-string arguments are ignored. + +

+

Example: + +

+
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
+// returns
+'/foo/bar/baz/asdf'
+
+path.join('foo', {}, 'bar')
+// returns
+'foo/bar'
+

path.resolve([from ...], to)#

+

Resolves to to an absolute path. + +

+

If to isn't already absolute from arguments are prepended in right to left +order, until an absolute path is found. If after using all from paths still +no absolute path is found, the current working directory is used as well. The +resulting path is normalized, and trailing slashes are removed unless the path +gets resolved to the root directory. Non-string arguments are ignored. + +

+

Another way to think of it is as a sequence of cd commands in a shell. + +

+
path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
+

Is similar to: + +

+
cd foo/bar
+cd /tmp/file/
+cd ..
+cd a/../subfile
+pwd
+

The difference is that the different paths don't need to exist and may also be +files. + +

+

Examples: + +

+
path.resolve('/foo/bar', './baz')
+// returns
+'/foo/bar/baz'
+
+path.resolve('/foo/bar', '/tmp/file/')
+// returns
+'/tmp/file'
+
+path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
+// if currently in /home/myself/node, it returns
+'/home/myself/node/wwwroot/static_files/gif/image.gif'
+

path.relative(from, to)#

+

Solve the relative path from from to to. + +

+

At times we have two absolute paths, and we need to derive the relative +path from one to the other. This is actually the reverse transform of +path.resolve, which means we see that: + +

+
path.resolve(from, path.relative(from, to)) == path.resolve(to)
+

Examples: + +

+
path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb')
+// returns
+'..\\..\\impl\\bbb'
+
+path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
+// returns
+'../../impl/bbb'
+

path.dirname(p)#

+

Return the directory name of a path. Similar to the Unix dirname command. + +

+

Example: + +

+
path.dirname('/foo/bar/baz/asdf/quux')
+// returns
+'/foo/bar/baz/asdf'
+

path.basename(p, [ext])#

+

Return the last portion of a path. Similar to the Unix basename command. + +

+

Example: + +

+
path.basename('/foo/bar/baz/asdf/quux.html')
+// returns
+'quux.html'
+
+path.basename('/foo/bar/baz/asdf/quux.html', '.html')
+// returns
+'quux'
+

path.extname(p)#

+

Return the extension of the path, from the last '.' to end of string +in the last portion of the path. If there is no '.' in the last portion +of the path or the first character of it is '.', then it returns +an empty string. Examples: + +

+
path.extname('index.html')
+// returns
+'.html'
+
+path.extname('index.')
+// returns
+'.'
+
+path.extname('index')
+// returns
+''
+

path.exists(p, [callback])#

+

Test whether or not the given path exists by checking with the file system. +Then call the callback argument with either true or false. Example: + +

+
path.exists('/etc/passwd', function (exists) {
+  util.debug(exists ? "it's there" : "no passwd!");
+});
+

path.existsSync(p)#

+

Synchronous version of path.exists. + +

+

net#

+
Stability: 3 - Stable
+

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'); + +

+

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

+

Creates a new TCP server. The connectionListener argument is +automatically set as a listener for the 'connection' +event. + +

+

options is an object with the following defaults: + +

+
{ allowHalfOpen: false
+}
+

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. + +

+

Here is an example of a echo server which listens for connections +on port 8124: + +

+
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');
+});
+

Test this by using telnet: + +

+
telnet localhost 8124
+

To listen on the socket /tmp/echo.sock the third line from the last would +just be changed to + +

+
server.listen('/tmp/echo.sock', function() { //'listening' listener
+

Use nc to connect to a UNIX domain socket server: + +

+
nc -U /tmp/echo.sock
+

net.connect(arguments...)#

+

net.createConnection(arguments...)#

+

Construct a new socket object and opens a socket to the given location. When +the socket is established the 'connect' event will be +emitted. + +

+

The arguments for these methods change the type of connection: + +

+
    +
  • net.connect(port, [host], [connectListener])
    • +

  • net.createConnection(port, [host], [connectListener])

    +

    Creates a TCP connection to port on host. If host is omitted, +'localhost' will be assumed.

    +
    • +

  • net.connect(path, [connectListener])

    +
    • +

  • net.createConnection(path, [connectListener])

    +

    Creates unix socket connection to path.

    +
    • +
+

The connectListener parameter will be added as an listener for the +'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 connect on the socket /tmp/echo.sock the second line would just be +changed to + +

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

Class: net.Server#

+

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. When the server has been bound, +'listening' event will be emitted. +the last parameter listeningListener will be added as an listener for the +'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 +would be to wait a second and then try again. This can be done with + +

+
server.on('error', function (e) {
+  if (e.code == 'EADDRINUSE') {
+    console.log('Address in use, retrying...');
+    setTimeout(function () {
+      server.close();
+      server.listen(PORT, HOST);
+    }, 1000);
+  }
+});
+

(Note: All sockets in Node set SO_REUSEADDR already) + + +

+

server.listen(path, [listeningListener])#

+

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

+

This function is asynchronous. When the server has been bound, +'listening' event will be emitted. +the last parameter listeningListener will be added as an listener for the +'listening' event. + +

+

server.close()#

+

Stops the server from accepting new connections. This function is +asynchronous, the server is finally closed when the server emits a 'close' +event. + + +

+

server.address()#

+

Returns the bound address and port of the server as reported by the operating system. +Useful to find which port was assigned when giving getting an OS-assigned address. +Returns an object with two properties, e.g. {"address":"127.0.0.1", "port":2121} + +

+

Example: + +

+
var server = net.createServer(function (socket) {
+  socket.end("goodbye\n");
+});
+
+// grab a random port.
+server.listen(function() {
+  address = server.address();
+  console.log("opened server on %j", address);
+});
+

Don't call server.address() until the 'listening' event has been emitted. + +

+

server.maxConnections#

+

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

+

server.connections#

+

The number of concurrent connections on the server. + + +

+

net.Server is an EventEmitter with the following events: + +

+

Event: 'listening'#

+

Emitted when the server has been bound after calling server.listen. + +

+

Event: 'connection'#

+
    +
  • Socket object The connection object
    • +
+

Emitted when a new connection is made. socket is an instance of +net.Socket. + +

+

Event: 'close'#

+

Emitted when the server closes. + +

+

Event: 'error'#

+
    +
  • Error Object
    • +
+

Emitted when an error occurs. The 'close' event will be called directly +following this event. See example in discussion of server.listen. + +

+

Class: net.Socket#

+

This object is an abstraction of a TCP or UNIX socket. net.Socket +instances implement a duplex Stream interface. They can be created by the +user and used as a client (with connect()) or they can be created by Node +and passed to the user through the 'connection' event of a server. + +

+

new net.Socket([options])#

+

Construct a new socket object. + +

+

options is an object with the following defaults: + +

+
{ fd: null
+  type: null
+  allowHalfOpen: false
+}
+

fd allows you to specify the existing file descriptor of socket. type +specified underlying protocol. It can be 'tcp4', 'tcp6', or 'unix'. +About allowHalfOpen, refer to createServer() and 'end' event. + +

+

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, +localhost will be assumed. If a path is given, the socket will be +opened as a unix socket to that path. + +

+

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 +the exception. + +

+

The connectListener parameter will be added as an listener for the +'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). + +

+

The consequence of this internal buffering is that memory may grow. This +property shows the number of characters currently buffered to be written. +(Number of characters is approximately equal to the number of bytes to be +written, but the buffer may contain strings, and the strings are lazily +encoded, so the exact number of bytes is not known.) + +

+

Users who experience large or growing bufferSize should attempt to +"throttle" the data flows in their program with pause() and resume(). + + +

+

socket.setEncoding([encoding])#

+

Sets the encoding (either 'ascii', 'utf8', or 'base64') for data that is +received. Defaults to null. + +

+

socket.setSecure()#

+

This function has been removed in v0.3. It used to upgrade the connection to +SSL/TLS. See the TLS section for the new API. + + +

+

socket.write(data, [encoding], [callback])#

+

Sends data on the socket. The second parameter specifies the encoding in the +case of a string--it defaults to UTF8 encoding. + +

+

Returns true if the entire data was flushed successfully to the kernel +buffer. Returns false if all or part of the data was queued in user memory. +'drain' will be emitted when the buffer is again free. + +

+

The optional callback parameter will be executed when the data is finally +written out - this may not be immediately. + +

+

socket.end([data], [encoding])#

+

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(). + +

+

socket.destroy()#

+

Ensures that no more I/O activity happens on this socket. Only necessary in +case of errors (parse error or so). + +

+

socket.pause()#

+

Pauses the reading of data. That is, 'data' events will not be emitted. +Useful to throttle back an upload. + +

+

socket.resume()#

+

Resumes reading after a call to pause(). + +

+

socket.setTimeout(timeout, [callback])#

+

Sets the socket to timeout after timeout milliseconds of inactivity on +the socket. By default net.Socket do not have a timeout. + +

+

When an idle timeout is triggered the socket will receive a 'timeout' +event but the connection will not be severed. The user must manually end() +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. + +

+

socket.setNoDelay([noDelay])#

+

Disables the Nagle algorithm. By default TCP connections use the Nagle +algorithm, they buffer data before sending it off. Setting true for +noDelay will immediately fire off data each time socket.write() is called. +noDelay defaults to true. + +

+

socket.setKeepAlive([enable], [initialDelay])#

+

Enable/disable keep-alive functionality, and optionally set the initial +delay before the first keepalive probe is sent on an idle socket. +enable defaults to false. + +

+

Set initialDelay (in milliseconds) to set the delay between the last +data packet received and the first keepalive probe. Setting 0 for +initialDelay will leave the value unchanged from the default +(or previous) setting. Defaults to 0. + +

+

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} + +

+

socket.remoteAddress#

+

The string representation of the remote IP address. For example, +'74.125.127.100' or '2001:4860:a005::68'. + +

+

socket.remotePort#

+

The numeric representation of the remote port. For example, +80 or 21. + +

+

socket.bytesRead#

+

The amount of received bytes. + +

+

socket.bytesWritten#

+

The amount of bytes sent. + + +

+

net.Socket instances are EventEmitters with the following events: + +

+

Event: 'connect'#

+

Emitted when a socket connection is successfully established. +See connect(). + +

+

Event: 'data'#

+
    +
  • Buffer object
    • +
+

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 section for more +information.) + +

+

Note that the data will be lost if there is no listener when a Socket +emits a 'data' event. + +

+

Event: 'end'#

+

Emitted when the other end of the socket sends a FIN packet. + +

+

By default (allowHalfOpen == false) the socket will destroy its file +descriptor once it has written out its pending write queue. However, by +setting allowHalfOpen == true the socket will not automatically end() +its side allowing the user to write arbitrary amounts of data, with the +caveat that the user is required to end() their side now. + + +

+

Event: 'timeout'#

+

Emitted if the socket times out from inactivity. This is only to notify that +the socket has been idle. The user must manually close the connection. + +

+

See also: socket.setTimeout() + + +

+

Event: 'drain'#

+

Emitted when the write buffer becomes empty. Can be used to throttle uploads. + +

+

See also: the return values of socket.write() + +

+

Event: 'error'#

+
    +
  • Error object
    • +
+

Emitted when an error occurs. The 'close' event will be called directly +following this event. + +

+

Event: 'close'#

+
    +
  • had_error Boolean true if the socket had a transmission error
    • +
+

Emitted once the socket is fully closed. The argument had_error is a boolean +which says if the socket was closed due to a transmission error. + +

+

net.isIP(input)#

+

Tests if input is an IP address. Returns 0 for invalid strings, +returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses. + + +

+

net.isIPv4(input)#

+

Returns true if input is a version 4 IP address, otherwise returns false. + + +

+

net.isIPv6(input)#

+

Returns true if input is a version 6 IP address, otherwise returns false. + + +

+

UDP / Datagram Sockets#

+
Stability: 3 - Stable
+ + +

Datagram sockets are available through require('dgram'). + +

+

dgram.createSocket(type, [callback])#

+
    +
  • type String. Either 'udp4' or 'udp6'
    • +
  • callback Function. Attached as a listener to message events. +Optional
    • +
  • Returns: Socket object
    • +
+

Creates a datagram Socket of the specified types. Valid types are udp4 +and udp6. + +

+

Takes an optional callback which is added as a listener for message events. + +

+

Call socket.bind if you want to receive datagrams. socket.bind() will bind +to the "all interfaces" address on a random port (it does the right thing for +both udp4 and udp6 sockets). You can then retrieve the address and port +with socket.address().address and socket.address().port. + +

+

Class: Socket#

+

The dgram Socket class encapsulates the datagram functionality. It +should be created via dgram.createSocket(type, [callback]). + +

+

Event: 'message'#

+
    +
  • msg Buffer object. The message
    • +
  • rinfo Object. Remote address information
    • +
+

Emitted when a new datagram is available on a socket. msg is a Buffer and rinfo is +an object with the sender's address information and the number of bytes in the datagram. + +

+

Event: 'listening'#

+

Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets +are created. + +

+

Event: 'close'#

+

Emitted when a socket is closed with close(). No new message events will be emitted +on this socket. + +

+

Event: 'error'#

+
    +
  • exception Error object
    • +
+

Emitted when an error occurs. + +

+

dgram.send(buf, offset, length, port, address, [callback])#

+
    +
  • buf Buffer object. Message to be sent
    • +
  • offset Integer. Offset in the buffer where the message starts.
    • +
  • length Integer. Number of bytes in the message.
    • +
  • port Integer. destination port
    • +
  • address String. destination IP
    • +
  • callback Function. Callback when message is done being delivered. +Optional.
    • +
+

For UDP sockets, the destination port and IP address must be specified. A string +may be supplied for the address parameter, and it will be resolved with DNS. An +optional callback may be specified to detect any DNS errors and when buf may be +re-used. Note that DNS lookups will delay the time that a send takes place, at +least until the next tick. The only way to know for sure that a send has taken place +is to use the callback. + +

+

If the socket has not been previously bound with a call to bind, it's +assigned a random port number and bound to the "all interfaces" address +(0.0.0.0 for udp4 sockets, ::0 for udp6 sockets). + +

+

Example of sending a UDP packet to a random port on localhost; + +

+
var dgram = require('dgram');
+var message = new Buffer("Some bytes");
+var client = dgram.createSocket("udp4");
+client.send(message, 0, message.length, 41234, "localhost", function(err, bytes) {
+  client.close();
+});
+

A Note about UDP datagram size + +

+

The maximum size of an IPv4/v6 datagram depends on the MTU (Maximum Transmission Unit) +and on the Payload Length field size. + +

+
    +

  • The Payload Length field is 16 bits wide, which means that a normal payload +cannot be larger than 64K octets including internet header and data +(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header); +this is generally true for loopback interfaces, but such long datagrams +are impractical for most hosts and networks.

    +
    • +

  • The MTU is the largest size a given link layer technology can support for datagrams. +For any link, IPv4 mandates a minimum MTU of 68 octets, while the recommended MTU +for IPv4 is 576 (typically recommended as the MTU for dial-up type applications), +whether they arrive whole or in fragments.

    +

    For IPv6, the minimum MTU is 1280 octets, however, the mandatory minimum +fragment reassembly buffer size is 1500 octets. +The value of 68 octets is very small, since most current link layer technologies have +a minimum MTU of 1500 (like Ethernet).

    +
    • +
+

Note that it's impossible to know in advance the MTU of each link through which +a packet might travel, and that generally sending a datagram greater than +the (receiver) MTU won't work (the packet gets silently dropped, without +informing the source that the data did not reach its intended recipient). + +

+

dgram.bind(port, [address])#

+
    +
  • port Integer
    • +
  • address String, Optional
    • +
+

For UDP sockets, listen for datagrams on a named port and optional address. If +address is not specified, the OS will try to listen on all addresses. + +

+

Example of a UDP server listening on port 41234: + +

+
var dgram = require("dgram");
+
+var server = dgram.createSocket("udp4");
+
+server.on("message", function (msg, rinfo) {
+  console.log("server got: " + msg + " from " +
+    rinfo.address + ":" + rinfo.port);
+});
+
+server.on("listening", function () {
+  var address = server.address();
+  console.log("server listening " +
+      address.address + ":" + address.port);
+});
+
+server.bind(41234);
+// server listening 0.0.0.0:41234
+

dgram.close()#

+

Close the underlying socket and stop listening for data on it. + +

+

dgram.address()#

+

Returns an object containing the address information for a socket. For UDP sockets, +this object will contain address and port. + +

+

dgram.setBroadcast(flag)#

+
    +
  • flag Boolean
    • +
+

Sets or clears the SO_BROADCAST socket option. When this option is set, UDP packets +may be sent to a local interface's broadcast address. + +

+

dgram.setTTL(ttl)#

+
    +
  • ttl Integer
    • +
+

Sets the IP_TTL socket option. TTL stands for "Time to Live," but in this context it +specifies the number of IP hops that a packet is allowed to go through. Each router or +gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a +router, it will not be forwarded. Changing TTL values is typically done for network +probes or when multicasting. + +

+

The argument to setTTL() is a number of hops between 1 and 255. The default on most +systems is 64. + +

+

dgram.setMulticastTTL(ttl)#

+
    +
  • ttl Integer
    • +
+

Sets the IP_MULTICAST_TTL socket option. TTL stands for "Time to Live," but in this +context it specifies the number of IP hops that a packet is allowed to go through, +specifically for multicast traffic. Each router or gateway that forwards a packet +decrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. + +

+

The argument to setMulticastTTL() is a number of hops between 0 and 255. The default on most +systems is 64. + +

+

dgram.setMulticastLoopback(flag)#

+
    +
  • flag Boolean
    • +
+

Sets or clears the IP_MULTICAST_LOOP socket option. When this option is set, multicast +packets will also be received on the local interface. + +

+

dgram.addMembership(multicastAddress, [multicastInterface])#

+
    +
  • multicastAddress String
    • +
  • multicastInterface String, Optional
    • +
+

Tells the kernel to join a multicast group with IP_ADD_MEMBERSHIP socket option. + +

+

If multicastInterface is not specified, the OS will try to add membership to all valid +interfaces. + +

+

dgram.dropMembership(multicastAddress, [multicastInterface])#

+
    +
  • multicastAddress String
    • +
  • multicastInterface String, Optional
    • +
+

Opposite of addMembership - tells the kernel to leave a multicast group with +IP_DROP_MEMBERSHIP socket option. This is automatically called by the kernel +when the socket is closed or process terminates, so most apps will never need to call +this. + +

+

If multicastInterface is not specified, the OS will try to drop membership to all valid +interfaces. + +

+

DNS#

+
Stability: 3 - Stable
+

Use require('dns') to access this module. All methods in the dns module +use C-Ares except for dns.lookup which uses getaddrinfo(3) in a thread +pool. C-Ares is much faster than getaddrinfo but the system resolver is +more constant with how other programs operate. When a user does +net.connect(80, 'google.com') or http.get({ host: 'google.com' }) the +dns.lookup method is used. Users who need to do a large number of look ups +quickly should use the methods that go through C-Ares. + +

+

Here is an example which resolves 'www.google.com' then reverse +resolves the IP addresses which are returned. + +

+
var dns = require('dns');
+
+dns.resolve4('www.google.com', function (err, addresses) {
+  if (err) throw err;
+
+  console.log('addresses: ' + JSON.stringify(addresses));
+
+  addresses.forEach(function (a) {
+    dns.reverse(a, function (err, domains) {
+      if (err) {
+        console.log('reverse for ' + a + ' failed: ' +
+          err.message);
+      } else {
+        console.log('reverse for ' + a + ': ' +
+          JSON.stringify(domains));
+      }
+    });
+  });
+});
+

dns.lookup(domain, [family], callback)#

+

Resolves a domain (e.g. 'google.com') into the first found A (IPv4) or +AAAA (IPv6) record. +The family can be the integer 4 or 6. Defaults to null that indicates +both Ip v4 and v6 address family. + +

+

The callback has arguments (err, address, family). The address argument +is a string representation of a IP v4 or v6 address. The family argument +is either the integer 4 or 6 and denotes the family of address (not +necessarily the value initially passed to lookup). + + +

+

dns.resolve(domain, [rrtype], callback)#

+

Resolves a domain (e.g. 'google.com') into an array of the record types +specified by rrtype. Valid rrtypes are 'A' (IPV4 addresses, default), +'AAAA' (IPV6 addresses), 'MX' (mail exchange records), 'TXT' (text +records), 'SRV' (SRV records), 'PTR' (used for reverse IP lookups), +'NS' (name server records) and 'CNAME' (canonical name records). + +

+

The callback has arguments (err, addresses). The type of each item +in addresses is determined by the record type, and described in the +documentation for the corresponding lookup methods below. + +

+

On error, err would be an instanceof Error object, where err.errno is +one of the error codes listed below and err.message is a string describing +the error in English. + + +

+

dns.resolve4(domain, callback)#

+

The same as dns.resolve(), but only for IPv4 queries (A records). +addresses is an array of IPv4 addresses (e.g. +['74.125.79.104', '74.125.79.105', '74.125.79.106']). + +

+

dns.resolve6(domain, callback)#

+

The same as dns.resolve4() except for IPv6 queries (an AAAA query). + + +

+

dns.resolveMx(domain, callback)#

+

The same as dns.resolve(), but only for mail exchange queries (MX records). + +

+

addresses is an array of MX records, each with a priority and an exchange +attribute (e.g. [{'priority': 10, 'exchange': 'mx.example.com'},...]). + +

+

dns.resolveTxt(domain, callback)#

+

The same as dns.resolve(), but only for text queries (TXT records). +addresses is an array of the text records available for domain (e.g., +['v=spf1 ip4:0.0.0.0 ~all']). + +

+

dns.resolveSrv(domain, callback)#

+

The same as dns.resolve(), but only for service records (SRV records). +addresses is an array of the SRV records available for domain. Properties +of SRV records are priority, weight, port, and name (e.g., +[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]). + +

+

dns.reverse(ip, callback)#

+

Reverse resolves an ip address to an array of domain names. + +

+

The callback has arguments (err, domains). + +

+

dns.resolveNs(domain, callback)#

+

The same as dns.resolve(), but only for name server records (NS records). +addresses is an array of the name server records available for domain +(e.g., ['ns1.example.com', 'ns2.example.com']). + +

+

dns.resolveCname(domain, callback)#

+

The same as dns.resolve(), but only for canonical name records (CNAME +records). addresses is an array of the canonical name records available for +domain (e.g., ['bar.example.com']). + +

+

If there an an error, err will be non-null and an instanceof the Error +object. + +

+

Each DNS query can return an error code. + +

+
    +
  • dns.TEMPFAIL: timeout, SERVFAIL or similar.
    • +
  • dns.PROTOCOL: got garbled reply.
    • +
  • dns.NXDOMAIN: domain does not exists.
    • +
  • dns.NODATA: domain exists but no data of reqd type.
    • +
  • dns.NOMEM: out of memory while processing.
    • +
  • dns.BADQUERY: the query is malformed.
    • +
+

HTTP#

+
Stability: 3 - Stable
+

To use the HTTP server and client one must require('http'). + +

+

The HTTP interfaces in Node are designed to support many features +of the protocol which have been traditionally difficult to use. +In particular, large, possibly chunk-encoded, messages. The interface is +careful to never buffer entire requests or responses--the +user is able to stream data. + +

+

HTTP message headers are represented by an object like this: + +

+
{ 'content-length': '123',
+  'content-type': 'text/plain',
+  'connection': 'keep-alive',
+  'accept': '*/*' }
+

Keys are lowercased. Values are not modified. + +

+

In order to support the full spectrum of possible HTTP applications, Node's +HTTP API is very low-level. It deals with stream handling and message +parsing only. It parses a message into headers and body but it does not +parse the actual headers or the body. + + +

+

http.createServer([requestListener])#

+

Returns a new web server object. + +

+

The requestListener is a function which is automatically +added to the 'request' event. + +

+

Class: http.Server#

+

This is an EventEmitter with the following events: + +

+

Event: 'request'#

+

function (request, response) { } + +

+

Emitted each time there is a request. Note that there may be multiple requests +per connection (in the case of keep-alive connections). + request is an instance of http.ServerRequest and response is + an instance of http.ServerResponse + +

+

Event: 'connection'#

+

function (socket) { } + +

+

When a new TCP stream is established. socket is an object of type + net.Socket. Usually users will not want to access this event. The + socket can also be accessed at request.connection. + +

+

Event: 'close'#

+

function () { } + +

+

Emitted when the server closes. + +

+

Event: 'checkContinue'#

+

function (request, response) { } + +

+

Emitted each time a request with an http Expect: 100-continue is received. +If this event isn't listened for, the server will automatically respond +with a 100 Continue as appropriate. + +

+

Handling this event involves calling response.writeContinue if the client +should continue to send the request body, or generating an appropriate HTTP +response (e.g., 400 Bad Request) if the client should not continue to send the +request body. + +

+

Note that when this event is emitted and handled, the request event will +not be emitted. + +

+

Event: 'upgrade'#

+

function (request, socket, head) { } + +

+

Emitted each time a client requests a http upgrade. If this event isn't +listened for, then clients requesting an upgrade will have their connections +closed. + +

+
    +
  • request is the arguments for the http request, as it is in the request event.
    • +
  • socket is the network socket between the server and client.
    • +
  • head is an instance of Buffer, the first packet of the upgraded stream, this may be empty.
    • +
+

After this event is emitted, the request's socket will not have a data +event listener, meaning you will need to bind to it in order to handle data +sent to the server on that socket. + +

+

Event: 'clientError'#

+

function (exception) { } + +

+

If a client connection emits an 'error' event - it will forwarded here. + +

+

server.listen(port, [hostname], [callback])#

+

Begin accepting connections on the specified port and hostname. If the +hostname is omitted, the server will accept connections directed to any +IPv4 address (INADDR_ANY). + +

+

To listen to a unix socket, supply a filename instead of port and hostname. + +

+

This function is asynchronous. The last parameter callback will be added as +a listener for the 'listening' event. +See also net.Server.listen(). + + +

+

server.listen(path, [callback])#

+

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

+

This function is asynchronous. The last parameter callback will be added as +a listener for the 'listening' event. +See also net.Server.listen(). + + +

+

server.close()#

+

Stops the server from accepting new connections. +See net.Server.close(). + + +

+

Class: http.ServerRequest#

+

This object is created internally by a HTTP server -- not by +the user -- and passed as the first argument to a 'request' listener. + +

+

The request implements the Readable Stream +interface. This is an EventEmitter with the following events: + +

+

Event: 'data'#

+

function (chunk) { } + +

+

Emitted when a piece of the message body is received. The chunk is a string if +an encoding has been set with request.setEncoding(), otherwise it's a +Buffer. + +

+

Note that the data will be lost if there is no listener when a +ServerRequest emits a 'data' event. + +

+

Event: 'end'#

+

function () { } + +

+

Emitted exactly once for each request. After that, no more 'data' events +will be emitted on the request. + +

+

Event: 'close'#

+

function () { } + +

+

Indicates that the underlaying connection was terminated before +response.end() was called or able to flush. + +

+

Just like 'end', this event occurs only once per request, and no more 'data' +events will fire afterwards. + +

+

Note: 'close' can fire after 'end', but not vice versa. + +

+

request.method#

+

The request method as a string. Read only. Example: +'GET', 'DELETE'. + + +

+

request.url#

+

Request URL string. This contains only the URL that is +present in the actual HTTP request. If the request is: + +

+
GET /status?name=ryan HTTP/1.1\r\n
+Accept: text/plain\r\n
+\r\n
+

Then request.url will be: + +

+
'/status?name=ryan'
+

If you would like to parse the URL into its parts, you can use +require('url').parse(request.url). Example: + +

+
node> require('url').parse('/status?name=ryan')
+{ href: '/status?name=ryan',
+  search: '?name=ryan',
+  query: 'name=ryan',
+  pathname: '/status' }
+

If you would like to extract the params from the query string, +you can use the require('querystring').parse function, or pass +true as the second argument to require('url').parse. Example: + +

+
node> require('url').parse('/status?name=ryan', true)
+{ href: '/status?name=ryan',
+  search: '?name=ryan',
+  query: { name: 'ryan' },
+  pathname: '/status' }
+

request.headers#

+

Read only. + +

+

request.trailers#

+

Read only; HTTP trailers (if present). Only populated after the 'end' event. + +

+

request.httpVersion#

+

The HTTP protocol version as a string. Read only. Examples: +'1.1', '1.0'. +Also request.httpVersionMajor is the first integer and +request.httpVersionMinor is the second. + + +

+

request.setEncoding([encoding])#

+

Set the encoding for the request body. Either 'utf8' or 'binary'. Defaults +to null, which means that the 'data' event will emit a Buffer object.. + + +

+

request.pause()#

+

Pauses request from emitting events. Useful to throttle back an upload. + + +

+

request.resume()#

+

Resumes a paused request. + +

+

request.connection#

+

The net.Socket object associated with the connection. + + +

+

With HTTPS support, use request.connection.verifyPeer() and +request.connection.getPeerCertificate() to obtain the client's +authentication details. + + + +

+

Class: http.ServerResponse#

+

This object is created internally by a HTTP server--not by the user. It is +passed as the second parameter to the 'request' event. + +

+

The response implements the Writable Stream +interface. This is an EventEmitter with the following events: + +

+

Event: 'close'#

+

function () { } + +

+

Indicates that the underlaying connection was terminated before +response.end() was called or able to flush. + +

+

response.writeContinue()#

+

Sends a HTTP/1.1 100 Continue message to the client, indicating that +the request body should be sent. See the checkContinue event on +Server. + +

+

response.writeHead(statusCode, [reasonPhrase], [headers])#

+

Sends a response header to the request. The status code is a 3-digit HTTP +status code, like 404. The last argument, headers, are the response headers. +Optionally one can give a human-readable reasonPhrase as the second +argument. + +

+

Example: + +

+
var body = 'hello world';
+response.writeHead(200, {
+  'Content-Length': body.length,
+  'Content-Type': 'text/plain' });
+

This method must only be called once on a message and it must +be called before response.end() is called. + +

+

If you call response.write() or response.end() before calling this, the +implicit/mutable headers will be calculated and call this function for you. + +

+

Note: that Content-Length is given in bytes not characters. The above example +works because the string 'hello world' contains only single byte characters. +If the body contains higher coded characters then Buffer.byteLength() +should be used to determine the number of bytes in a given encoding. +And Node does not check whether Content-Length and the length of the body +which has been transmitted are equal or not. + +

+

response.statusCode#

+

When using implicit headers (not calling response.writeHead() explicitly), this property +controls the status code that will be send to the client when the headers get +flushed. + +

+

Example: + +

+
response.statusCode = 404;
+

After response header was sent to the client, this property indicates the +status code which was sent out. + +

+

response.setHeader(name, value)#

+

Sets a single header value for implicit headers. If this header already exists +in the to-be-sent headers, its value will be replaced. Use an array of strings +here if you need to send multiple headers with the same name. + +

+

Example: + +

+
response.setHeader("Content-Type", "text/html");
+

or + +

+
response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]);
+

response.getHeader(name)#

+

Reads out a header that's already been queued but not sent to the client. Note +that the name is case insensitive. This can only be called before headers get +implicitly flushed. + +

+

Example: + +

+
var contentType = response.getHeader('content-type');
+

response.removeHeader(name)#

+

Removes a header that's queued for implicit sending. + +

+

Example: + +

+
response.removeHeader("Content-Encoding");
+

response.write(chunk, [encoding])#

+

If this method is called and response.writeHead() has not been called, it will +switch to implicit header mode and flush the implicit headers. + +

+

This sends a chunk of the response body. This method may +be called multiple times to provide successive parts of the body. + +

+

chunk can be a string or a buffer. If chunk is a string, +the second parameter specifies how to encode it into a byte stream. +By default the encoding is 'utf8'. + +

+

Note: This is the raw HTTP body and has nothing to do with +higher-level multi-part body encodings that may be used. + +

+

The first time response.write() is called, it will send the buffered +header information and the first body to the client. The second time +response.write() is called, Node assumes you're going to be streaming +data, and sends that separately. That is, the response is buffered up to the +first chunk of body. + +

+

response.addTrailers(headers)#

+

This method adds HTTP trailing headers (a header but at the end of the +message) to the response. + +

+

Trailers will only be emitted if chunked encoding is used for the +response; if it is not (e.g., if the request was HTTP/1.0), they will +be silently discarded. + +

+

Note that HTTP requires the Trailer header to be sent if you intend to +emit trailers, with a list of the header fields in its value. E.g., + +

+
response.writeHead(200, { 'Content-Type': 'text/plain',
+                          'Trailer': 'Content-MD5' });
+response.write(fileData);
+response.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});
+response.end();
+

response.end([data], [encoding])#

+

This method signals to the server that all of the response headers and body +has been sent; that server should consider this message complete. +The method, response.end(), MUST be called on each +response. + +

+

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

+

http.request(options, callback)#

+

Node maintains several connections per server to make HTTP requests. +This function allows one to transparently issue requests. options align +with url.parse(). + +

+

Options: + +

+
    +
  • host: A domain name or IP address of the server to issue the request to. +Defaults to 'localhost'.
    • +
  • hostname: To support url.parse() hostname is preferred over host
    • +
  • port: Port of remote server. Defaults to 80.
    • +
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • +
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • +
  • path: Request path. Defaults to '/'. Should include query string if any. +E.G. '/index.html?page=12'
    • +
  • headers: An object containing request headers.
    • +
  • auth: Basic authentication i.e. 'user:password' to compute an +Authorization header.
    • +
  • agent: Controls Agent behavior. When an Agent is used +request will default to Connection: keep-alive. Possible values:
      +
    • undefined (default): use global Agent for this host +and port.
      • +
    • Agent object: explicitly use the passed in Agent.
      • +
    • false: opts out of connection pooling with an Agent, defaults request to +Connection: close.
      • +
    +
    • +
+

http.request() returns an instance of the http.ClientRequest +class. The ClientRequest instance is a writable stream. If one needs to +upload a file with a POST request, then write to the ClientRequest object. + +

+

Example: + +

+
var options = {
+  host: 'www.google.com',
+  port: 80,
+  path: '/upload',
+  method: 'POST'
+};
+
+var req = http.request(options, function(res) {
+  console.log('STATUS: ' + res.statusCode);
+  console.log('HEADERS: ' + JSON.stringify(res.headers));
+  res.setEncoding('utf8');
+  res.on('data', function (chunk) {
+    console.log('BODY: ' + chunk);
+  });
+});
+
+req.on('error', function(e) {
+  console.log('problem with request: ' + e.message);
+});
+
+// write data to request body
+req.write('data\n');
+req.write('data\n');
+req.end();
+

Note that in the example req.end() was called. With http.request() one +must always call req.end() to signify that you're done with the request - +even if there is no data being written to the request body. + +

+

If any error is encountered during the request (be that with DNS resolution, +TCP level errors, or actual HTTP parse errors) an 'error' event is emitted +on the returned request object. + +

+

There are a few special headers that should be noted. + +

+
    +

  • Sending a 'Connection: keep-alive' will notify Node that the connection to +the server should be persisted until the next request.

    +
    • +

  • Sending a 'Content-length' header will disable the default chunked encoding.

    +
    • +

  • Sending an 'Expect' header will immediately send the request headers. +Usually, when sending 'Expect: 100-continue', you should both set a timeout +and listen for the continue event. See RFC2616 Section 8.2.3 for more +information.

    +
    • +

  • Sending an Authorization header will override using the auth option +to compute basic authentication.

    +
    • +
+

http.get(options, callback)#

+

Since most requests are GET requests without bodies, Node provides this +convenience method. The only difference between this method and http.request() is +that it sets the method to GET and calls req.end() automatically. + +

+

Example: + +

+
var options = {
+  host: 'www.google.com',
+  port: 80,
+  path: '/index.html'
+};
+
+http.get(options, function(res) {
+  console.log("Got response: " + res.statusCode);
+}).on('error', function(e) {
+  console.log("Got error: " + e.message);
+});
+

Class: http.Agent#

+

In node 0.5.3+ there is a new implementation of the HTTP Agent which is used +for pooling sockets used in HTTP client requests. + +

+

Previously, a single agent instance help the pool for single host+port. The +current implementation now holds sockets for any number of hosts. + +

+

The current HTTP Agent also defaults client requests to using +Connection:keep-alive. If no pending HTTP requests are waiting on a socket +to become free the socket is closed. This means that node's pool has the +benefit of keep-alive when under load but still does not require developers +to manually close the HTTP clients using keep-alive. + +

+

Sockets are removed from the agent's pool when the socket emits either a +"close" event or a special "agentRemove" event. This means that if you intend +to keep one HTTP request open for a long time and don't want it to stay in the +pool you can do something along the lines of: + +

+
http.get(options, function(res) {
+  // Do stuff
+}).on("socket", function (socket) {
+  socket.emit("agentRemove");
+});
+

Alternatively, you could just opt out of pooling entirely using agent:false: + +

+
http.get({host:'localhost', port:80, path:'/', agent:false}, function (res) {
+  // Do stuff
+})
+

agent.maxSockets#

+

By default set to 5. Determines how many concurrent sockets the agent can have +open per host. + +

+

agent.sockets#

+

An object which contains arrays of sockets currently in use by the Agent. Do not +modify. + +

+

agent.requests#

+

An object which contains queues of requests that have not yet been assigned to +sockets. Do not modify. + +

+

http.globalAgent#

+

Global instance of Agent which is used as the default for all http client +requests. + + +

+

Class: http.ClientRequest#

+

This object is created internally and returned from http.request(). It +represents an in-progress request whose header has already been queued. The +header is still mutable using the setHeader(name, value), getHeader(name), +removeHeader(name) API. The actual header will be sent along with the first +data chunk or when closing the connection. + +

+

To get the response, add a listener for 'response' to the request object. +'response' will be emitted from the request object when the response +headers have been received. The 'response' event is executed with one +argument which is an instance of http.ClientResponse. + +

+

During the 'response' event, one can add listeners to the +response object; particularly to listen for the 'data' event. Note that +the 'response' event is called before any part of the response body is received, +so there is no need to worry about racing to catch the first part of the +body. As long as a listener for 'data' is added during the 'response' +event, the entire body will be caught. + + +

+
// Good
+request.on('response', function (response) {
+  response.on('data', function (chunk) {
+    console.log('BODY: ' + chunk);
+  });
+});
+
+// Bad - misses all or part of the body
+request.on('response', function (response) {
+  setTimeout(function () {
+    response.on('data', function (chunk) {
+      console.log('BODY: ' + chunk);
+    });
+  }, 10);
+});
+

Note: Node does not check whether Content-Length and the length of the body +which has been transmitted are equal or not. + +

+

The request implements the Writable Stream +interface. This is an EventEmitter with the following events: + +

+

Event 'response'#

+

function (response) { } + +

+

Emitted when a response is received to this request. This event is emitted only once. The +response argument will be an instance of http.ClientResponse. + +

+

Options: + +

+
    +
  • host: A domain name or IP address of the server to issue the request to.
    • +
  • port: Port of remote server.
    • +
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • +
+

Event: 'socket'#

+

function (socket) { } + +

+

Emitted after a socket is assigned to this request. + +

+

Event: 'upgrade'#

+

function (response, 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. + +

+

A client server pair that show you how to listen for the upgrade event using http.getAgent: + +

+
var http = require('http');
+var net = require('net');
+
+// Create an HTTP server
+var srv = http.createServer(function (req, res) {
+  res.writeHead(200, {'Content-Type': 'text/plain'});
+  res.end('okay');
+});
+srv.on('upgrade', function(req, socket, upgradeHead) {
+  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
+               'Upgrade: WebSocket\r\n' +
+               'Connection: Upgrade\r\n' +
+               '\r\n\r\n');
+
+  socket.ondata = function(data, start, end) {
+    socket.write(data.toString('utf8', start, end), 'utf8'); // echo back
+  };
+});
+
+// now that server is running
+srv.listen(1337, '127.0.0.1', function() {
+
+  // make a request
+  var options = {
+    port: 1337,
+    host: '127.0.0.1',
+    headers: {
+      'Connection': 'Upgrade',
+      'Upgrade': 'websocket'
+    }
+  };
+
+  var req = http.request(options);
+  req.end();
+
+  req.on('upgrade', function(res, socket, upgradeHead) {
+    console.log('got upgraded!');
+    socket.end();
+    process.exit(0);
+  });
+});
+

Event: 'continue'#

+

function () { } + +

+

Emitted when the server sends a '100 Continue' HTTP response, usually because +the request contained 'Expect: 100-continue'. This is an instruction that +the client should send the request body. + +

+

request.write(chunk, [encoding])#

+

Sends a chunk of the body. By calling this method +many times, the user can stream a request body to a +server--in that case it is suggested to use the +['Transfer-Encoding', 'chunked'] header line when +creating the request. + +

+

The chunk argument should be a buffer or a string. + +

+

The encoding argument is optional and only applies when chunk is a string. +Defaults to 'utf8'. + + +

+

request.end([data], [encoding])#

+

Finishes sending the request. If any parts of the body are +unsent, it will flush them to the stream. If the request is +chunked, this will send the terminating '0\r\n\r\n'. + +

+

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

+

request.abort()#

+

Aborts a request. (New since v0.3.8.) + +

+

request.setTimeout(timeout, [callback])#

+

Once a socket is assigned to this request and is connected +socket.setTimeout(timeout, [callback]) +will be called. + +

+

request.setNoDelay([noDelay])#

+

Once a socket is assigned to this request and is connected +socket.setNoDelay(noDelay) +will be called. + +

+

request.setSocketKeepAlive([enable], [initialDelay])#

+

Once a socket is assigned to this request and is connected +socket.setKeepAlive(enable, [initialDelay]) +will be called. + +

+

http.ClientResponse#

+

This object is created when making a request with http.request(). It is +passed to the 'response' event of the request object. + +

+

The response implements the Readable Stream +interface. This is an EventEmitter with the following events: + + +

+

Event: 'data'#

+

function (chunk) { } + +

+

Emitted when a piece of the message body is received. + +

+

Note that the data will be lost if there is no listener when a +ClientResponse emits a 'data' event. + + +

+

Event: 'end'#

+

function () { } + +

+

Emitted exactly once for each message. No arguments. After +emitted no other events will be emitted on the response. + +

+

Event: 'close'#

+

function (err) { } + +

+

Indicates that the underlaying connection was terminated before +end event was emitted. +See http.ServerRequest's 'close' event for more +information. + +

+

response.statusCode#

+

The 3-digit HTTP response status code. E.G. 404. + +

+

response.httpVersion#

+

The HTTP version of the connected-to server. Probably either +'1.1' or '1.0'. +Also response.httpVersionMajor is the first integer and +response.httpVersionMinor is the second. + +

+

response.headers#

+

The response headers object. + +

+

response.trailers#

+

The response trailers object. Only populated after the 'end' event. + +

+

response.setEncoding([encoding])#

+

Set the encoding for the response body. Either 'utf8', 'ascii', or +'base64'. Defaults to null, which means that the 'data' event will emit +a Buffer object. + +

+

response.pause()#

+

Pauses response from emitting events. Useful to throttle back a download. + +

+

response.resume()#

+

Resumes a paused response. + +

+

HTTPS#

+
Stability: 3 - Stable
+

HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a +separate module. + +

+

Class: https.Server#

+

This class is a subclass of tls.Server and emits events same as +http.Server. See http.Server for more information. + +

+

https.createServer(options, [requestListener])#

+

Returns a new HTTPS web server object. The options is similar to +tls.createServer(). The requestListener is a function which is +automatically added to the 'request' event. + +

+

Example: + +

+
// curl -k https://localhost:8000/
+var https = require('https');
+var fs = require('fs');
+
+var options = {
+  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
+  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
+};
+
+https.createServer(options, function (req, res) {
+  res.writeHead(200);
+  res.end("hello world\n");
+}).listen(8000);
+

Or + +

+
var https = require('https');
+var fs = require('fs');
+
+var options = {
+  pfx: fs.readFileSync('server.pfx')
+};
+
+https.createServer(options, function (req, res) {
+  res.writeHead(200);
+  res.end("hello world\n");
+}).listen(8000);
+

https.request(options, callback)#

+

Makes a request to a secure web server. +All options from http.request() are valid. + +

+

Example: + +

+
var https = require('https');
+
+var options = {
+  host: 'encrypted.google.com',
+  port: 443,
+  path: '/',
+  method: 'GET'
+};
+
+var req = https.request(options, function(res) {
+  console.log("statusCode: ", res.statusCode);
+  console.log("headers: ", res.headers);
+
+  res.on('data', function(d) {
+    process.stdout.write(d);
+  });
+});
+req.end();
+
+req.on('error', function(e) {
+  console.error(e);
+});
+

The options argument has the following options + +

+
    +
  • host: IP or domain of host to make request to. Defaults to 'localhost'.
    • +
  • port: port of host to request to. Defaults to 443.
    • +
  • path: Path to request. Default '/'.
    • +

  • method: HTTP request method. Default 'GET'.

    +
    • +

  • host: A domain name or IP address of the server to issue the request to. +Defaults to 'localhost'.

    +
    • +
  • hostname: To support url.parse() hostname is preferred over host
    • +
  • port: Port of remote server. Defaults to 443.
    • +
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • +
  • path: Request path. Defaults to '/'. Should include query string if any. +E.G. '/index.html?page=12'
    • +
  • headers: An object containing request headers.
    • +
  • auth: Basic authentication i.e. 'user:password' to compute an +Authorization header.
    • +
  • agent: Controls Agent behavior. When an Agent is +used request will default to Connection: keep-alive. Possible values:
      +
    • undefined (default): use globalAgent for this +host and port.
      • +
    • Agent object: explicitly use the passed in Agent.
      • +
    • false: opts out of connection pooling with an Agent, defaults request to +Connection: close.
      • +
    +
    • +
+

The following options from tls.connect() can also be +specified. However, a globalAgent silently ignores these. + +

+
    +
  • pfx: Certificate, Private key and CA certificates to use for SSL. Default null.
    • +
  • key: Private key to use for SSL. Default null.
    • +
  • passphrase: A string of passphrase for the private key or pfx. Default null.
    • +
  • cert: Public x509 certificate to use. Default null.
    • +
  • ca: An authority certificate or array of authority certificates to check +the remote host against.
    • +
+

In order to specify these options, use a custom Agent. + +

+

Example: + +

+
var options = {
+  host: 'encrypted.google.com',
+  port: 443,
+  path: '/',
+  method: 'GET',
+  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
+  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
+};
+options.agent = new https.Agent(options);
+
+var req = https.request(options, function(res) {
+  ...
+}
+

Or does not use an Agent. + +

+

Example: + +

+
var options = {
+  host: 'encrypted.google.com',
+  port: 443,
+  path: '/',
+  method: 'GET',
+  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
+  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
+  agent: false
+};
+
+var req = https.request(options, function(res) {
+  ...
+}
+

https.get(options, callback)#

+

Like http.get() but for HTTPS. + +

+

Example: + +

+
var https = require('https');
+
+https.get({ host: 'encrypted.google.com', path: '/' }, function(res) {
+  console.log("statusCode: ", res.statusCode);
+  console.log("headers: ", res.headers);
+
+  res.on('data', function(d) {
+    process.stdout.write(d);
+  });
+
+}).on('error', function(e) {
+  console.error(e);
+});
+

Class: https.Agent#

+

An Agent object for HTTPS similar to http.Agent. +See https.request() for more information. + + +

+

https.globalAgent#

+

Global instance of https.Agent which is used as the default +for all HTTPS client requests. + +

+

URL#

+
Stability: 3 - Stable
+

This module has utilities for URL resolution and parsing. +Call require('url') to use it. + +

+

Parsed URL objects have some or all of the following fields, depending on +whether or not they exist in the URL string. Any parts that are not in the URL +string will not be in the parsed object. Examples are shown for the URL + +

+

'http://user:pass@host.com:8080/p/a/t/h?query=string#hash' + +

+
    +

  • href: The full URL that was originally parsed. Both the protocol and host are lowercased.

    +

    Example: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

    +
    • +

  • protocol: The request protocol, lowercased.

    +

    Example: 'http:'

    +
    • +

  • host: The full lowercased host portion of the URL, including port +information.

    +

    Example: 'host.com:8080'

    +
    • +

  • auth: The authentication information portion of a URL.

    +

    Example: 'user:pass'

    +
    • +

  • hostname: Just the lowercased hostname portion of the host.

    +

    Example: 'host.com'

    +
    • +

  • port: The port number portion of the host.

    +

    Example: '8080'

    +
    • +

  • pathname: The path section of the URL, that comes after the host and +before the query, including the initial slash if present.

    +

    Example: '/p/a/t/h'

    +
    • +

  • search: The 'query string' portion of the URL, including the leading +question mark.

    +

    Example: '?query=string'

    +
    • +

  • path: Concatenation of pathname and search.

    +

    Example: '/p/a/t/h?query=string'

    +
    • +

  • query: Either the 'params' portion of the query string, or a +querystring-parsed object.

    +

    Example: 'query=string' or {'query':'string'}

    +
    • +

  • hash: The 'fragment' portion of the URL including the pound-sign.

    +

    Example: '#hash'

    +
    • +
+

The following methods are provided by the URL module: + +

+

url.parse(urlStr, [parseQueryString], [slashesDenoteHost])#

+

Take a URL string, and return an object. + +

+

Pass true as the second argument to also parse +the query string using the querystring module. +Defaults to false. + +

+

Pass true as the third argument to treat //foo/bar as +{ host: 'foo', pathname: '/bar' } rather than +{ pathname: '//foo/bar' }. Defaults to false. + +

+

url.format(urlObj)#

+

Take a parsed URL object, and return a formatted URL string. + +

+
    +
  • href will be ignored.
    • +
  • protocolis treated the same with or without the trailing : (colon).
      +
    • The protocols http, https, ftp, gopher, file will be +postfixed with :// (colon-slash-slash).
      • +
    • All other protocols mailto, xmpp, aim, sftp, foo, etc will +be postfixed with : (colon)
      • +
    +
    • +
  • auth will be used if present.
    • +
  • hostname will only be used if host is absent.
    • +
  • port will only be used if host is absent.
    • +
  • host will be used in place of auth, hostname, and port
    • +
  • pathname is treated the same with or without the leading / (slash)
    • +
  • search will be used in place of query
    • +
  • query (object; see querystring) will only be used if search is absent.
    • +
  • search is treated the same with or without the leading ? (question mark)
    • +
  • hash is treated the same with or without the leading # (pound sign, anchor)
    • +
+

url.resolve(from, to)#

+

Take a base URL, and a href URL, and resolve them as a browser would for +an anchor tag. + +

+

Query String#

+
Stability: 3 - Stable
+ + +

This module provides utilities for dealing with query strings. +It provides the following methods: + +

+

querystring.stringify(obj, [sep], [eq])#

+

Serialize an object to a query string. +Optionally override the default separator ('&') and assignment ('=') +characters. + +

+

Example: + +

+
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })
+// returns
+'foo=bar&baz=qux&baz=quux&corge='
+
+querystring.stringify({foo: 'bar', baz: 'qux'}, ';', ':')
+// returns
+'foo:bar;baz:qux'
+

querystring.parse(str, [sep], [eq])#

+

Deserialize a query string to an object. +Optionally override the default separator ('&') and assignment ('=') +characters. + +

+

Example: + +

+
querystring.parse('foo=bar&baz=qux&baz=quux&corge')
+// returns
+{ foo: 'bar', baz: ['qux', 'quux'], corge: '' }
+

querystring.escape#

+

The escape function used by querystring.stringify, +provided so that it could be overridden if necessary. + +

+

querystring.unescape#

+

The unescape function used by querystring.parse, +provided so that it could be overridden if necessary. + +

+

Readline#

+
Stability: 3 - Stable
+

To use this module, do require('readline'). Readline allows reading of a +stream (such as STDIN) on a line-by-line basis. + +

+

Note that once you've invoked this module, your node program will not +terminate until you've closed the interface, and the STDIN stream. Here's how +to allow your program to gracefully terminate: + +

+
var rl = require('readline');
+
+var i = rl.createInterface(process.stdin, process.stdout, null);
+i.question("What do you think of node.js?", function(answer) {
+  // TODO: Log the answer in a database
+  console.log("Thank you for your valuable feedback.");
+
+  // These two lines together allow the program to terminate. Without
+  // them, it would run forever.
+  i.close();
+  process.stdin.destroy();
+});
+

rl.createInterface(input, output, completer)#

+

Takes two streams and creates a readline interface. The completer function +is used for autocompletion. When given a substring, it returns [[substr1, +substr2, ...], originalsubstring]. + +

+

Also completer can be run in async mode if it accepts two arguments: + +

+

function completer(linePartial, callback) { + callback(null, [['123'], linePartial]); + } + +

+

createInterface is commonly used with process.stdin and +process.stdout in order to accept user input: + +

+
var readline = require('readline'),
+  rl = readline.createInterface(process.stdin, process.stdout);
+

Class: Interface#

+

The class that represents a readline interface with a stdin and stdout +stream. + +

+

rl.setPrompt(prompt, length)#

+

Sets the prompt, for example when you run node on the command line, you see +> , which is node's prompt. + +

+

rl.prompt()#

+

Readies readline for input from the user, putting the current setPrompt +options on a new line, giving the user a new spot to write. + +

+

rl.question(query, callback)#

+

Prepends the prompt with query and invokes callback with the user's +response. Displays the query to the user, and then invokes callback with the +user's response after it has been typed. + +

+

Example usage: + +

+
interface.question('What is your favorite food?', function(answer) {
+  console.log('Oh, so your favorite food is ' + answer);
+});
+

rl.close()#

+

Closes tty. + +

+

rl.pause()#

+

Pauses tty. + +

+

rl.resume()#

+

Resumes tty. + +

+

rl.write()#

+

Writes to tty. + +

+

Event: 'line'#

+

function (line) {} + +

+

Emitted whenever the in stream receives a \n, usually received when the +user hits enter, or return. This is a good hook to listen for user input. + +

+

Example of listening for line: + +

+
rl.on('line', function (cmd) {
+  console.log('You just typed: '+cmd);
+});
+

Event: 'close'#

+

function () {} + +

+

Emitted whenever the in stream receives a ^C or ^D, respectively known +as SIGINT and EOT. This is a good way to know the user is finished using +your program. + +

+

Example of listening for close, and exiting the program afterward: + +

+
rl.on('close', function() {
+  console.log('goodbye!');
+  process.exit(0);
+});
+

Here's an example of how to use all these together to craft a tiny command +line interface: + +

+
var readline = require('readline'),
+  rl = readline.createInterface(process.stdin, process.stdout),
+  prefix = 'OHAI> ';
+
+rl.on('line', function(line) {
+  switch(line.trim()) {
+    case 'hello':
+      console.log('world!');
+      break;
+    default:
+      console.log('Say what? I might have heard `' + line.trim() + '`');
+      break;
+  }
+  rl.setPrompt(prefix, prefix.length);
+  rl.prompt();
+}).on('close', function() {
+  console.log('Have a great day!');
+  process.exit(0);
+});
+console.log(prefix + 'Good to see you. Try typing stuff.');
+rl.setPrompt(prefix, prefix.length);
+rl.prompt();
+

Take a look at this slightly more complicated +example, and +http-console for a real-life use +case. + +

+

REPL#

+

A Read-Eval-Print-Loop (REPL) is available both as a standalone program and easily +includable in other programs. REPL provides a way to interactively run +JavaScript and see the results. It can be used for debugging, testing, or +just trying things out. + +

+

By executing node without any arguments from the command-line you will be +dropped into the REPL. It has simplistic emacs line-editing. + +

+
mjr:~$ node
+Type '.help' for options.
+> a = [ 1, 2, 3];
+[ 1, 2, 3 ]
+> a.forEach(function (v) {
+...   console.log(v);
+...   });
+1
+2
+3
+

For advanced line-editors, start node with the environmental variable NODE_NO_READLINE=1. +This will start the REPL in canonical terminal settings which will allow you to use with rlwrap. + +

+

For example, you could add this to your bashrc file: + +

+
alias node="env NODE_NO_READLINE=1 rlwrap node"
+

repl.start([prompt], [stream], [eval], [useGlobal], [ignoreUndefined])#

+

Starts a REPL with prompt as the prompt and stream for all I/O. prompt +is optional and defaults to > . stream is optional and defaults to +process.stdin. eval is optional too and defaults to async wrapper for +eval(). + +

+

If useGlobal is set to true, then the repl will use the global object, +instead of running scripts in a separate context. Defaults to false. + +

+

If ignoreUndefined is set to true, then the repl will not output return value +of command if it's undefined. Defaults to false. + +

+

You can use your own eval function if it has following signature: + +

+
function eval(cmd, callback) {
+  callback(null, result);
+}
+

Multiple REPLs may be started against the same running instance of node. Each +will share the same global object but will have unique I/O. + +

+

Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket: + +

+
var net = require("net"),
+    repl = require("repl");
+
+connections = 0;
+
+repl.start("node via stdin> ");
+
+net.createServer(function (socket) {
+  connections += 1;
+  repl.start("node via Unix socket> ", socket);
+}).listen("/tmp/node-repl-sock");
+
+net.createServer(function (socket) {
+  connections += 1;
+  repl.start("node via TCP socket> ", socket);
+}).listen(5001);
+

Running this program from the command line will start a REPL on stdin. Other +REPL clients may connect through the Unix socket or TCP socket. telnet is useful +for connecting to TCP sockets, and socat can be used to connect to both Unix and +TCP sockets. + +

+

By starting a REPL from a Unix socket-based server instead of stdin, you can +connect to a long-running node process without restarting it. + + +

+

REPL Features#

+ + +

Inside the REPL, Control+D will exit. Multi-line expressions can be input. +Tab completion is supported for both global and local variables. + +

+

The special variable _ (underscore) contains the result of the last expression. + +

+
> [ "a", "b", "c" ]
+[ 'a', 'b', 'c' ]
+> _.length
+3
+> _ += 1
+4
+

The REPL provides access to any variables in the global scope. You can expose +a variable to the REPL explicitly by assigning it to the context object +associated with each REPLServer. For example: + +

+
// repl_test.js
+var repl = require("repl"),
+    msg = "message";
+
+repl.start().context.m = msg;
+

Things in the context object appear as local within the REPL: + +

+
mjr:~$ node repl_test.js
+> m
+'message'
+

There are a few special REPL commands: + +

+
    +
  • .break - While inputting a multi-line expression, sometimes you get lost +or just don't care about completing it. .break will start over.
    • +
  • .clear - Resets the context object to an empty object and clears any +multi-line expression.
    • +
  • .exit - Close the I/O stream, which will cause the REPL to exit.
    • +
  • .help - Show this list of special commands.
    • +
  • .save - Save the current REPL session to a file
    +

    .save ./file/to/save.js

    +
    +
    • +
  • .load - Load a file into the current REPL session.
    +

    .load ./file/to/load.js

    +
    +
    • +
+

The following key combinations in the REPL have these special effects: + +

+
    +
  • <ctrl>C - Similar to the .break keyword. Terminates the current +command. Press twice on a blank line to forcibly exit.
    • +
  • <ctrl>D - Similar to the .exit keyword.
    • +
+

Executing JavaScript#

+
Stability: 3 - Stable
+ + +

You can access this module with: + +

+
var vm = require('vm');
+

JavaScript code can be compiled and run immediately or compiled, saved, and run later. + + +

+

vm.runInThisContext(code, [filename])#

+

vm.runInThisContext() compiles code, runs it and returns the result. Running +code does not have access to local scope. filename is optional, it's used only +in stack traces. + +

+

Example of using vm.runInThisContext and eval to run the same code: + +

+
var localVar = 123,
+    usingscript, evaled,
+    vm = require('vm');
+
+usingscript = vm.runInThisContext('localVar = 1;',
+  'myfile.vm');
+console.log('localVar: ' + localVar + ', usingscript: ' +
+  usingscript);
+evaled = eval('localVar = 1;');
+console.log('localVar: ' + localVar + ', evaled: ' +
+  evaled);
+
+// localVar: 123, usingscript: 1
+// localVar: 1, evaled: 1
+

vm.runInThisContext does not have access to the local scope, so localVar is unchanged. +eval does have access to the local scope, so localVar is changed. + +

+

In case of syntax error in code, vm.runInThisContext emits the syntax error to stderr +and throws an exception. + + +

+

vm.runInNewContext(code, [sandbox], [filename])#

+

vm.runInNewContext compiles code, then runs it in sandbox and returns the +result. Running code does not have access to local scope. The object sandbox +will be used as the global object for code. +sandbox and filename are optional, filename is only used in stack traces. + +

+

Example: compile and execute code that increments a global variable and sets a new one. +These globals are contained in the sandbox. + +

+
var util = require('util'),
+    vm = require('vm'),
+    sandbox = {
+      animal: 'cat',
+      count: 2
+    };
+
+vm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');
+console.log(util.inspect(sandbox));
+
+// { animal: 'cat', count: 3, name: 'kitty' }
+

Note that running untrusted code is a tricky business requiring great care. To prevent accidental +global variable leakage, vm.runInNewContext is quite useful, but safely running untrusted code +requires a separate process. + +

+

In case of syntax error in code, vm.runInNewContext emits the syntax error to stderr +and throws an exception. + +

+

vm.runInContext(code, context, [filename])#

+

vm.runInContext compiles code, then runs it in context and returns the +result. A (V8) context comprises a global object, together with a set of +built-in objects and functions. Running code does not have access to local scope +and the global object held within context will be used as the global object +for code. +filename is optional, it's used only in stack traces. + +

+

Example: compile and execute code in a existing context. + +

+
var util = require('util'),
+    vm = require('vm'),
+    initSandbox = {
+      animal: 'cat',
+      count: 2
+    },
+    context = vm.createContext(initSandbox);
+
+vm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');
+console.log(util.inspect(context));
+
+// { animal: 'cat', count: 3, name: 'CATT' }
+

Note that createContext will perform a shallow clone of the supplied sandbox object in order to +initialise the global object of the freshly constructed context. + +

+

Note that running untrusted code is a tricky business requiring great care. To prevent accidental +global variable leakage, vm.runInContext is quite useful, but safely running untrusted code +requires a separate process. + +

+

In case of syntax error in code, vm.runInContext emits the syntax error to stderr +and throws an exception. + +

+

vm.createContext([initSandbox])#

+

vm.createContext creates a new context which is suitable for use as the 2nd argument of a subsequent +call to vm.runInContext. A (V8) context comprises a global object together with a set of +build-in objects and functions. The optional argument initSandbox will be shallow-copied +to seed the initial contents of the global object used by the context. + +

+

vm.createScript(code, [filename])#

+

createScript compiles code but does not run it. Instead, it returns a +vm.Script object representing this compiled code. This script can be run +later many times using methods below. The returned script is not bound to any +global object. It is bound before each run, just for that run. filename is +optional, it's only used in stack traces. + +

+

In case of syntax error in code, createScript prints the syntax error to stderr +and throws an exception. + + +

+

Class: Script#

+

A class for running scripts. Returned by vm.createScript. + +

+

script.runInThisContext()#

+

Similar to vm.runInThisContext but a method of a precompiled Script object. +script.runInThisContext runs the code of script and returns the result. +Running code does not have access to local scope, but does have access to the global object +(v8: in actual context). + +

+

Example of using script.runInThisContext to compile code once and run it multiple times: + +

+
var vm = require('vm');
+
+globalVar = 0;
+
+var script = vm.createScript('globalVar += 1', 'myfile.vm');
+
+for (var i = 0; i < 1000 ; i += 1) {
+  script.runInThisContext();
+}
+
+console.log(globalVar);
+
+// 1000
+

script.runInNewContext([sandbox])#

+

Similar to vm.runInNewContext a method of a precompiled Script object. +script.runInNewContext runs the code of script with sandbox as the global object and returns the result. +Running code does not have access to local scope. sandbox is optional. + +

+

Example: compile code that increments a global variable and sets one, then execute this code multiple times. +These globals are contained in the sandbox. + +

+
var util = require('util'),
+    vm = require('vm'),
+    sandbox = {
+      animal: 'cat',
+      count: 2
+    };
+
+var script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');
+
+for (var i = 0; i < 10 ; i += 1) {
+  script.runInNewContext(sandbox);
+}
+
+console.log(util.inspect(sandbox));
+
+// { animal: 'cat', count: 12, name: 'kitty' }
+

Note that running untrusted code is a tricky business requiring great care. To prevent accidental +global variable leakage, script.runInNewContext is quite useful, but safely running untrusted code +requires a separate process. + +

+

Child Process#

+
Stability: 3 - Stable
+

Node provides a tri-directional popen(3) facility through the +child_process module. + +

+

It is possible to stream data through a child's stdin, stdout, and +stderr in a fully non-blocking way. + +

+

To create a child process use require('child_process').spawn() or +require('child_process').fork(). The semantics of each are slightly +different, and explained below. + +

+

Class: ChildProcess#

+

ChildProcess is an EventEmitter. + +

+

Child processes always have three streams associated with them. child.stdin, +child.stdout, and child.stderr. These may be shared with the stdio +streams of the parent process, or they may be separate stream objects +which can be piped to and from. + +

+

The ChildProcess class is not intended to be used directly. Use the +spawn() or fork() methods to create a Child Process instance. + +

+

Event: 'exit'#

+
    +
  • code Number the exit code, if it exited normally.
    • +
  • signal String the signal passed to kill the child process, if it +was killed by the parent.
    • +
+

This event is emitted after the child process ends. If the process terminated +normally, code is the final exit code of the process, otherwise null. If +the process terminated due to receipt of a signal, signal is the string name +of the signal, otherwise null. + +

+

See waitpid(2). + +

+

child.stdin#

+
    +
  • Stream object
    • +
+

A Writable Stream that represents the child process's stdin. +Closing this stream via end() often causes the child process to terminate. + +

+

If the child stdio streams are shared with the parent, then this will +not be set. + +

+

child.stdout#

+
    +
  • Stream object
    • +
+

A Readable Stream that represents the child process's stdout. + +

+

If the child stdio streams are shared with the parent, then this will +not be set. + +

+

child.stderr#

+
    +
  • Stream object
    • +
+

A Readable Stream that represents the child process's stderr. + +

+

If the child stdio streams are shared with the parent, then this will +not be set. + +

+

child.pid#

+
    +
  • Integer
    • +
+

The PID of the child process. + +

+

Example: + +

+
var spawn = require('child_process').spawn,
+    grep  = spawn('grep', ['ssh']);
+
+console.log('Spawned child pid: ' + grep.pid);
+grep.stdin.end();
+

child.kill([signal])#

+
    +
  • signal String
    • +
+

Send a signal to the child process. If no argument is given, the process will +be sent 'SIGTERM'. See signal(7) for a list of available signals. + +

+
var spawn = require('child_process').spawn,
+    grep  = spawn('grep', ['ssh']);
+
+grep.on('exit', function (code, signal) {
+  console.log('child process terminated due to receipt of signal '+signal);
+});
+
+// send SIGHUP to process
+grep.kill('SIGHUP');
+

Note that while the function is called kill, the signal delivered to the child +process may not actually kill it. kill really just sends a signal to a process. + +

+

See kill(2) + +

+

child.send(message, [sendHandle])#

+
    +
  • message Object
    • +
  • sendHandle Handle object
    • +
+

Send a message (and, optionally, a handle object) to a child process. + +

+

See child_process.fork() for details. + +

+

child_process.spawn(command, [args], [options])#

+
    +
  • command String The command to run
    • +
  • args Array List of string arguments
    • +
  • options Object
      +
    • cwd String Current working directory of the child process
      • +
    • customFds Array Deprecated File descriptors for the child to use +for stdio. (See below)
      • +
    • env Object Environment key-value pairs
      • +
    +
    • +
  • return: ChildProcess object
    • +
+

Launches a new process with the given command, with command line arguments in args. +If omitted, args defaults to an empty Array. + +

+

The third argument is used to specify additional options, which defaults to: + +

+
{ cwd: undefined,
+  env: process.env
+}
+

cwd allows you to specify the working directory from which the process is spawned. +Use env to specify environment variables that will be visible to the new process. + +

+

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code: + +

+
var util  = require('util'),
+    spawn = require('child_process').spawn,
+    ls    = spawn('ls', ['-lh', '/usr']);
+
+ls.stdout.on('data', function (data) {
+  console.log('stdout: ' + data);
+});
+
+ls.stderr.on('data', function (data) {
+  console.log('stderr: ' + data);
+});
+
+ls.on('exit', function (code) {
+  console.log('child process exited with code ' + code);
+});
+

Example: A very elaborate way to run 'ps ax | grep ssh' + +

+
var util  = require('util'),
+    spawn = require('child_process').spawn,
+    ps    = spawn('ps', ['ax']),
+    grep  = spawn('grep', ['ssh']);
+
+ps.stdout.on('data', function (data) {
+  grep.stdin.write(data);
+});
+
+ps.stderr.on('data', function (data) {
+  console.log('ps stderr: ' + data);
+});
+
+ps.on('exit', function (code) {
+  if (code !== 0) {
+    console.log('ps process exited with code ' + code);
+  }
+  grep.stdin.end();
+});
+
+grep.stdout.on('data', function (data) {
+  console.log(data);
+});
+
+grep.stderr.on('data', function (data) {
+  console.log('grep stderr: ' + data);
+});
+
+grep.on('exit', function (code) {
+  if (code !== 0) {
+    console.log('grep process exited with code ' + code);
+  }
+});
+

Example of checking for failed exec: + +

+
var spawn = require('child_process').spawn,
+    child = spawn('bad_command');
+
+child.stderr.setEncoding('utf8');
+child.stderr.on('data', function (data) {
+  if (/^execvp\(\)/.test(data)) {
+    console.log('Failed to start child process.');
+  }
+});
+

Note that if spawn receives an empty options object, it will result in +spawning the process with an empty environment rather than using +process.env. This due to backwards compatibility issues with a deprecated +API. + +

+

There is a deprecated option called customFds which allows one to specify +specific file descriptors for the stdio of the child process. This API was +not portable to all platforms and therefore removed. +With customFds it was possible to hook up the new process' [stdin, stdout, +stderr] to existing streams; -1 meant that a new stream should be created. +Use at your own risk. + +

+

There are several internal options. In particular stdinStream, +stdoutStream, stderrStream. They are for INTERNAL USE ONLY. As with all +undocumented APIs in Node, they should not be used. + +

+

See also: child_process.exec() and child_process.fork() + +

+

child_process.exec(command, [options], callback)#

+
    +
  • command String The command to run, with space-separated arguments
    • +
  • options Object
      +
    • cwd String Current working directory of the child process
      • +
    • customFds Array Deprecated File descriptors for the child to use +for stdio. (See below)
      • +
    • env Object Environment key-value pairs
      • +
    • encoding String (Default: 'utf8')
      • +
    • timeout Number (Default: 0)
      • +
    • maxBuffer Number (Default: 200*1024)
      • +
    • killSignal String (Default: 'SIGTERM')
      • +
    +
    • +
  • callback Function called with the output when process terminates
      +
    • error Error
      • +
    • stdout Buffer
      • +
    • stderr Buffer
      • +
    +
    • +
  • Return: ChildProcess object
    • +
+

Runs a command in a shell and buffers the output. + +

+
var util = require('util'),
+    exec = require('child_process').exec,
+    child;
+
+child = exec('cat *.js bad_file | wc -l',
+  function (error, stdout, stderr) {
+    console.log('stdout: ' + stdout);
+    console.log('stderr: ' + stderr);
+    if (error !== null) {
+      console.log('exec error: ' + error);
+    }
+});
+

The callback gets the arguments (error, stdout, stderr). On success, error +will be null. On error, error will be an instance of Error and err.code +will be the exit code of the child process, and err.signal will be set to the +signal that terminated the process. + +

+

There is a second optional argument to specify several options. The +default options are + +

+
{ encoding: 'utf8',
+  timeout: 0,
+  maxBuffer: 200*1024,
+  killSignal: 'SIGTERM',
+  cwd: null,
+  env: null }
+

If timeout is greater than 0, then it will kill the child process +if it runs longer than timeout milliseconds. The child process is killed with +killSignal (default: 'SIGTERM'). maxBuffer specifies the largest +amount of data allowed on stdout or stderr - if this value is exceeded then +the child process is killed. + + +

+

child_process.execFile(file, args, options, callback)#

+
    +
  • file String The filename of the program to run
    • +
  • args Array List of string arguments
    • +
  • options Object
      +
    • cwd String Current working directory of the child process
      • +
    • customFds Array Deprecated File descriptors for the child to use +for stdio. (See below)
      • +
    • env Object Environment key-value pairs
      • +
    • encoding String (Default: 'utf8')
      • +
    • timeout Number (Default: 0)
      • +
    • maxBuffer Number (Default: 200*1024)
      • +
    • killSignal String (Default: 'SIGTERM')
      • +
    +
    • +
  • callback Function called with the output when process terminates
      +
    • error Error
      • +
    • stdout Buffer
      • +
    • stderr Buffer
      • +
    +
    • +
  • Return: ChildProcess object
    • +
+

This is similar to child_process.exec() except it does not execute a +subshell but rather the specified file directly. This makes it slightly +leaner than child_process.exec. It has the same options. + + +

+

child_process.fork(modulePath, [args], [options])#

+
    +
  • modulePath String The module to run in the child
    • +
  • args Array List of string arguments
    • +
  • options Object
      +
    • cwd String Current working directory of the child process
      • +
    • customFds Array Deprecated File descriptors for the child to use +for stdio. (See below)
      • +
    • env Object Environment key-value pairs
      • +
    • encoding String (Default: 'utf8')
      • +
    • timeout Number (Default: 0)
      • +
    +
    • +
  • Return: ChildProcess object
    • +
+

This is a special case of the spawn() functionality for spawning Node +processes. In addition to having all the methods in a normal ChildProcess +instance, the returned object has a communication channel built-in. The +channel is written to with child.send(message, [sendHandle]) and messages +are received by a 'message' event on the child. + +

+

For example: + +

+
var cp = require('child_process');
+
+var n = cp.fork(__dirname + '/sub.js');
+
+n.on('message', function(m) {
+  console.log('PARENT got message:', m);
+});
+
+n.send({ hello: 'world' });
+

And then the child script, 'sub.js' might look like this: + +

+
process.on('message', function(m) {
+  console.log('CHILD got message:', m);
+});
+
+process.send({ foo: 'bar' });
+

In the child the process object will have a send() method, and process +will emit objects each time it receives a message on its channel. + +

+

By default the spawned Node process will have the stdin, stdout, stderr +associated with the parent's. + +

+

These child Nodes are still whole new instances of V8. Assume at least 30ms +startup and 10mb memory for each new Node. That is, you cannot create many +thousands of them. + +

+

The sendHandle option to child.send() is for sending a handle object to +another process. Child will receive the handle as as second argument to the +message event. Here is an example of sending a handle: + +

+
var server = require('net').createServer();
+var child = require('child_process').fork(__dirname + '/child.js');
+// Open up the server object and send the handle.
+server.listen(1337, function() {
+  child.send({ server: true }, server._handle);
+});
+

Here is an example of receiving the server handle and sharing it between +processes: + +

+
process.on('message', function(m, serverHandle) {
+  if (serverHandle) {
+    var server = require('net').createServer();
+    server.listen(serverHandle);
+  }
+});
+

Assert#

+
Stability: 5 - Locked
+

This module is used for writing unit tests for your applications, you can +access it with require('assert'). + +

+

assert.fail(actual, expected, message, operator)#

+

Throws an exception that displays the values for actual and expected separated by the provided operator. + +

+

assert(value, message), assert.ok(value, [message])#

+

Tests if value is a true value, it is equivalent to assert.equal(true, value, message); + +

+

assert.equal(actual, expected, [message])#

+

Tests shallow, coercive equality with the equal comparison operator ( == ). + +

+

assert.notEqual(actual, expected, [message])#

+

Tests shallow, coercive non-equality with the not equal comparison operator ( != ). + +

+

assert.deepEqual(actual, expected, [message])#

+

Tests for deep equality. + +

+

assert.notDeepEqual(actual, expected, [message])#

+

Tests for any deep inequality. + +

+

assert.strictEqual(actual, expected, [message])#

+

Tests strict equality, as determined by the strict equality operator ( === ) + +

+

assert.notStrictEqual(actual, expected, [message])#

+

Tests strict non-equality, as determined by the strict not equal operator ( !== ) + +

+

assert.throws(block, [error], [message])#

+

Expects block to throw an error. error can be constructor, regexp or +validation function. + +

+

Validate instanceof using constructor: + +

+
assert.throws(
+  function() {
+    throw new Error("Wrong value");
+  },
+  Error
+);
+

Validate error message using RegExp: + +

+
assert.throws(
+  function() {
+    throw new Error("Wrong value");
+  },
+  /value/
+);
+

Custom error validation: + +

+
assert.throws(
+  function() {
+    throw new Error("Wrong value");
+  },
+  function(err) {
+    if ( (err instanceof Error) && /value/.test(err) ) {
+      return true;
+    }
+  },
+  "unexpected error"
+);
+

assert.doesNotThrow(block, [error], [message])#

+

Expects block not to throw an error, see assert.throws for details. + +

+

assert.ifError(value)#

+

Tests if value is not a false value, throws if it is a true value. Useful when +testing the first argument, error in callbacks. + +

+

TTY#

+
Stability: 3 - Stable
+

Use require('tty') to access this module. + +

+

Example: + +

+
var tty = require('tty');
+process.stdin.resume();
+tty.setRawMode(true);
+process.stdin.on('keypress', function(char, key) {
+  if (key && key.ctrl && key.name == 'c') {
+    console.log('graceful exit');
+    process.exit()
+  }
+});
+

tty.isatty(fd)#

+

Returns true or false depending on if the fd is associated with a +terminal. + + +

+

tty.setRawMode(mode)#

+

mode should be true or false. This sets the properties of the current +process's stdin fd to act either as a raw device or default. + +

+

Zlib#

+
Stability: 3 - Stable
+

You can access this module with: + +

+
var zlib = require('zlib');
+

This provides bindings to Gzip/Gunzip, Deflate/Inflate, and +DeflateRaw/InflateRaw classes. Each class takes the same options, and +is a readable/writable Stream. + +

+

Examples#

+

Compressing or decompressing a file can be done by piping an +fs.ReadStream into a zlib stream, then into an fs.WriteStream. + +

+
var gzip = zlib.createGzip();
+var fs = require('fs');
+var inp = fs.createReadStream('input.txt');
+var out = fs.createWriteStream('input.txt.gz');
+
+inp.pipe(gzip).pipe(out);
+

Compressing or decompressing data in one step can be done by using +the convenience methods. + +

+
var input = '.................................';
+zlib.deflate(input, function(err, buffer) {
+  if (!err) {
+    console.log(buffer.toString('base64'));
+  }
+});
+
+var buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');
+zlib.unzip(buffer, function(err, buffer) {
+  if (!err) {
+    console.log(buffer.toString());
+  }
+});
+

To use this module in an HTTP client or server, use the +accept-encoding +on requests, and the +content-encoding +header on responses. + +

+

Note: these examples are drastically simplified to show +the basic concept. Zlib encoding can be expensive, and the results +ought to be cached. See Memory Usage Tuning +below for more information on the speed/memory/compression +tradeoffs involved in zlib usage. + +

+
// client request example
+var zlib = require('zlib');
+var http = require('http');
+var fs = require('fs');
+var request = http.get({ host: 'izs.me',
+                         path: '/',
+                         port: 80,
+                         headers: { 'accept-encoding': 'gzip,deflate' } });
+request.on('response', function(response) {
+  var output = fs.createWriteStream('izs.me_index.html');
+
+  switch (response.headers['content-encoding']) {
+    // or, just use zlib.createUnzip() to handle both cases
+    case 'gzip':
+      response.pipe(zlib.createGunzip()).pipe(output);
+      break;
+    case 'deflate':
+      response.pipe(zlib.createInflate()).pipe(output);
+      break;
+    default:
+      response.pipe(output);
+      break;
+  }
+});
+
+// server example
+// Running a gzip operation on every request is quite expensive.
+// It would be much more efficient to cache the compressed buffer.
+var zlib = require('zlib');
+var http = require('http');
+var fs = require('fs');
+http.createServer(function(request, response) {
+  var raw = fs.createReadStream('index.html');
+  var acceptEncoding = request.headers['accept-encoding'];
+  if (!acceptEncoding) {
+    acceptEncoding = '';
+  }
+
+  // Note: this is not a conformant accept-encoding parser.
+  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
+  if (acceptEncoding.match(/\bdeflate\b/)) {
+    response.writeHead(200, { 'content-encoding': 'deflate' });
+    raw.pipe(zlib.createDeflate()).pipe(response);
+  } else if (acceptEncoding.match(/\bgzip\b/)) {
+    response.writeHead(200, { 'content-encoding': 'gzip' });
+    raw.pipe(zlib.createGzip()).pipe(response);
+  } else {
+    response.writeHead(200, {});
+    raw.pipe(response);
+  }
+}).listen(1337);
+

Constants#

+ + +

All of the constants defined in zlib.h are also defined on +require('zlib'). They are described in more detail in the zlib +documentation. See http://zlib.net/manual.html#Constants +for more details. + +

+

zlib.createGzip([options])#

+

Returns a new Gzip object with an options. + +

+

zlib.createGunzip([options])#

+

Returns a new Gunzip object with an options. + +

+

zlib.createDeflate([options])#

+

Returns a new Deflate object with an options. + +

+

zlib.createInflate([options])#

+

Returns a new Inflate object with an options. + +

+

zlib.createDeflateRaw([options])#

+

Returns a new DeflateRaw object with an options. + +

+

zlib.createInflateRaw([options])#

+

Returns a new InflateRaw object with an options. + +

+

zlib.createUnzip([options])#

+

Returns a new Unzip object with an options. + + +

+

Class: zlib.Gzip#

+

Compress data using gzip. + +

+

Class: zlib.Gunzip#

+

Decompress a gzip stream. + +

+

Class: zlib.Deflate#

+

Compress data using deflate. + +

+

Class: zlib.Inflate#

+

Decompress a deflate stream. + +

+

Class: zlib.DeflateRaw#

+

Compress data using deflate, and do not append a zlib header. + +

+

Class: zlib.InflateRaw#

+

Decompress a raw deflate stream. + +

+

Class: zlib.Unzip#

+

Decompress either a Gzip- or Deflate-compressed stream by auto-detecting +the header. + +

+

Convenience Methods#

+ + +

All of these take a string or buffer as the first argument, and call the +supplied callback with callback(error, result). The +compression/decompression engine is created using the default settings +in all convenience methods. To supply different options, use the +zlib classes directly. + +

+

zlib.deflate(buf, callback)#

+

Compress a string with Deflate. + +

+

zlib.deflateRaw(buf, callback)#

+

Compress a string with DeflateRaw. + +

+

zlib.gzip(buf, callback)#

+

Compress a string with Gzip. + +

+

zlib.gunzip(buf, callback)#

+

Decompress a raw Buffer with Gunzip. + +

+

zlib.inflate(buf, callback)#

+

Decompress a raw Buffer with Inflate. + +

+

zlib.inflateRaw(buf, callback)#

+

Decompress a raw Buffer with InflateRaw. + +

+

zlib.unzip(buf, callback)#

+

Decompress a raw Buffer with Unzip. + +

+

Options#

+ + +

Each class takes an options object. All options are optional. (The +convenience methods use the default settings for all options.) + +

+

Note that some options are only +relevant when compressing, and are ignored by the decompression classes. + +

+
    +
  • chunkSize (default: 16*1024)
    • +
  • windowBits
    • +
  • level (compression only)
    • +
  • memLevel (compression only)
    • +
  • strategy (compression only)
    • +
+

See the description of deflateInit2 and inflateInit2 at +

+

http://zlib.net/manual.html#Advanced for more information on these. + +

+

Memory Usage Tuning#

+ + +

From zlib/zconf.h, modified to node's usage: + +

+

The memory requirements for deflate are (in bytes): + +

+
(1 << (windowBits+2)) +  (1 << (memLevel+9))
+

that is: 128K for windowBits=15 + 128K for memLevel = 8 +(default values) plus a few kilobytes for small objects. + +

+

For example, if you want to reduce +the default memory requirements from 256K to 128K, set the options to: + +

+
{ windowBits: 14, memLevel: 7 }
+

Of course this will generally degrade compression (there's no free lunch). + +

+

The memory requirements for inflate are (in bytes) + +

+
1 << windowBits
+

that is, 32K for windowBits=15 (default value) plus a few kilobytes +for small objects. + +

+

This is in addition to a single internal output slab buffer of size +chunkSize, which defaults to 16K. + +

+

The speed of zlib compression is affected most dramatically by the +level setting. A higher level will result in better compression, but +will take longer to complete. A lower level will result in less +compression, but will be much faster. + +

+

In general, greater memory usage options will mean that node has to make +fewer calls to zlib, since it'll be able to process more data in a +single write operation. So, this is another factor that affects the +speed, at the cost of memory usage. + +

+

os#

+
Stability: 4 - API Frozen
+

Provides a few basic operating-system related utility functions. + +

+

Use require('os') to access this module. + +

+

os.hostname()#

+

Returns the hostname of the operating system. + +

+

os.type()#

+

Returns the operating system name. + +

+

os.platform()#

+

Returns the operating system platform. + +

+

os.arch()#

+

Returns the operating system CPU architecture. + +

+

os.release()#

+

Returns the operating system release. + +

+

os.uptime()#

+

Returns the system uptime in seconds. + +

+

os.loadavg()#

+

Returns an array containing the 1, 5, and 15 minute load averages. + +

+

os.totalmem()#

+

Returns the total amount of system memory in bytes. + +

+

os.freemem()#

+

Returns the amount of free system memory in bytes. + +

+

os.cpus()#

+

Returns an array of objects containing information about each CPU/core installed: model, speed (in MHz), and times (an object containing the number of CPU ticks spent in: user, nice, sys, idle, and irq). + +

+

Example inspection of os.cpus: + +

+
[ { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 252020,
+       nice: 0,
+       sys: 30340,
+       idle: 1070356870,
+       irq: 0 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 306960,
+       nice: 0,
+       sys: 26980,
+       idle: 1071569080,
+       irq: 0 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 248450,
+       nice: 0,
+       sys: 21750,
+       idle: 1070919370,
+       irq: 0 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 256880,
+       nice: 0,
+       sys: 19430,
+       idle: 1070905480,
+       irq: 20 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 511580,
+       nice: 20,
+       sys: 40900,
+       idle: 1070842510,
+       irq: 0 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 291660,
+       nice: 0,
+       sys: 34360,
+       idle: 1070888000,
+       irq: 10 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 308260,
+       nice: 0,
+       sys: 55410,
+       idle: 1071129970,
+       irq: 880 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 266450,
+       nice: 1480,
+       sys: 34920,
+       idle: 1072572010,
+       irq: 30 } } ]
+

os.networkInterfaces()#

+

Get a list of network interfaces: + +

+
{ lo0: 
+   [ { address: '::1', family: 'IPv6', internal: true },
+     { address: 'fe80::1', family: 'IPv6', internal: true },
+     { address: '127.0.0.1', family: 'IPv4', internal: true } ],
+  en1: 
+   [ { address: 'fe80::cabc:c8ff:feef:f996', family: 'IPv6',
+       internal: false },
+     { address: '10.0.1.123', family: 'IPv4', internal: false } ],
+  vmnet1: [ { address: '10.99.99.254', family: 'IPv4', internal: false } ],
+  vmnet8: [ { address: '10.88.88.1', family: 'IPv4', internal: false } ],
+  ppp0: [ { address: '10.2.0.231', family: 'IPv4', internal: false } ] }
+

Debugger#

+
Stability: 3 - Stable
+ + +

V8 comes with an extensive debugger which is accessible out-of-process via a +simple TCP protocol. +Node has a built-in client for this debugger. To use this, start Node with the +debug argument; a prompt will appear: + +

+
% node debug myscript.js
+< debugger listening on port 5858
+connecting... ok
+break in /home/indutny/Code/git/indutny/myscript.js:1
+  1 x = 5;
+  2 setTimeout(function () {
+  3   debugger;
+debug>
+

Node's debugger client doesn't support the full range of commands, but +simple step and inspection is possible. By putting the statement debugger; +into the source code of your script, you will enable a breakpoint. + +

+

For example, suppose myscript.js looked like this: + +

+
// myscript.js
+x = 5;
+setTimeout(function () {
+  debugger;
+  console.log("world");
+}, 1000);
+console.log("hello");
+

Then once the debugger is run, it will break on line 4. + +

+
% node debug myscript.js
+< debugger listening on port 5858
+connecting... ok
+break in /home/indutny/Code/git/indutny/myscript.js:1
+  1 x = 5;
+  2 setTimeout(function () {
+  3   debugger;
+debug> cont
+< hello
+break in /home/indutny/Code/git/indutny/myscript.js:3
+  1 x = 5;
+  2 setTimeout(function () {
+  3   debugger;
+  4   console.log("world");
+  5 }, 1000);
+debug> next
+break in /home/indutny/Code/git/indutny/myscript.js:4
+  2 setTimeout(function () {
+  3   debugger;
+  4   console.log("world");
+  5 }, 1000);
+  6 console.log("hello");
+debug> repl
+Press Ctrl + C to leave debug repl
+> x
+5
+> 2+2
+4
+debug> next
+< world
+break in /home/indutny/Code/git/indutny/myscript.js:5
+  3   debugger;
+  4   console.log("world");
+  5 }, 1000);
+  6 console.log("hello");
+  7
+debug> quit
+%
+

The repl command allows you to evaluate code remotely. The next command +steps over to the next line. There are a few other commands available and more +to come. Type help to see others. + +

+

Watchers#

+

You can watch expression and variable values while debugging your code. +On every breakpoint each expression from the watchers list will be evaluated +in the current context and displayed just before the breakpoint's source code +listing. + +

+

To start watching an expression, type watch("my_expression"). watchers +prints the active watchers. To remove a watcher, type +unwatch("my_expression"). + +

+

Commands reference#

+

Stepping#

+
    +
  • cont, c - Continue execution
    • +
  • next, n - Step next
    • +
  • step, s - Step in
    • +
  • out, o - Step out
    • +
+

Breakpoints#

+
    +
  • setBreakpoint(), sb() - Set breakpoint on current line
    • +
  • setBreakpoint('fn()'), sb(...) - Set breakpoint on a first statement in +functions body
    • +
  • setBreakpoint('script.js', 1), sb(...) - Set breakpoint on first line of +script.js
    • +
  • clearBreakpoint, cb(...) - Clear breakpoint
    • +
+

Info#

+
    +
  • backtrace, bt - Print backtrace of current execution frame
    • +
  • list(5) - List scripts source code with 5 line context (5 lines before and +after)
    • +
  • watch(expr) - Add expression to watch list
    • +
  • unwatch(expr) - Remove expression from watch list
    • +
  • watchers - List all watchers and their values (automatically listed on each +breakpoint)
    • +
  • repl - Open debugger's repl for evaluation in debugging script's context
    • +
+

Execution control#

+
    +
  • run - Run script (automatically runs on debugger's start)
    • +
  • restart - Restart script
    • +
  • kill - Kill script
    • +
+

Various#

+
    +
  • scripts - List all loaded scripts
    • +
  • version - Display v8's version
    • +
+

Advanced Usage#

+

The V8 debugger can be enabled and accessed either by starting Node with +the --debug command-line flag or by signaling an existing Node process +with SIGUSR1. + +

+

Cluster#

+
Stability: 1 Experimental - Drastic changes in future versions
+

A single instance of Node runs in a single thread. To take advantage of +multi-core systems the user will sometimes want to launch a cluster of Node +processes to handle the load. + +

+

The cluster module allows you to easily create a network of processes that +all share server ports. + +

+
var cluster = require('cluster');
+var http = require('http');
+var numCPUs = require('os').cpus().length;
+
+if (cluster.isMaster) {
+  // Fork workers.
+  for (var i = 0; i < numCPUs; i++) {
+    cluster.fork();
+  }
+
+  cluster.on('death', function(worker) {
+    console.log('worker ' + worker.pid + ' died');
+  });
+} else {
+  // Worker processes have a http server.
+  http.Server(function(req, res) {
+    res.writeHead(200);
+    res.end("hello world\n");
+  }).listen(8000);
+}
+

Running node will now share port 8000 between the workers: + +

+
% node server.js
+Worker 2438 online
+Worker 2437 online
+

The difference between cluster.fork() and child_process.fork() is simply +that cluster allows TCP servers to be shared between workers. cluster.fork +is implemented on top of child_process.fork. The message passing API that +is available with child_process.fork is available with cluster as well. +As an example, here is a cluster which keeps count of the number of requests +in the master process via message passing: + +

+
var cluster = require('cluster');
+var http = require('http');
+var numReqs = 0;
+
+if (cluster.isMaster) {
+  // Fork workers.
+  for (var i = 0; i < 2; i++) {
+    var worker = cluster.fork();
+
+    worker.on('message', function(msg) {
+      if (msg.cmd && msg.cmd == 'notifyRequest') {
+        numReqs++;
+      }
+    });
+  }
+
+  setInterval(function() {
+    console.log("numReqs =", numReqs);
+  }, 1000);
+} else {
+  // Worker processes have a http server.
+  http.Server(function(req, res) {
+    res.writeHead(200);
+    res.end("hello world\n");
+    // Send message to master process
+    process.send({ cmd: 'notifyRequest' });
+  }).listen(8000);
+}
+

cluster.fork()#

+

Spawn a new worker process. This can only be called from the master process. + +

+

cluster.isMaster#

+

cluster.isWorker#

+

Boolean flags to determine if the current process is a master or a worker +process in a cluster. A process isMaster if process.env.NODE_WORKER_ID +is undefined. + +

+

Event: 'death'#

+

When any of the workers die the cluster module will emit the 'death' event. +This can be used to restart the worker by calling fork() again. + +

+
cluster.on('death', function(worker) {
+  console.log('worker ' + worker.pid + ' died. restart...');
+  cluster.fork();
+});
+

Different techniques can be used to restart the worker depending on the +application. + +

+

Appendix 1 - Third Party Modules#

+

There are many third party modules for Node. At the time of writing, August +2010, the master repository of modules is +the wiki page. + +

+

This appendix is intended as a SMALL guide to new-comers to help them +quickly find what are considered to be quality modules. It is not intended +to be a complete list. There may be better more complete modules found +elsewhere. + +

+ +

Patches to this list are welcome. + +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/index.html @@ -0,0 +1,127 @@ + + + + + Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + + +
+ + + + + + + + + + --- /dev/null +++ b/doc/api/vm.html @@ -0,0 +1,291 @@ + + + + + Executing JavaScript Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Executing JavaScript#

+
Stability: 3 - Stable
+ + +

You can access this module with: + +

+
var vm = require('vm');
+

JavaScript code can be compiled and run immediately or compiled, saved, and run later. + + +

+

vm.runInThisContext(code, [filename])#

+

vm.runInThisContext() compiles code, runs it and returns the result. Running +code does not have access to local scope. filename is optional, it's used only +in stack traces. + +

+

Example of using vm.runInThisContext and eval to run the same code: + +

+
var localVar = 123,
+    usingscript, evaled,
+    vm = require('vm');
+
+usingscript = vm.runInThisContext('localVar = 1;',
+  'myfile.vm');
+console.log('localVar: ' + localVar + ', usingscript: ' +
+  usingscript);
+evaled = eval('localVar = 1;');
+console.log('localVar: ' + localVar + ', evaled: ' +
+  evaled);
+
+// localVar: 123, usingscript: 1
+// localVar: 1, evaled: 1
+

vm.runInThisContext does not have access to the local scope, so localVar is unchanged. +eval does have access to the local scope, so localVar is changed. + +

+

In case of syntax error in code, vm.runInThisContext emits the syntax error to stderr +and throws an exception. + + +

+

vm.runInNewContext(code, [sandbox], [filename])#

+

vm.runInNewContext compiles code, then runs it in sandbox and returns the +result. Running code does not have access to local scope. The object sandbox +will be used as the global object for code. +sandbox and filename are optional, filename is only used in stack traces. + +

+

Example: compile and execute code that increments a global variable and sets a new one. +These globals are contained in the sandbox. + +

+
var util = require('util'),
+    vm = require('vm'),
+    sandbox = {
+      animal: 'cat',
+      count: 2
+    };
+
+vm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');
+console.log(util.inspect(sandbox));
+
+// { animal: 'cat', count: 3, name: 'kitty' }
+

Note that running untrusted code is a tricky business requiring great care. To prevent accidental +global variable leakage, vm.runInNewContext is quite useful, but safely running untrusted code +requires a separate process. + +

+

In case of syntax error in code, vm.runInNewContext emits the syntax error to stderr +and throws an exception. + +

+

vm.runInContext(code, context, [filename])#

+

vm.runInContext compiles code, then runs it in context and returns the +result. A (V8) context comprises a global object, together with a set of +built-in objects and functions. Running code does not have access to local scope +and the global object held within context will be used as the global object +for code. +filename is optional, it's used only in stack traces. + +

+

Example: compile and execute code in a existing context. + +

+
var util = require('util'),
+    vm = require('vm'),
+    initSandbox = {
+      animal: 'cat',
+      count: 2
+    },
+    context = vm.createContext(initSandbox);
+
+vm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');
+console.log(util.inspect(context));
+
+// { animal: 'cat', count: 3, name: 'CATT' }
+

Note that createContext will perform a shallow clone of the supplied sandbox object in order to +initialise the global object of the freshly constructed context. + +

+

Note that running untrusted code is a tricky business requiring great care. To prevent accidental +global variable leakage, vm.runInContext is quite useful, but safely running untrusted code +requires a separate process. + +

+

In case of syntax error in code, vm.runInContext emits the syntax error to stderr +and throws an exception. + +

+

vm.createContext([initSandbox])#

+

vm.createContext creates a new context which is suitable for use as the 2nd argument of a subsequent +call to vm.runInContext. A (V8) context comprises a global object together with a set of +build-in objects and functions. The optional argument initSandbox will be shallow-copied +to seed the initial contents of the global object used by the context. + +

+

vm.createScript(code, [filename])#

+

createScript compiles code but does not run it. Instead, it returns a +vm.Script object representing this compiled code. This script can be run +later many times using methods below. The returned script is not bound to any +global object. It is bound before each run, just for that run. filename is +optional, it's only used in stack traces. + +

+

In case of syntax error in code, createScript prints the syntax error to stderr +and throws an exception. + + +

+

Class: Script#

+

A class for running scripts. Returned by vm.createScript. + +

+

script.runInThisContext()#

+

Similar to vm.runInThisContext but a method of a precompiled Script object. +script.runInThisContext runs the code of script and returns the result. +Running code does not have access to local scope, but does have access to the global object +(v8: in actual context). + +

+

Example of using script.runInThisContext to compile code once and run it multiple times: + +

+
var vm = require('vm');
+
+globalVar = 0;
+
+var script = vm.createScript('globalVar += 1', 'myfile.vm');
+
+for (var i = 0; i < 1000 ; i += 1) {
+  script.runInThisContext();
+}
+
+console.log(globalVar);
+
+// 1000
+

script.runInNewContext([sandbox])#

+

Similar to vm.runInNewContext a method of a precompiled Script object. +script.runInNewContext runs the code of script with sandbox as the global object and returns the result. +Running code does not have access to local scope. sandbox is optional. + +

+

Example: compile code that increments a global variable and sets one, then execute this code multiple times. +These globals are contained in the sandbox. + +

+
var util = require('util'),
+    vm = require('vm'),
+    sandbox = {
+      animal: 'cat',
+      count: 2
+    };
+
+var script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');
+
+for (var i = 0; i < 10 ; i += 1) {
+  script.runInNewContext(sandbox);
+}
+
+console.log(util.inspect(sandbox));
+
+// { animal: 'cat', count: 12, name: 'kitty' }
+

Note that running untrusted code is a tricky business requiring great care. To prevent accidental +global variable leakage, script.runInNewContext is quite useful, but safely running untrusted code +requires a separate process. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/crypto.json @@ -0,0 +1,666 @@ +{ + "source": "doc/api/crypto.markdown", + "modules": [ + { + "textRaw": "Crypto", + "name": "crypto", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Use require('crypto') to access this module.\n\n

\n

The crypto module requires OpenSSL to be available on the underlying platform.\nIt offers a way of encapsulating secure credentials to be used as part\nof a secure HTTPS net or http connection.\n\n

\n

It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods.\n\n

\n", + "methods": [ + { + "textRaw": "crypto.createCredentials(details)", + "type": "method", + "name": "createCredentials", + "desc": "

Creates a credentials object, with the optional details being a dictionary with keys:\n\n

\n
    \n
  • pfx : A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
    • \n
  • key : a string holding the PEM encoded private key
    • \n
  • cert : a string holding the PEM encoded certificate
    • \n
  • passphrase : A string of passphrase for the private key or pfx
    • \n
  • ca : either a string or list of strings of PEM encoded CA certificates to trust.
    • \n
  • ciphers: a string describing the ciphers to use or exclude. Consult\nhttp://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details\non the format.
    • \n
\n

If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in\n

\n

http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "details" + } + ] + } + ] + }, + { + "textRaw": "crypto.createHash(algorithm)", + "type": "method", + "name": "createHash", + "desc": "

Creates and returns a hash object, a cryptographic hash with the given algorithm\nwhich can be used to generate hash digests.\n\n

\n

algorithm is dependent on the available algorithms supported by the version\nof OpenSSL on the platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', etc.\nOn recent releases, openssl list-message-digest-algorithms will display the available digest algorithms.\n\n

\n

Example: this program that takes the sha1 sum of a file\n\n

\n
var filename = process.argv[2];\nvar crypto = require('crypto');\nvar fs = require('fs');\n\nvar shasum = crypto.createHash('sha1');\n\nvar s = fs.ReadStream(filename);\ns.on('data', function(d) {\n  shasum.update(d);\n});\n\ns.on('end', function() {\n  var d = shasum.digest('hex');\n  console.log(d + '  ' + filename);\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + } + ] + } + ] + }, + { + "textRaw": "crypto.createHmac(algorithm, key)", + "type": "method", + "name": "createHmac", + "desc": "

Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key.\n\n

\n

algorithm is dependent on the available algorithms supported by OpenSSL - see createHash above.\nkey is the hmac key to be used.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + }, + { + "name": "key" + } + ] + } + ] + }, + { + "textRaw": "crypto.createCipher(algorithm, password)", + "type": "method", + "name": "createCipher", + "desc": "

Creates and returns a cipher object, with the given algorithm and password.\n\n

\n

algorithm is dependent on OpenSSL, examples are 'aes192', etc.\nOn recent releases, openssl list-cipher-algorithms will display the\navailable cipher algorithms.\npassword is used to derive key and IV, which must be 'binary' encoded\nstring (See the Buffer section for more information).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + }, + { + "name": "password" + } + ] + } + ] + }, + { + "textRaw": "crypto.createCipheriv(algorithm, key, iv)", + "type": "method", + "name": "createCipheriv", + "desc": "

Creates and returns a cipher object, with the given algorithm, key and iv.\n\n

\n

algorithm is the same as the createCipher(). key is a raw key used in\nalgorithm. iv is an Initialization vector. key and iv must be 'binary'\nencoded string (See the Buffer section for more information).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + }, + { + "name": "key" + }, + { + "name": "iv" + } + ] + } + ] + }, + { + "textRaw": "crypto.createDecipher(algorithm, password)", + "type": "method", + "name": "createDecipher", + "desc": "

Creates and returns a decipher object, with the given algorithm and key.\nThis is the mirror of the createCipher() above.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + }, + { + "name": "password" + } + ] + } + ] + }, + { + "textRaw": "crypto.createDecipheriv(algorithm, key, iv)", + "type": "method", + "name": "createDecipheriv", + "desc": "

Creates and returns a decipher object, with the given algorithm, key and iv.\nThis is the mirror of the createCipheriv() above.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + }, + { + "name": "key" + }, + { + "name": "iv" + } + ] + } + ] + }, + { + "textRaw": "crypto.createSign(algorithm)", + "type": "method", + "name": "createSign", + "desc": "

Creates and returns a signing object, with the given algorithm.\nOn recent OpenSSL releases, openssl list-public-key-algorithms will display\nthe available signing algorithms. Examples are 'RSA-SHA256'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + } + ] + } + ] + }, + { + "textRaw": "crypto.createVerify(algorithm)", + "type": "method", + "name": "createVerify", + "desc": "

Creates and returns a verification object, with the given algorithm.\nThis is the mirror of the signing object above.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "algorithm" + } + ] + } + ] + }, + { + "textRaw": "crypto.createDiffieHellman(prime_length)", + "type": "method", + "name": "createDiffieHellman", + "desc": "

Creates a Diffie-Hellman key exchange object and generates a prime of the\ngiven bit length. The generator used is 2.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "prime_length" + } + ] + } + ] + }, + { + "textRaw": "crypto.createDiffieHellman(prime, [encoding])", + "type": "method", + "name": "createDiffieHellman", + "desc": "

Creates a Diffie-Hellman key exchange object using the supplied prime. The\ngenerator used is 2. Encoding can be 'binary', 'hex', or 'base64'.\nDefaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "prime" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "crypto.pbkdf2(password, salt, iterations, keylen, callback)", + "type": "method", + "name": "pbkdf2", + "desc": "

Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive\na key of given length from the given password, salt and iterations.\nThe callback gets two arguments (err, derivedKey).\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "password" + }, + { + "name": "salt" + }, + { + "name": "iterations" + }, + { + "name": "keylen" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "crypto.randomBytes(size, [callback])", + "type": "method", + "name": "randomBytes", + "desc": "

Generates cryptographically strong pseudo-random data. Usage:\n\n

\n
// async\ncrypto.randomBytes(256, function(ex, buf) {\n  if (ex) throw ex;\n  console.log('Have %d bytes of random data: %s', buf.length, buf);\n});\n\n// sync\ntry {\n  var buf = crypto.randomBytes(256);\n  console.log('Have %d bytes of random data: %s', buf.length, buf);\n} catch (ex) {\n  // handle error\n}
\n", + "signatures": [ + { + "params": [ + { + "name": "size" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: Hash", + "type": "class", + "name": "Hash", + "desc": "

The class for creating hash digests of data.\n\n

\n

Returned by crypto.createHash.\n\n

\n", + "methods": [ + { + "textRaw": "hash.update(data, [input_encoding])", + "type": "method", + "name": "update", + "desc": "

Updates the hash content with the given data, the encoding of which is given\nin input_encoding and can be 'utf8', 'ascii' or 'binary'.\nDefaults to 'binary'.\nThis can be called many times with new data as it is streamed.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + }, + { + "name": "input_encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "hash.digest([encoding])", + "type": "method", + "name": "digest", + "desc": "

Calculates the digest of all of the passed data to be hashed.\nThe encoding can be 'hex', 'binary' or 'base64'.\nDefaults to 'binary'.\n\n

\n

Note: hash object can not be used after digest() method been called.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: Hmac", + "type": "class", + "name": "Hmac", + "desc": "

Class for creating cryptographic hmac content.\n\n

\n

Returned by crypto.createHmac.\n\n

\n", + "methods": [ + { + "textRaw": "hmac.update(data)", + "type": "method", + "name": "update", + "desc": "

Update the hmac content with the given data.\nThis can be called many times with new data as it is streamed.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + } + ] + } + ] + }, + { + "textRaw": "hmac.digest([encoding])", + "type": "method", + "name": "digest", + "desc": "

Calculates the digest of all of the passed data to the hmac.\nThe encoding can be 'hex', 'binary' or 'base64'.\nDefaults to 'binary'.\n\n

\n

Note: hmac object can not be used after digest() method been called.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: Cipher", + "type": "class", + "name": "Cipher", + "desc": "

Class for encrypting data.\n\n

\n

Returned by crypto.createCipher and crypto.createCipheriv.\n\n

\n", + "methods": [ + { + "textRaw": "cipher.update(data, [input_encoding], [output_encoding])", + "type": "method", + "name": "update", + "desc": "

Updates the cipher with data, the encoding of which is given in\ninput_encoding and can be 'utf8', 'ascii' or 'binary'.\nDefaults to 'binary'.\n\n

\n

The output_encoding specifies the output format of the enciphered data,\nand can be 'binary', 'base64' or 'hex'. Defaults to 'binary'.\n\n

\n

Returns the enciphered contents, and can be called many times with new data as it is streamed.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + }, + { + "name": "input_encoding", + "optional": true + }, + { + "name": "output_encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "cipher.final([output_encoding])", + "type": "method", + "name": "final", + "desc": "

Returns any remaining enciphered contents, with output_encoding being one of:\n'binary', 'base64' or 'hex'. Defaults to 'binary'.\n\n

\n

Note: cipher object can not be used after final() method been called.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "output_encoding", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: Decipher", + "type": "class", + "name": "Decipher", + "desc": "

Class for decrypting data.\n\n

\n

Returned by crypto.createDecipher and crypto.createDecipheriv.\n\n

\n", + "methods": [ + { + "textRaw": "decipher.update(data, [input_encoding], [output_encoding])", + "type": "method", + "name": "update", + "desc": "

Updates the decipher with data, which is encoded in 'binary', 'base64'\nor 'hex'. Defaults to 'binary'.\n\n

\n

The output_decoding specifies in what format to return the deciphered\nplaintext: 'binary', 'ascii' or 'utf8'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + }, + { + "name": "input_encoding", + "optional": true + }, + { + "name": "output_encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "decipher.final([output_encoding])", + "type": "method", + "name": "final", + "desc": "

Returns any remaining plaintext which is deciphered,\nwith output_encoding being one of: 'binary', 'ascii' or 'utf8'.\nDefaults to 'binary'.\n\n

\n

Note: decipher object can not be used after final() method been called.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "output_encoding", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: Signer", + "type": "class", + "name": "Signer", + "desc": "

Class for generating signatures.\n\n

\n

Returned by crypto.createSign.\n\n

\n", + "methods": [ + { + "textRaw": "signer.update(data)", + "type": "method", + "name": "update", + "desc": "

Updates the signer object with data.\nThis can be called many times with new data as it is streamed.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + } + ] + } + ] + }, + { + "textRaw": "signer.sign(private_key, [output_format])", + "type": "method", + "name": "sign", + "desc": "

Calculates the signature on all the updated data passed through the signer.\nprivate_key is a string containing the PEM encoded private key for signing.\n\n

\n

Returns the signature in output_format which can be 'binary', 'hex' or\n'base64'. Defaults to 'binary'.\n\n

\n

Note: signer object can not be used after sign() method been called.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "private_key" + }, + { + "name": "output_format", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: Verify", + "type": "class", + "name": "Verify", + "desc": "

Class for verifying signatures.\n\n

\n

Returned by crypto.createVerify.\n\n

\n", + "methods": [ + { + "textRaw": "verifier.update(data)", + "type": "method", + "name": "update", + "desc": "

Updates the verifier object with data.\nThis can be called many times with new data as it is streamed.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data" + } + ] + } + ] + }, + { + "textRaw": "verifier.verify(object, signature, [signature_format])", + "type": "method", + "name": "verify", + "desc": "

Verifies the signed data by using the object and signature. object is a\nstring containing a PEM encoded object, which can be one of RSA public key,\nDSA public key, or X.509 certificate. signature is the previously calculated\nsignature for the data, in the signature_format which can be 'binary',\n'hex' or 'base64'. Defaults to 'binary'.\n\n

\n

Returns true or false depending on the validity of the signature for the data and public key.\n\n

\n

Note: verifier object can not be used after verify() method been called.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "object" + }, + { + "name": "signature" + }, + { + "name": "signature_format", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Class: DiffieHellman", + "type": "class", + "name": "DiffieHellman", + "desc": "

The class for creating Diffie-Hellman key exchanges.\n\n

\n

Returned by crypto.createDiffieHellman.\n\n

\n", + "methods": [ + { + "textRaw": "diffieHellman.generateKeys([encoding])", + "type": "method", + "name": "generateKeys", + "desc": "

Generates private and public Diffie-Hellman key values, and returns the\npublic key in the specified encoding. This key should be transferred to the\nother party. Encoding can be 'binary', 'hex', or 'base64'.\nDefaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])", + "type": "method", + "name": "computeSecret", + "desc": "

Computes the shared secret using other_public_key as the other party's\npublic key and returns the computed shared secret. Supplied key is\ninterpreted using specified input_encoding, and secret is encoded using\nspecified output_encoding. Encodings can be 'binary', 'hex', or\n'base64'. The input encoding defaults to 'binary'.\nIf no output encoding is given, the input encoding is used as output encoding.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "other_public_key" + }, + { + "name": "input_encoding", + "optional": true + }, + { + "name": "output_encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.getPrime([encoding])", + "type": "method", + "name": "getPrime", + "desc": "

Returns the Diffie-Hellman prime in the specified encoding, which can be\n'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.getGenerator([encoding])", + "type": "method", + "name": "getGenerator", + "desc": "

Returns the Diffie-Hellman prime in the specified encoding, which can be\n'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.getPublicKey([encoding])", + "type": "method", + "name": "getPublicKey", + "desc": "

Returns the Diffie-Hellman public key in the specified encoding, which can\nbe 'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.getPrivateKey([encoding])", + "type": "method", + "name": "getPrivateKey", + "desc": "

Returns the Diffie-Hellman private key in the specified encoding, which can\nbe 'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.setPublicKey(public_key, [encoding])", + "type": "method", + "name": "setPublicKey", + "desc": "

Sets the Diffie-Hellman public key. Key encoding can be 'binary', 'hex',\nor 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "public_key" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "diffieHellman.setPrivateKey(public_key, [encoding])", + "type": "method", + "name": "setPrivateKey", + "desc": "

Sets the Diffie-Hellman private key. Key encoding can be 'binary', 'hex',\nor 'base64'. Defaults to 'binary'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "public_key" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + } + ] + } + ], + "type": "module", + "displayName": "Crypto" + } + ] +} --- /dev/null +++ b/doc/api/util.html @@ -0,0 +1,271 @@ + + + + + util Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

util#

+
Stability: 5 - Locked
+

These functions are in the module 'util'. Use require('util') to access +them. + + +

+

util.format()#

+

Returns a formatted string using the first argument as a printf-like format. + +

+

The first argument is a string that contains zero or more placeholders. +Each placeholder is replaced with the converted value from its corresponding +argument. Supported placeholders are: + +

+
    +
  • %s - String.
    • +
  • %d - Number (both integer and float).
    • +
  • %j - JSON.
    • +
  • %% - single percent sign ('%'). This does not consume an argument.
    • +
+

If the placeholder does not have a corresponding argument, the placeholder is +not replaced. + +

+
util.format('%s:%s', 'foo'); // 'foo:%s'
+

If there are more arguments than placeholders, the extra arguments are +converted to strings with util.inspect() and these strings are concatenated, +delimited by a space. + +

+
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
+

If the first argument is not a format string then util.format() returns +a string that is the concatenation of all its arguments separated by spaces. +Each argument is converted to a string with util.inspect(). + +

+
util.format(1, 2, 3); // '1 2 3'
+

util.debug(string)#

+

A synchronous output function. Will block the process and +output string immediately to stderr. + +

+
require('util').debug('message on stderr');
+

util.log(string)#

+

Output with timestamp on stdout. + +

+
require('util').log('Timestamped message.');
+

util.inspect(object, [showHidden], [depth], [colors])#

+

Return a string representation of object, which is useful for debugging. + +

+

If showHidden is true, then the object's non-enumerable properties will be +shown too. Defaults to false. + +

+

If depth is provided, it tells inspect how many times to recurse while +formatting the object. This is useful for inspecting large complicated objects. + +

+

The default is to only recurse twice. To make it recurse indefinitely, pass +in null for depth. + +

+

If colors is true, the output will be styled with ANSI color codes. +Defaults to false. + +

+

Example of inspecting all properties of the util object: + +

+
var util = require('util');
+
+console.log(util.inspect(util, true, null));
+

util.isArray(object)#

+

Returns true if the given "object" is an Array. false otherwise. + +

+
var util = require('util');
+
+util.isArray([])
+  // true
+util.isArray(new Array)
+  // true
+util.isArray({})
+  // false
+

util.isRegExp(object)#

+

Returns true if the given "object" is a RegExp. false otherwise. + +

+
var util = require('util');
+
+util.isRegExp(/some regexp/)
+  // true
+util.isRegExp(new RegExp('another regexp'))
+  // true
+util.isRegExp({})
+  // false
+

util.isDate(object)#

+

Returns true if the given "object" is a Date. false otherwise. + +

+
var util = require('util');
+
+util.isDate(new Date())
+  // true
+util.isDate(Date())
+  // false (without 'new' returns a String)
+util.isDate({})
+  // false
+

util.isError(object)#

+

Returns true if the given "object" is an Error. false otherwise. + +

+
var util = require('util');
+
+util.isError(new Error())
+  // true
+util.isError(new TypeError())
+  // true
+util.isError({ name: 'Error', message: 'an error occurred' })
+  // false
+

util.pump(readableStream, writableStream, [callback])#

+

Experimental + +

+

Read the data from readableStream and send it to the writableStream. +When writableStream.write(data) returns false readableStream will be +paused until the drain event occurs on the writableStream. callback gets +an error as its only argument and is called when writableStream is closed or +when an error occurs. + + +

+

util.inherits(constructor, superConstructor)#

+

Inherit the prototype methods from one +constructor +into another. The prototype of constructor will be set to a new +object created from superConstructor. + +

+

As an additional convenience, superConstructor will be accessible +through the constructor.super_ property. + +

+
var util = require("util");
+var events = require("events");
+
+function MyStream() {
+    events.EventEmitter.call(this);
+}
+
+util.inherits(MyStream, events.EventEmitter);
+
+MyStream.prototype.write = function(data) {
+    this.emit("data", data);
+}
+
+var stream = new MyStream();
+
+console.log(stream instanceof events.EventEmitter); // true
+console.log(MyStream.super_ === events.EventEmitter); // true
+
+stream.on("data", function(data) {
+    console.log('Received data: "' + data + '"');
+})
+stream.write("It works!"); // Received data: "It works!"
+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/http.json @@ -0,0 +1,699 @@ +{ + "source": "doc/api/http.markdown", + "modules": [ + { + "textRaw": "HTTP", + "name": "http", + "stability": 3, + "stabilityText": "Stable", + "desc": "

To use the HTTP server and client one must require('http').\n\n

\n

The HTTP interfaces in Node are designed to support many features\nof the protocol which have been traditionally difficult to use.\nIn particular, large, possibly chunk-encoded, messages. The interface is\ncareful to never buffer entire requests or responses--the\nuser is able to stream data.\n\n

\n

HTTP message headers are represented by an object like this:\n\n

\n
{ 'content-length': '123',\n  'content-type': 'text/plain',\n  'connection': 'keep-alive',\n  'accept': '*/*' }
\n

Keys are lowercased. Values are not modified.\n\n

\n

In order to support the full spectrum of possible HTTP applications, Node's\nHTTP API is very low-level. It deals with stream handling and message\nparsing only. It parses a message into headers and body but it does not\nparse the actual headers or the body.\n\n\n

\n", + "methods": [ + { + "textRaw": "http.createServer([requestListener])", + "type": "method", + "name": "createServer", + "desc": "

Returns a new web server object.\n\n

\n

The requestListener is a function which is automatically\nadded to the 'request' event.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "requestListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "http.request(options, callback)", + "type": "method", + "name": "request", + "desc": "

Node maintains several connections per server to make HTTP requests.\nThis function allows one to transparently issue requests. options align\nwith url.parse().\n\n

\n

Options:\n\n

\n
    \n
  • host: A domain name or IP address of the server to issue the request to.\nDefaults to 'localhost'.
    • \n
  • hostname: To support url.parse() hostname is preferred over host
    • \n
  • port: Port of remote server. Defaults to 80.
    • \n
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • \n
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • \n
  • path: Request path. Defaults to '/'. Should include query string if any.\nE.G. '/index.html?page=12'
    • \n
  • headers: An object containing request headers.
    • \n
  • auth: Basic authentication i.e. 'user:password' to compute an\nAuthorization header.
    • \n
  • agent: Controls Agent behavior. When an Agent is used\nrequest will default to Connection: keep-alive. Possible values:
      \n
    • undefined (default): use global Agent for this host\nand port.
      • \n
    • Agent object: explicitly use the passed in Agent.
      • \n
    • false: opts out of connection pooling with an Agent, defaults request to\nConnection: close.
      • \n
    \n
    • \n
\n

http.request() returns an instance of the http.ClientRequest\nclass. The ClientRequest instance is a writable stream. If one needs to\nupload a file with a POST request, then write to the ClientRequest object.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'www.google.com',\n  port: 80,\n  path: '/upload',\n  method: 'POST'\n};\n\nvar req = http.request(options, function(res) {\n  console.log('STATUS: ' + res.statusCode);\n  console.log('HEADERS: ' + JSON.stringify(res.headers));\n  res.setEncoding('utf8');\n  res.on('data', function (chunk) {\n    console.log('BODY: ' + chunk);\n  });\n});\n\nreq.on('error', function(e) {\n  console.log('problem with request: ' + e.message);\n});\n\n// write data to request body\nreq.write('data\\n');\nreq.write('data\\n');\nreq.end();
\n

Note that in the example req.end() was called. With http.request() one\nmust always call req.end() to signify that you're done with the request -\neven if there is no data being written to the request body.\n\n

\n

If any error is encountered during the request (be that with DNS resolution,\nTCP level errors, or actual HTTP parse errors) an 'error' event is emitted\non the returned request object.\n\n

\n

There are a few special headers that should be noted.\n\n

\n
    \n

  • Sending a 'Connection: keep-alive' will notify Node that the connection to\nthe server should be persisted until the next request.

    \n
    • \n

  • Sending a 'Content-length' header will disable the default chunked encoding.

    \n
    • \n

  • Sending an 'Expect' header will immediately send the request headers.\nUsually, when sending 'Expect: 100-continue', you should both set a timeout\nand listen for the continue event. See RFC2616 Section 8.2.3 for more\ninformation.

    \n
    • \n

  • Sending an Authorization header will override using the auth option\nto compute basic authentication.

    \n
    • \n
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "http.get(options, callback)", + "type": "method", + "name": "get", + "desc": "

Since most requests are GET requests without bodies, Node provides this\nconvenience method. The only difference between this method and http.request() is\nthat it sets the method to GET and calls req.end() automatically.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'www.google.com',\n  port: 80,\n  path: '/index.html'\n};\n\nhttp.get(options, function(res) {\n  console.log("Got response: " + res.statusCode);\n}).on('error', function(e) {\n  console.log("Got error: " + e.message);\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "callback" + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: http.Server", + "type": "class", + "name": "http.Server", + "desc": "

This is an EventEmitter with the following events:\n\n

\n", + "events": [ + { + "textRaw": "Event: 'request'", + "type": "event", + "name": "request", + "desc": "

function (request, response) { }\n\n

\n

Emitted each time there is a request. Note that there may be multiple requests\nper connection (in the case of keep-alive connections).\n request is an instance of http.ServerRequest and response is\n an instance of http.ServerResponse\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'connection'", + "type": "event", + "name": "connection", + "desc": "

function (socket) { }\n\n

\n

When a new TCP stream is established. socket is an object of type\n net.Socket. Usually users will not want to access this event. The\n socket can also be accessed at request.connection.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () { }\n\n

\n

Emitted when the server closes.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'checkContinue'", + "type": "event", + "name": "checkContinue", + "desc": "

function (request, response) { }\n\n

\n

Emitted each time a request with an http Expect: 100-continue is received.\nIf this event isn't listened for, the server will automatically respond\nwith a 100 Continue as appropriate.\n\n

\n

Handling this event involves calling response.writeContinue if the client\nshould continue to send the request body, or generating an appropriate HTTP\nresponse (e.g., 400 Bad Request) if the client should not continue to send the\nrequest body.\n\n

\n

Note that when this event is emitted and handled, the request event will\nnot be emitted.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'upgrade'", + "type": "event", + "name": "upgrade", + "desc": "

function (request, socket, head) { }\n\n

\n

Emitted each time a client requests a http upgrade. If this event isn't\nlistened for, then clients requesting an upgrade will have their connections\nclosed.\n\n

\n
    \n
  • request is the arguments for the http request, as it is in the request event.
    • \n
  • socket is the network socket between the server and client.
    • \n
  • head is an instance of Buffer, the first packet of the upgraded stream, this may be empty.
    • \n
\n

After this event is emitted, the request's socket will not have a data\nevent listener, meaning you will need to bind to it in order to handle data\nsent to the server on that socket.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'clientError'", + "type": "event", + "name": "clientError", + "desc": "

function (exception) { }\n\n

\n

If a client connection emits an 'error' event - it will forwarded here.\n\n

\n", + "params": [] + } + ], + "methods": [ + { + "textRaw": "server.listen(port, [hostname], [callback])", + "type": "method", + "name": "listen", + "desc": "

Begin accepting connections on the specified port and hostname. If the\nhostname is omitted, the server will accept connections directed to any\nIPv4 address (INADDR_ANY).\n\n

\n

To listen to a unix socket, supply a filename instead of port and hostname.\n\n

\n

This function is asynchronous. The last parameter callback will be added as\na listener for the 'listening' event.\nSee also net.Server.listen().\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "port" + }, + { + "name": "hostname", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "server.listen(path, [callback])", + "type": "method", + "name": "listen", + "desc": "

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

\n

This function is asynchronous. The last parameter callback will be added as\na listener for the 'listening' event.\nSee also net.Server.listen().\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "path" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "server.close()", + "type": "method", + "name": "close", + "desc": "

Stops the server from accepting new connections.\nSee net.Server.close().\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + }, + { + "textRaw": "Class: http.ServerRequest", + "type": "class", + "name": "http.ServerRequest", + "desc": "

This object is created internally by a HTTP server -- not by\nthe user -- and passed as the first argument to a 'request' listener.\n\n

\n

The request implements the Readable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", + "events": [ + { + "textRaw": "Event: 'data'", + "type": "event", + "name": "data", + "desc": "

function (chunk) { }\n\n

\n

Emitted when a piece of the message body is received. The chunk is a string if\nan encoding has been set with request.setEncoding(), otherwise it's a\nBuffer.\n\n

\n

Note that the data will be lost if there is no listener when a\nServerRequest emits a 'data' event.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'end'", + "type": "event", + "name": "end", + "desc": "

function () { }\n\n

\n

Emitted exactly once for each request. After that, no more 'data' events\nwill be emitted on the request.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () { }\n\n

\n

Indicates that the underlaying connection was terminated before\nresponse.end() was called or able to flush.\n\n

\n

Just like 'end', this event occurs only once per request, and no more 'data'\nevents will fire afterwards.\n\n

\n

Note: 'close' can fire after 'end', but not vice versa.\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "request.method", + "name": "method", + "desc": "

The request method as a string. Read only. Example:\n'GET', 'DELETE'.\n\n\n

\n" + }, + { + "textRaw": "request.url", + "name": "url", + "desc": "

Request URL string. This contains only the URL that is\npresent in the actual HTTP request. If the request is:\n\n

\n
GET /status?name=ryan HTTP/1.1\\r\\n\nAccept: text/plain\\r\\n\n\\r\\n
\n

Then request.url will be:\n\n

\n
'/status?name=ryan'
\n

If you would like to parse the URL into its parts, you can use\nrequire('url').parse(request.url). Example:\n\n

\n
node> require('url').parse('/status?name=ryan')\n{ href: '/status?name=ryan',\n  search: '?name=ryan',\n  query: 'name=ryan',\n  pathname: '/status' }
\n

If you would like to extract the params from the query string,\nyou can use the require('querystring').parse function, or pass\ntrue as the second argument to require('url').parse. Example:\n\n

\n
node> require('url').parse('/status?name=ryan', true)\n{ href: '/status?name=ryan',\n  search: '?name=ryan',\n  query: { name: 'ryan' },\n  pathname: '/status' }
\n" + }, + { + "textRaw": "request.headers", + "name": "headers", + "desc": "

Read only.\n\n

\n" + }, + { + "textRaw": "request.trailers", + "name": "trailers", + "desc": "

Read only; HTTP trailers (if present). Only populated after the 'end' event.\n\n

\n" + }, + { + "textRaw": "request.httpVersion", + "name": "httpVersion", + "desc": "

The HTTP protocol version as a string. Read only. Examples:\n'1.1', '1.0'.\nAlso request.httpVersionMajor is the first integer and\nrequest.httpVersionMinor is the second.\n\n\n

\n" + }, + { + "textRaw": "request.connection", + "name": "connection", + "desc": "

The net.Socket object associated with the connection.\n\n\n

\n

With HTTPS support, use request.connection.verifyPeer() and\nrequest.connection.getPeerCertificate() to obtain the client's\nauthentication details.\n\n\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "request.setEncoding([encoding])", + "type": "method", + "name": "setEncoding", + "desc": "

Set the encoding for the request body. Either 'utf8' or 'binary'. Defaults\nto null, which means that the 'data' event will emit a Buffer object..\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "request.pause()", + "type": "method", + "name": "pause", + "desc": "

Pauses request from emitting events. Useful to throttle back an upload.\n\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "request.resume()", + "type": "method", + "name": "resume", + "desc": "

Resumes a paused request.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + }, + { + "textRaw": "Class: http.ServerResponse", + "type": "class", + "name": "http.ServerResponse", + "desc": "

This object is created internally by a HTTP server--not by the user. It is\npassed as the second parameter to the 'request' event.\n\n

\n

The response implements the Writable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", + "events": [ + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () { }\n\n

\n

Indicates that the underlaying connection was terminated before\nresponse.end() was called or able to flush.\n\n

\n", + "params": [] + } + ], + "methods": [ + { + "textRaw": "response.writeContinue()", + "type": "method", + "name": "writeContinue", + "desc": "

Sends a HTTP/1.1 100 Continue message to the client, indicating that\nthe request body should be sent. See the checkContinue event on\nServer.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "response.writeHead(statusCode, [reasonPhrase], [headers])", + "type": "method", + "name": "writeHead", + "desc": "

Sends a response header to the request. The status code is a 3-digit HTTP\nstatus code, like 404. The last argument, headers, are the response headers.\nOptionally one can give a human-readable reasonPhrase as the second\nargument.\n\n

\n

Example:\n\n

\n
var body = 'hello world';\nresponse.writeHead(200, {\n  'Content-Length': body.length,\n  'Content-Type': 'text/plain' });
\n

This method must only be called once on a message and it must\nbe called before response.end() is called.\n\n

\n

If you call response.write() or response.end() before calling this, the\nimplicit/mutable headers will be calculated and call this function for you.\n\n

\n

Note: that Content-Length is given in bytes not characters. The above example\nworks because the string 'hello world' contains only single byte characters.\nIf the body contains higher coded characters then Buffer.byteLength()\nshould be used to determine the number of bytes in a given encoding.\nAnd Node does not check whether Content-Length and the length of the body\nwhich has been transmitted are equal or not.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "statusCode" + }, + { + "name": "reasonPhrase", + "optional": true + }, + { + "name": "headers", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "response.setHeader(name, value)", + "type": "method", + "name": "setHeader", + "desc": "

Sets a single header value for implicit headers. If this header already exists\nin the to-be-sent headers, its value will be replaced. Use an array of strings\nhere if you need to send multiple headers with the same name.\n\n

\n

Example:\n\n

\n
response.setHeader("Content-Type", "text/html");
\n

or\n\n

\n
response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]);
\n", + "signatures": [ + { + "params": [ + { + "name": "name" + }, + { + "name": "value" + } + ] + } + ] + }, + { + "textRaw": "response.getHeader(name)", + "type": "method", + "name": "getHeader", + "desc": "

Reads out a header that's already been queued but not sent to the client. Note\nthat the name is case insensitive. This can only be called before headers get\nimplicitly flushed.\n\n

\n

Example:\n\n

\n
var contentType = response.getHeader('content-type');
\n", + "signatures": [ + { + "params": [ + { + "name": "name" + } + ] + } + ] + }, + { + "textRaw": "response.removeHeader(name)", + "type": "method", + "name": "removeHeader", + "desc": "

Removes a header that's queued for implicit sending.\n\n

\n

Example:\n\n

\n
response.removeHeader("Content-Encoding");
\n", + "signatures": [ + { + "params": [ + { + "name": "name" + } + ] + } + ] + }, + { + "textRaw": "response.write(chunk, [encoding])", + "type": "method", + "name": "write", + "desc": "

If this method is called and response.writeHead() has not been called, it will\nswitch to implicit header mode and flush the implicit headers.\n\n

\n

This sends a chunk of the response body. This method may\nbe called multiple times to provide successive parts of the body.\n\n

\n

chunk can be a string or a buffer. If chunk is a string,\nthe second parameter specifies how to encode it into a byte stream.\nBy default the encoding is 'utf8'.\n\n

\n

Note: This is the raw HTTP body and has nothing to do with\nhigher-level multi-part body encodings that may be used.\n\n

\n

The first time response.write() is called, it will send the buffered\nheader information and the first body to the client. The second time\nresponse.write() is called, Node assumes you're going to be streaming\ndata, and sends that separately. That is, the response is buffered up to the\nfirst chunk of body.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "chunk" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "response.addTrailers(headers)", + "type": "method", + "name": "addTrailers", + "desc": "

This method adds HTTP trailing headers (a header but at the end of the\nmessage) to the response.\n\n

\n

Trailers will only be emitted if chunked encoding is used for the\nresponse; if it is not (e.g., if the request was HTTP/1.0), they will\nbe silently discarded.\n\n

\n

Note that HTTP requires the Trailer header to be sent if you intend to\nemit trailers, with a list of the header fields in its value. E.g.,\n\n

\n
response.writeHead(200, { 'Content-Type': 'text/plain',\n                          'Trailer': 'Content-MD5' });\nresponse.write(fileData);\nresponse.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});\nresponse.end();
\n", + "signatures": [ + { + "params": [ + { + "name": "headers" + } + ] + } + ] + }, + { + "textRaw": "response.end([data], [encoding])", + "type": "method", + "name": "end", + "desc": "

This method signals to the server that all of the response headers and body\nhas been sent; that server should consider this message complete.\nThe method, response.end(), MUST be called on each\nresponse.\n\n

\n

If data is specified, it is equivalent to calling response.write(data, encoding)\nfollowed by response.end().\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data", + "optional": true + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + } + ], + "properties": [ + { + "textRaw": "response.statusCode", + "name": "statusCode", + "desc": "

When using implicit headers (not calling response.writeHead() explicitly), this property\ncontrols the status code that will be send to the client when the headers get\nflushed.\n\n

\n

Example:\n\n

\n
response.statusCode = 404;
\n

After response header was sent to the client, this property indicates the\nstatus code which was sent out.\n\n

\n" + } + ] + }, + { + "textRaw": "Class: http.Agent", + "type": "class", + "name": "http.Agent", + "desc": "

In node 0.5.3+ there is a new implementation of the HTTP Agent which is used\nfor pooling sockets used in HTTP client requests.\n\n

\n

Previously, a single agent instance help the pool for single host+port. The\ncurrent implementation now holds sockets for any number of hosts.\n\n

\n

The current HTTP Agent also defaults client requests to using\nConnection:keep-alive. If no pending HTTP requests are waiting on a socket\nto become free the socket is closed. This means that node's pool has the\nbenefit of keep-alive when under load but still does not require developers\nto manually close the HTTP clients using keep-alive.\n\n

\n

Sockets are removed from the agent's pool when the socket emits either a\n"close" event or a special "agentRemove" event. This means that if you intend\nto keep one HTTP request open for a long time and don't want it to stay in the\npool you can do something along the lines of:\n\n

\n
http.get(options, function(res) {\n  // Do stuff\n}).on("socket", function (socket) {\n  socket.emit("agentRemove");\n});
\n

Alternatively, you could just opt out of pooling entirely using agent:false:\n\n

\n
http.get({host:'localhost', port:80, path:'/', agent:false}, function (res) {\n  // Do stuff\n})
\n", + "properties": [ + { + "textRaw": "agent.maxSockets", + "name": "maxSockets", + "desc": "

By default set to 5. Determines how many concurrent sockets the agent can have \nopen per host.\n\n

\n" + }, + { + "textRaw": "agent.sockets", + "name": "sockets", + "desc": "

An object which contains arrays of sockets currently in use by the Agent. Do not \nmodify.\n\n

\n" + }, + { + "textRaw": "agent.requests", + "name": "requests", + "desc": "

An object which contains queues of requests that have not yet been assigned to \nsockets. Do not modify.\n\n

\n" + } + ] + }, + { + "textRaw": "Class: http.ClientRequest", + "type": "class", + "name": "http.ClientRequest", + "desc": "

This object is created internally and returned from http.request(). It\nrepresents an in-progress request whose header has already been queued. The\nheader is still mutable using the setHeader(name, value), getHeader(name),\nremoveHeader(name) API. The actual header will be sent along with the first\ndata chunk or when closing the connection.\n\n

\n

To get the response, add a listener for 'response' to the request object.\n'response' will be emitted from the request object when the response\nheaders have been received. The 'response' event is executed with one\nargument which is an instance of http.ClientResponse.\n\n

\n

During the 'response' event, one can add listeners to the\nresponse object; particularly to listen for the 'data' event. Note that\nthe 'response' event is called before any part of the response body is received,\nso there is no need to worry about racing to catch the first part of the\nbody. As long as a listener for 'data' is added during the 'response'\nevent, the entire body will be caught.\n\n\n

\n
// Good\nrequest.on('response', function (response) {\n  response.on('data', function (chunk) {\n    console.log('BODY: ' + chunk);\n  });\n});\n\n// Bad - misses all or part of the body\nrequest.on('response', function (response) {\n  setTimeout(function () {\n    response.on('data', function (chunk) {\n      console.log('BODY: ' + chunk);\n    });\n  }, 10);\n});
\n

Note: Node does not check whether Content-Length and the length of the body\nwhich has been transmitted are equal or not.\n\n

\n

The request implements the Writable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", + "events": [ + { + "textRaw": "Event 'response'", + "type": "event", + "name": "response", + "desc": "

function (response) { }\n\n

\n

Emitted when a response is received to this request. This event is emitted only once. The\nresponse argument will be an instance of http.ClientResponse.\n\n

\n

Options:\n\n

\n
    \n
  • host: A domain name or IP address of the server to issue the request to.
    • \n
  • port: Port of remote server.
    • \n
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • \n
\n", + "params": [] + }, + { + "textRaw": "Event: 'socket'", + "type": "event", + "name": "socket", + "desc": "

function (socket) { }\n\n

\n

Emitted after a socket is assigned to this request.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'upgrade'", + "type": "event", + "name": "upgrade", + "desc": "

function (response, socket, head) { }\n\n

\n

Emitted each time a server responds to a request with an upgrade. If this\nevent isn't being listened for, clients receiving an upgrade header will have\ntheir connections closed.\n\n

\n

A client server pair that show you how to listen for the upgrade event using http.getAgent:\n\n

\n
var http = require('http');\nvar net = require('net');\n\n// Create an HTTP server\nvar srv = http.createServer(function (req, res) {\n  res.writeHead(200, {'Content-Type': 'text/plain'});\n  res.end('okay');\n});\nsrv.on('upgrade', function(req, socket, upgradeHead) {\n  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\\r\\n' +\n               'Upgrade: WebSocket\\r\\n' +\n               'Connection: Upgrade\\r\\n' +\n               '\\r\\n\\r\\n');\n\n  socket.ondata = function(data, start, end) {\n    socket.write(data.toString('utf8', start, end), 'utf8'); // echo back\n  };\n});\n\n// now that server is running\nsrv.listen(1337, '127.0.0.1', function() {\n\n  // make a request\n  var options = {\n    port: 1337,\n    host: '127.0.0.1',\n    headers: {\n      'Connection': 'Upgrade',\n      'Upgrade': 'websocket'\n    }\n  };\n\n  var req = http.request(options);\n  req.end();\n\n  req.on('upgrade', function(res, socket, upgradeHead) {\n    console.log('got upgraded!');\n    socket.end();\n    process.exit(0);\n  });\n});
\n", + "params": [] + }, + { + "textRaw": "Event: 'continue'", + "type": "event", + "name": "continue", + "desc": "

function () { }\n\n

\n

Emitted when the server sends a '100 Continue' HTTP response, usually because\nthe request contained 'Expect: 100-continue'. This is an instruction that\nthe client should send the request body.\n\n

\n", + "params": [] + } + ], + "methods": [ + { + "textRaw": "request.write(chunk, [encoding])", + "type": "method", + "name": "write", + "desc": "

Sends a chunk of the body. By calling this method\nmany times, the user can stream a request body to a\nserver--in that case it is suggested to use the\n['Transfer-Encoding', 'chunked'] header line when\ncreating the request.\n\n

\n

The chunk argument should be a buffer or a string.\n\n

\n

The encoding argument is optional and only applies when chunk is a string.\nDefaults to 'utf8'.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "chunk" + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "request.end([data], [encoding])", + "type": "method", + "name": "end", + "desc": "

Finishes sending the request. If any parts of the body are\nunsent, it will flush them to the stream. If the request is\nchunked, this will send the terminating '0\\r\\n\\r\\n'.\n\n

\n

If data is specified, it is equivalent to calling\nrequest.write(data, encoding) followed by request.end().\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "data", + "optional": true + }, + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "request.abort()", + "type": "method", + "name": "abort", + "desc": "

Aborts a request. (New since v0.3.8.)\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "request.setTimeout(timeout, [callback])", + "type": "method", + "name": "setTimeout", + "desc": "

Once a socket is assigned to this request and is connected \nsocket.setTimeout(timeout, [callback])\nwill be called.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "timeout" + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "request.setNoDelay([noDelay])", + "type": "method", + "name": "setNoDelay", + "desc": "

Once a socket is assigned to this request and is connected \nsocket.setNoDelay(noDelay)\nwill be called.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "noDelay", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "request.setSocketKeepAlive([enable], [initialDelay])", + "type": "method", + "name": "setSocketKeepAlive", + "desc": "

Once a socket is assigned to this request and is connected \nsocket.setKeepAlive(enable, [initialDelay])\nwill be called.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "enable", + "optional": true + }, + { + "name": "initialDelay", + "optional": true + } + ] + } + ] + } + ] + } + ], + "properties": [ + { + "textRaw": "http.globalAgent", + "name": "globalAgent", + "desc": "

Global instance of Agent which is used as the default for all http client\nrequests.\n\n\n

\n" + }, + { + "textRaw": "http.ClientResponse", + "name": "ClientResponse", + "desc": "

This object is created when making a request with http.request(). It is\npassed to the 'response' event of the request object.\n\n

\n

The response implements the Readable Stream\ninterface. This is an EventEmitter with the following events:\n\n\n

\n", + "events": [ + { + "textRaw": "Event: 'data'", + "type": "event", + "name": "data", + "desc": "

function (chunk) { }\n\n

\n

Emitted when a piece of the message body is received.\n\n

\n

Note that the data will be lost if there is no listener when a\nClientResponse emits a 'data' event.\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'end'", + "type": "event", + "name": "end", + "desc": "

function () { }\n\n

\n

Emitted exactly once for each message. No arguments. After\nemitted no other events will be emitted on the response.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function (err) { }\n\n

\n

Indicates that the underlaying connection was terminated before\nend event was emitted.\nSee http.ServerRequest's 'close' event for more\ninformation.\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "response.statusCode", + "name": "statusCode", + "desc": "

The 3-digit HTTP response status code. E.G. 404.\n\n

\n" + }, + { + "textRaw": "response.httpVersion", + "name": "httpVersion", + "desc": "

The HTTP version of the connected-to server. Probably either\n'1.1' or '1.0'.\nAlso response.httpVersionMajor is the first integer and\nresponse.httpVersionMinor is the second.\n\n

\n" + }, + { + "textRaw": "response.headers", + "name": "headers", + "desc": "

The response headers object.\n\n

\n" + }, + { + "textRaw": "response.trailers", + "name": "trailers", + "desc": "

The response trailers object. Only populated after the 'end' event.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "response.setEncoding([encoding])", + "type": "method", + "name": "setEncoding", + "desc": "

Set the encoding for the response body. Either 'utf8', 'ascii', or\n'base64'. Defaults to null, which means that the 'data' event will emit\na Buffer object.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "response.pause()", + "type": "method", + "name": "pause", + "desc": "

Pauses response from emitting events. Useful to throttle back a download.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "response.resume()", + "type": "method", + "name": "resume", + "desc": "

Resumes a paused response.\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + } + ], + "type": "module", + "displayName": "HTTP" + } + ] +} --- /dev/null +++ b/doc/api/dns.html @@ -0,0 +1,235 @@ + + + + + DNS Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

DNS#

+
Stability: 3 - Stable
+

Use require('dns') to access this module. All methods in the dns module +use C-Ares except for dns.lookup which uses getaddrinfo(3) in a thread +pool. C-Ares is much faster than getaddrinfo but the system resolver is +more constant with how other programs operate. When a user does +net.connect(80, 'google.com') or http.get({ host: 'google.com' }) the +dns.lookup method is used. Users who need to do a large number of look ups +quickly should use the methods that go through C-Ares. + +

+

Here is an example which resolves 'www.google.com' then reverse +resolves the IP addresses which are returned. + +

+
var dns = require('dns');
+
+dns.resolve4('www.google.com', function (err, addresses) {
+  if (err) throw err;
+
+  console.log('addresses: ' + JSON.stringify(addresses));
+
+  addresses.forEach(function (a) {
+    dns.reverse(a, function (err, domains) {
+      if (err) {
+        console.log('reverse for ' + a + ' failed: ' +
+          err.message);
+      } else {
+        console.log('reverse for ' + a + ': ' +
+          JSON.stringify(domains));
+      }
+    });
+  });
+});
+

dns.lookup(domain, [family], callback)#

+

Resolves a domain (e.g. 'google.com') into the first found A (IPv4) or +AAAA (IPv6) record. +The family can be the integer 4 or 6. Defaults to null that indicates +both Ip v4 and v6 address family. + +

+

The callback has arguments (err, address, family). The address argument +is a string representation of a IP v4 or v6 address. The family argument +is either the integer 4 or 6 and denotes the family of address (not +necessarily the value initially passed to lookup). + + +

+

dns.resolve(domain, [rrtype], callback)#

+

Resolves a domain (e.g. 'google.com') into an array of the record types +specified by rrtype. Valid rrtypes are 'A' (IPV4 addresses, default), +'AAAA' (IPV6 addresses), 'MX' (mail exchange records), 'TXT' (text +records), 'SRV' (SRV records), 'PTR' (used for reverse IP lookups), +'NS' (name server records) and 'CNAME' (canonical name records). + +

+

The callback has arguments (err, addresses). The type of each item +in addresses is determined by the record type, and described in the +documentation for the corresponding lookup methods below. + +

+

On error, err would be an instanceof Error object, where err.errno is +one of the error codes listed below and err.message is a string describing +the error in English. + + +

+

dns.resolve4(domain, callback)#

+

The same as dns.resolve(), but only for IPv4 queries (A records). +addresses is an array of IPv4 addresses (e.g. +['74.125.79.104', '74.125.79.105', '74.125.79.106']). + +

+

dns.resolve6(domain, callback)#

+

The same as dns.resolve4() except for IPv6 queries (an AAAA query). + + +

+

dns.resolveMx(domain, callback)#

+

The same as dns.resolve(), but only for mail exchange queries (MX records). + +

+

addresses is an array of MX records, each with a priority and an exchange +attribute (e.g. [{'priority': 10, 'exchange': 'mx.example.com'},...]). + +

+

dns.resolveTxt(domain, callback)#

+

The same as dns.resolve(), but only for text queries (TXT records). +addresses is an array of the text records available for domain (e.g., +['v=spf1 ip4:0.0.0.0 ~all']). + +

+

dns.resolveSrv(domain, callback)#

+

The same as dns.resolve(), but only for service records (SRV records). +addresses is an array of the SRV records available for domain. Properties +of SRV records are priority, weight, port, and name (e.g., +[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]). + +

+

dns.reverse(ip, callback)#

+

Reverse resolves an ip address to an array of domain names. + +

+

The callback has arguments (err, domains). + +

+

dns.resolveNs(domain, callback)#

+

The same as dns.resolve(), but only for name server records (NS records). +addresses is an array of the name server records available for domain +(e.g., ['ns1.example.com', 'ns2.example.com']). + +

+

dns.resolveCname(domain, callback)#

+

The same as dns.resolve(), but only for canonical name records (CNAME +records). addresses is an array of the canonical name records available for +domain (e.g., ['bar.example.com']). + +

+

If there an an error, err will be non-null and an instanceof the Error +object. + +

+

Each DNS query can return an error code. + +

+
    +
  • dns.TEMPFAIL: timeout, SERVFAIL or similar.
    • +
  • dns.PROTOCOL: got garbled reply.
    • +
  • dns.NXDOMAIN: domain does not exists.
    • +
  • dns.NODATA: domain exists but no data of reqd type.
    • +
  • dns.NOMEM: out of memory while processing.
    • +
  • dns.BADQUERY: the query is malformed.
    • +
+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/events.html @@ -0,0 +1,198 @@ + + + + + Events Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Events#

+
Stability: 4 - API Frozen
+ + +

Many objects in Node emit events: a net.Server emits an event each time +a peer connects to it, a fs.readStream emits an event when the file is +opened. All objects which emit events are instances of events.EventEmitter. +You can access this module by doing: require("events"); + +

+

Typically, event names are represented by a camel-cased string, however, +there aren't any strict restrictions on that, as any string will be accepted. + +

+

Functions can then be attached to objects, to be executed when an event +is emitted. These functions are called listeners. + + +

+

Class: events.EventEmitter#

+

To access the EventEmitter class, require('events').EventEmitter. + +

+

When an EventEmitter instance experiences an error, the typical action is +to emit an 'error' event. Error events are treated as a special case in node. +If there is no listener for it, then the default action is to print a stack +trace and exit the program. + +

+

All EventEmitters emit the event 'newListener' when new listeners are +added. + +

+

emitter.addListener(event, listener)#

+

emitter.on(event, listener)#

+

Adds a listener to the end of the listeners array for the specified event. + +

+
server.on('connection', function (stream) {
+  console.log('someone connected!');
+});
+

emitter.once(event, listener)#

+

Adds a one time listener for the event. This listener is +invoked only the next time the event is fired, after which +it is removed. + +

+
server.once('connection', function (stream) {
+  console.log('Ah, we have our first user!');
+});
+

emitter.removeListener(event, listener)#

+

Remove a listener from the listener array for the specified event. +Caution: changes array indices in the listener array behind the listener. + +

+
var callback = function(stream) {
+  console.log('someone connected!');
+};
+server.on('connection', callback);
+// ...
+server.removeListener('connection', callback);
+

emitter.removeAllListeners([event])#

+

Removes all listeners, or those of the specified event. + + +

+

emitter.setMaxListeners(n)#

+

By default EventEmitters will print a warning if more than 10 listeners are +added for a particular event. This is a useful default which helps finding memory leaks. +Obviously not all Emitters should be limited to 10. This function allows +that to be increased. Set to zero for unlimited. + + +

+

emitter.listeners(event)#

+

Returns an array of listeners for the specified event. This array can be +manipulated, e.g. to remove listeners. + +

+
server.on('connection', function (stream) {
+  console.log('someone connected!');
+});
+console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
+

emitter.emit(event, [arg1], [arg2], [...])#

+

Execute each of the listeners in order with the supplied arguments. + +

+

Event: 'newListener'#

+
    +
  • event String The event name
    • +
  • listener Function The event handler function
    • +
+

This event is emitted any time someone adds a new listener. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/timers.json @@ -0,0 +1,98 @@ +{ + "source": "doc/api/timers.markdown", + "modules": [ + { + "textRaw": "Timers", + "name": "timers", + "stability": 5, + "stabilityText": "Locked", + "desc": "

All of the timer functions are globals. You do not need to require()\nthis module in order to use them.\n\n

\n", + "methods": [ + { + "textRaw": "setTimeout(callback, delay, [arg], [...])", + "type": "method", + "name": "setTimeout", + "desc": "

To schedule execution of a one-time callback after delay milliseconds. Returns a\ntimeoutId for possible use with clearTimeout(). Optionally you can\nalso pass arguments to the callback.\n\n

\n

It is important to note that your callback will probably not be called in exactly\ndelay milliseconds - Node.js makes no guarantees about the exact timing of when\nthe callback will fire, nor of the ordering things will fire in. The callback will\nbe called as close as possible to the time specified.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "callback" + }, + { + "name": "delay" + }, + { + "name": "arg", + "optional": true + }, + { + "name": "...", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "clearTimeout(timeoutId)", + "type": "method", + "name": "clearTimeout", + "desc": "

Prevents a timeout from triggering.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "timeoutId" + } + ] + } + ] + }, + { + "textRaw": "setInterval(callback, delay, [arg], [...])", + "type": "method", + "name": "setInterval", + "desc": "

To schedule the repeated execution of callback every delay milliseconds.\nReturns a intervalId for possible use with clearInterval(). Optionally\nyou can also pass arguments to the callback.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "callback" + }, + { + "name": "delay" + }, + { + "name": "arg", + "optional": true + }, + { + "name": "...", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "clearInterval(intervalId)", + "type": "method", + "name": "clearInterval", + "desc": "

Stops a interval from triggering.\n

\n", + "signatures": [ + { + "params": [ + { + "name": "intervalId" + } + ] + } + ] + } + ], + "type": "module", + "displayName": "Timers" + } + ] +} --- /dev/null +++ b/doc/api/globals.html @@ -0,0 +1,255 @@ + + + + + Global Objects Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Global Objects#

+ + +

These objects are available in all modules. Some of these objects aren't +actually in the global scope but in the module scope - this will be noted. + +

+

global#

+ + +
    +
  • {Object} The global namespace object.
    • +
+

In browsers, the top-level scope is the global scope. That means that in +browsers if you're in the global scope var something will define a global +variable. In Node this is different. The top-level scope is not the global +scope; var something inside a Node module will be local to that module. + +

+

process#

+ + +
    +
  • {Object}
    • +
+

The process object. See the process object section. + +

+

console#

+ + +
    +
  • {Object}
    • +
+

Used to print to stdout and stderr. See the stdio section. + +

+

Buffer#

+ + +
    +
  • {Object}
    • +
+

Used to handle binary data. See the buffer section. + +

+

require()#

+ + +
    +
  • {Function}
    • +
+

To require modules. See the Modules section. +require isn't actually a global but rather local to each module. + + +

+

require.resolve()#

+

Use the internal require() machinery to look up the location of a module, +but rather than loading the module, just return the resolved filename. + +

+

require.cache#

+
    +
  • Object
    • +
+

Modules are cached in this object when they are required. By deleting a key +value from this object, the next require will reload the module. + +

+

__filename#

+ + +
    +
  • {String}
    • +
+

The filename of the code being executed. This is the resolved absolute path +of this code file. For a main program this is not necessarily the same +filename used in the command line. The value inside a module is the path +to that module file. + +

+

Example: running node example.js from /Users/mjr + +

+
console.log(__filename);
+// /Users/mjr/example.js
+

__filename isn't actually a global but rather local to each module. + +

+

__dirname#

+ + +
    +
  • {String}
    • +
+

The name of the directory that the currently executing script resides in. + +

+

Example: running node example.js from /Users/mjr + +

+
console.log(__dirname);
+// /Users/mjr
+

__dirname isn't actually a global but rather local to each module. + + +

+

module#

+ + +
    +
  • {Object}
    • +
+

A reference to the current module. In particular +module.exports is the same as the exports object. See src/node.js +for more information. +module isn't actually a global but rather local to each module. + + +

+

exports#

+ + +

An object which is shared between all instances of the current module and +made accessible through require(). +exports is the same as the module.exports object. See src/node.js +for more information. +exports isn't actually a global but rather local to each module. + +

+

See the module system documentation for more +information. + +

+

See the module section for more information. + +

+

setTimeout(cb, ms)#

+

clearTimeout(t)#

+

setInterval(cb, ms)#

+

clearInterval(t)#

+ + +

The timer functions are global variables. See the timers section. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/crypto.html @@ -0,0 +1,494 @@ + + + + + Crypto Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ +
+

Table of Contents

+ + +
+ +
+

Crypto#

+
Stability: 3 - Stable
+

Use require('crypto') to access this module. + +

+

The crypto module requires OpenSSL to be available on the underlying platform. +It offers a way of encapsulating secure credentials to be used as part +of a secure HTTPS net or http connection. + +

+

It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods. + +

+

crypto.createCredentials(details)#

+

Creates a credentials object, with the optional details being a dictionary with keys: + +

+
    +
  • pfx : A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
    • +
  • key : a string holding the PEM encoded private key
    • +
  • cert : a string holding the PEM encoded certificate
    • +
  • passphrase : A string of passphrase for the private key or pfx
    • +
  • ca : either a string or list of strings of PEM encoded CA certificates to trust.
    • +
  • ciphers: a string describing the ciphers to use or exclude. Consult +http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details +on the format.
    • +
+

If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in +

+

http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt. + + +

+

crypto.createHash(algorithm)#

+

Creates and returns a hash object, a cryptographic hash with the given algorithm +which can be used to generate hash digests. + +

+

algorithm is dependent on the available algorithms supported by the version +of OpenSSL on the platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', etc. +On recent releases, openssl list-message-digest-algorithms will display the available digest algorithms. + +

+

Example: this program that takes the sha1 sum of a file + +

+
var filename = process.argv[2];
+var crypto = require('crypto');
+var fs = require('fs');
+
+var shasum = crypto.createHash('sha1');
+
+var s = fs.ReadStream(filename);
+s.on('data', function(d) {
+  shasum.update(d);
+});
+
+s.on('end', function() {
+  var d = shasum.digest('hex');
+  console.log(d + '  ' + filename);
+});
+

Class: Hash#

+

The class for creating hash digests of data. + +

+

Returned by crypto.createHash. + +

+

hash.update(data, [input_encoding])#

+

Updates the hash content with the given data, the encoding of which is given +in input_encoding and can be 'utf8', 'ascii' or 'binary'. +Defaults to 'binary'. +This can be called many times with new data as it is streamed. + +

+

hash.digest([encoding])#

+

Calculates the digest of all of the passed data to be hashed. +The encoding can be 'hex', 'binary' or 'base64'. +Defaults to 'binary'. + +

+

Note: hash object can not be used after digest() method been called. + + +

+

crypto.createHmac(algorithm, key)#

+

Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key. + +

+

algorithm is dependent on the available algorithms supported by OpenSSL - see createHash above. +key is the hmac key to be used. + +

+

Class: Hmac#

+

Class for creating cryptographic hmac content. + +

+

Returned by crypto.createHmac. + +

+

hmac.update(data)#

+

Update the hmac content with the given data. +This can be called many times with new data as it is streamed. + +

+

hmac.digest([encoding])#

+

Calculates the digest of all of the passed data to the hmac. +The encoding can be 'hex', 'binary' or 'base64'. +Defaults to 'binary'. + +

+

Note: hmac object can not be used after digest() method been called. + + +

+

crypto.createCipher(algorithm, password)#

+

Creates and returns a cipher object, with the given algorithm and password. + +

+

algorithm is dependent on OpenSSL, examples are 'aes192', etc. +On recent releases, openssl list-cipher-algorithms will display the +available cipher algorithms. +password is used to derive key and IV, which must be 'binary' encoded +string (See the Buffer section for more information). + +

+

crypto.createCipheriv(algorithm, key, iv)#

+

Creates and returns a cipher object, with the given algorithm, key and iv. + +

+

algorithm is the same as the createCipher(). key is a raw key used in +algorithm. iv is an Initialization vector. key and iv must be 'binary' +encoded string (See the Buffer section for more information). + +

+

Class: Cipher#

+

Class for encrypting data. + +

+

Returned by crypto.createCipher and crypto.createCipheriv. + +

+

cipher.update(data, [input_encoding], [output_encoding])#

+

Updates the cipher with data, the encoding of which is given in +input_encoding and can be 'utf8', 'ascii' or 'binary'. +Defaults to 'binary'. + +

+

The output_encoding specifies the output format of the enciphered data, +and can be 'binary', 'base64' or 'hex'. Defaults to 'binary'. + +

+

Returns the enciphered contents, and can be called many times with new data as it is streamed. + +

+

cipher.final([output_encoding])#

+

Returns any remaining enciphered contents, with output_encoding being one of: +'binary', 'base64' or 'hex'. Defaults to 'binary'. + +

+

Note: cipher object can not be used after final() method been called. + + +

+

crypto.createDecipher(algorithm, password)#

+

Creates and returns a decipher object, with the given algorithm and key. +This is the mirror of the createCipher() above. + +

+

crypto.createDecipheriv(algorithm, key, iv)#

+

Creates and returns a decipher object, with the given algorithm, key and iv. +This is the mirror of the createCipheriv() above. + +

+

Class: Decipher#

+

Class for decrypting data. + +

+

Returned by crypto.createDecipher and crypto.createDecipheriv. + +

+

decipher.update(data, [input_encoding], [output_encoding])#

+

Updates the decipher with data, which is encoded in 'binary', 'base64' +or 'hex'. Defaults to 'binary'. + +

+

The output_decoding specifies in what format to return the deciphered +plaintext: 'binary', 'ascii' or 'utf8'. Defaults to 'binary'. + +

+

decipher.final([output_encoding])#

+

Returns any remaining plaintext which is deciphered, +with output_encoding being one of: 'binary', 'ascii' or 'utf8'. +Defaults to 'binary'. + +

+

Note: decipher object can not be used after final() method been called. + + +

+

crypto.createSign(algorithm)#

+

Creates and returns a signing object, with the given algorithm. +On recent OpenSSL releases, openssl list-public-key-algorithms will display +the available signing algorithms. Examples are 'RSA-SHA256'. + +

+

Class: Signer#

+

Class for generating signatures. + +

+

Returned by crypto.createSign. + +

+

signer.update(data)#

+

Updates the signer object with data. +This can be called many times with new data as it is streamed. + +

+

signer.sign(private_key, [output_format])#

+

Calculates the signature on all the updated data passed through the signer. +private_key is a string containing the PEM encoded private key for signing. + +

+

Returns the signature in output_format which can be 'binary', 'hex' or +'base64'. Defaults to 'binary'. + +

+

Note: signer object can not be used after sign() method been called. + +

+

crypto.createVerify(algorithm)#

+

Creates and returns a verification object, with the given algorithm. +This is the mirror of the signing object above. + +

+

Class: Verify#

+

Class for verifying signatures. + +

+

Returned by crypto.createVerify. + +

+

verifier.update(data)#

+

Updates the verifier object with data. +This can be called many times with new data as it is streamed. + +

+

verifier.verify(object, signature, [signature_format])#

+

Verifies the signed data by using the object and signature. object is a +string containing a PEM encoded object, which can be one of RSA public key, +DSA public key, or X.509 certificate. signature is the previously calculated +signature for the data, in the signature_format which can be 'binary', +'hex' or 'base64'. Defaults to 'binary'. + +

+

Returns true or false depending on the validity of the signature for the data and public key. + +

+

Note: verifier object can not be used after verify() method been called. + +

+

crypto.createDiffieHellman(prime_length)#

+

Creates a Diffie-Hellman key exchange object and generates a prime of the +given bit length. The generator used is 2. + +

+

crypto.createDiffieHellman(prime, [encoding])#

+

Creates a Diffie-Hellman key exchange object using the supplied prime. The +generator used is 2. Encoding can be 'binary', 'hex', or 'base64'. +Defaults to 'binary'. + +

+

Class: DiffieHellman#

+

The class for creating Diffie-Hellman key exchanges. + +

+

Returned by crypto.createDiffieHellman. + +

+

diffieHellman.generateKeys([encoding])#

+

Generates private and public Diffie-Hellman key values, and returns the +public key in the specified encoding. This key should be transferred to the +other party. Encoding can be 'binary', 'hex', or 'base64'. +Defaults to 'binary'. + +

+

diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])#

+

Computes the shared secret using other_public_key as the other party's +public key and returns the computed shared secret. Supplied key is +interpreted using specified input_encoding, and secret is encoded using +specified output_encoding. Encodings can be 'binary', 'hex', or +'base64'. The input encoding defaults to 'binary'. +If no output encoding is given, the input encoding is used as output encoding. + +

+

diffieHellman.getPrime([encoding])#

+

Returns the Diffie-Hellman prime in the specified encoding, which can be +'binary', 'hex', or 'base64'. Defaults to 'binary'. + +

+

diffieHellman.getGenerator([encoding])#

+

Returns the Diffie-Hellman prime in the specified encoding, which can be +'binary', 'hex', or 'base64'. Defaults to 'binary'. + +

+

diffieHellman.getPublicKey([encoding])#

+

Returns the Diffie-Hellman public key in the specified encoding, which can +be 'binary', 'hex', or 'base64'. Defaults to 'binary'. + +

+

diffieHellman.getPrivateKey([encoding])#

+

Returns the Diffie-Hellman private key in the specified encoding, which can +be 'binary', 'hex', or 'base64'. Defaults to 'binary'. + +

+

diffieHellman.setPublicKey(public_key, [encoding])#

+

Sets the Diffie-Hellman public key. Key encoding can be 'binary', 'hex', +or 'base64'. Defaults to 'binary'. + +

+

diffieHellman.setPrivateKey(public_key, [encoding])#

+

Sets the Diffie-Hellman private key. Key encoding can be 'binary', 'hex', +or 'base64'. Defaults to 'binary'. + +

+

crypto.pbkdf2(password, salt, iterations, keylen, callback)#

+

Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive +a key of given length from the given password, salt and iterations. +The callback gets two arguments (err, derivedKey). + +

+

crypto.randomBytes(size, [callback])#

+

Generates cryptographically strong pseudo-random data. Usage: + +

+
// async
+crypto.randomBytes(256, function(ex, buf) {
+  if (ex) throw ex;
+  console.log('Have %d bytes of random data: %s', buf.length, buf);
+});
+
+// sync
+try {
+  var buf = crypto.randomBytes(256);
+  console.log('Have %d bytes of random data: %s', buf.length, buf);
+} catch (ex) {
+  // handle error
+}
+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/stream.json @@ -0,0 +1,277 @@ +{ + "source": "doc/api/stream.markdown", + "modules": [ + { + "textRaw": "Stream", + "name": "stream", + "stability": 2, + "stabilityText": "Unstable", + "desc": "

A stream is an abstract interface implemented by various objects in Node.\nFor example a request to an HTTP server is a stream, as is stdout. Streams\nare readable, writable, or both. All streams are instances of EventEmitter.\n\n

\n

You can load up the Stream base class by doing require('stream').\n\n

\n", + "classes": [ + { + "textRaw": "Readable Stream", + "name": "Readable Stream", + "type": "class", + "desc": "

A Readable Stream has the following methods, members, and events.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'data'", + "type": "event", + "name": "data", + "desc": "

function (data) { }\n\n

\n

The 'data' event emits either a Buffer (by default) or a string if\nsetEncoding() was used.\n\n

\n

Note that the data will be lost if there is no listener when a\nReadable Stream emits a 'data' event.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'end'", + "type": "event", + "name": "end", + "desc": "

function () { }\n\n

\n

Emitted when the stream has received an EOF (FIN in TCP terminology).\nIndicates that no more 'data' events will happen. If the stream is also\nwritable, it may be possible to continue writing.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "desc": "

function (exception) { }\n\n

\n

Emitted if there was an error receiving data.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () { }\n\n

\n

Emitted when the underlying file descriptor has been closed. Not all streams\nwill emit this. (For example, an incoming HTTP request will not emit\n'close'.)\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "stream.readable", + "name": "readable", + "desc": "

A boolean that is true by default, but turns false after an 'error'\noccurred, the stream came to an 'end', or destroy() was called.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "stream.setEncoding(encoding)", + "type": "method", + "name": "setEncoding", + "desc": "

Makes the data event emit a string instead of a Buffer. encoding can be\n'utf8', 'ascii', or 'base64'.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "encoding" + } + ] + } + ] + }, + { + "textRaw": "stream.pause()", + "type": "method", + "name": "pause", + "desc": "

Pauses the incoming 'data' events.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "stream.resume()", + "type": "method", + "name": "resume", + "desc": "

Resumes the incoming 'data' events after a pause().\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "stream.destroy()", + "type": "method", + "name": "destroy", + "desc": "

Closes the underlying file descriptor. Stream will not emit any more events.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "stream.pipe(destination, [options])", + "type": "method", + "name": "pipe", + "desc": "

This is a Stream.prototype method available on all Streams.\n\n

\n

Connects this read stream to destination WriteStream. Incoming\ndata on this stream gets written to destination. The destination and source\nstreams are kept in sync by pausing and resuming as necessary.\n\n

\n

This function returns the destination stream.\n\n

\n

Emulating the Unix cat command:\n\n

\n
process.stdin.resume();\nprocess.stdin.pipe(process.stdout);
\n

By default end() is called on the destination when the source stream emits\nend, so that destination is no longer writable. Pass { end: false } as\noptions to keep the destination stream open.\n\n

\n

This keeps process.stdout open so that "Goodbye" can be written at the end.\n\n

\n
process.stdin.resume();\n\nprocess.stdin.pipe(process.stdout, { end: false });\n\nprocess.stdin.on("end", function() {\n  process.stdout.write("Goodbye\\n");\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "destination" + }, + { + "name": "options", + "optional": true + } + ] + } + ] + } + ] + }, + { + "textRaw": "Writable Stream", + "name": "Writable Stream", + "type": "class", + "desc": "

A Writable Stream has the following methods, members, and events.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'drain'", + "type": "event", + "name": "drain", + "desc": "

function () { }\n\n

\n

After a write() method returned false, this event is emitted to\nindicate that it is safe to write again.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'error'", + "type": "event", + "name": "error", + "desc": "

function (exception) { }\n\n

\n

Emitted on error with the exception exception.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () { }\n\n

\n

Emitted when the underlying file descriptor has been closed.\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'pipe'", + "type": "event", + "name": "pipe", + "desc": "

function (src) { }\n\n

\n

Emitted when the stream is passed to a readable stream's pipe method.\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "stream.writable", + "name": "writable", + "desc": "

A boolean that is true by default, but turns false after an 'error'\noccurred or end() / destroy() was called.\n\n

\n" + } + ], + "methods": [ + { + "textRaw": "stream.write(string, [encoding], [fd])", + "type": "method", + "name": "write", + "desc": "

Writes string with the given encoding to the stream. Returns true if\nthe string has been flushed to the kernel buffer. Returns false to\nindicate that the kernel buffer is full, and the data will be sent out in\nthe future. The 'drain' event will indicate when the kernel buffer is\nempty again. The encoding defaults to 'utf8'.\n\n

\n

If the optional fd parameter is specified, it is interpreted as an integral\nfile descriptor to be sent over the stream. This is only supported for UNIX\nstreams, and is silently ignored otherwise. When writing a file descriptor in\nthis manner, closing the descriptor before the stream drains risks sending an\ninvalid (closed) FD.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "string" + }, + { + "name": "encoding", + "optional": true + }, + { + "name": "fd", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "stream.write(buffer)", + "type": "method", + "name": "write", + "desc": "

Same as the above except with a raw buffer.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buffer" + } + ] + } + ] + }, + { + "textRaw": "stream.end()", + "type": "method", + "name": "end", + "desc": "

Terminates the stream with EOF or FIN.\nThis call will allow queued write data to be sent before closing the stream.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "stream.end(string, encoding)", + "type": "method", + "name": "end", + "desc": "

Sends string with the given encoding and terminates the stream with EOF\nor FIN. This is useful to reduce the number of packets sent.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "string" + }, + { + "name": "encoding" + } + ] + } + ] + }, + { + "textRaw": "stream.end(buffer)", + "type": "method", + "name": "end", + "desc": "

Same as above but with a buffer.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "buffer" + } + ] + } + ] + }, + { + "textRaw": "stream.destroy()", + "type": "method", + "name": "destroy", + "desc": "

Closes the underlying file descriptor. Stream will not emit any more events.\nAny queued write data will not be sent.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "stream.destroySoon()", + "type": "method", + "name": "destroySoon", + "desc": "

After the write queue is drained, close the file descriptor. destroySoon()\ncan still destroy straight away, as long as there is no data left in the queue\nfor writes.\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + } + ], + "type": "module", + "displayName": "Stream" + } + ] +} --- /dev/null +++ b/doc/api/repl.html @@ -0,0 +1,237 @@ + + + + + REPL Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

REPL#

+

A Read-Eval-Print-Loop (REPL) is available both as a standalone program and easily +includable in other programs. REPL provides a way to interactively run +JavaScript and see the results. It can be used for debugging, testing, or +just trying things out. + +

+

By executing node without any arguments from the command-line you will be +dropped into the REPL. It has simplistic emacs line-editing. + +

+
mjr:~$ node
+Type '.help' for options.
+> a = [ 1, 2, 3];
+[ 1, 2, 3 ]
+> a.forEach(function (v) {
+...   console.log(v);
+...   });
+1
+2
+3
+

For advanced line-editors, start node with the environmental variable NODE_NO_READLINE=1. +This will start the REPL in canonical terminal settings which will allow you to use with rlwrap. + +

+

For example, you could add this to your bashrc file: + +

+
alias node="env NODE_NO_READLINE=1 rlwrap node"
+

repl.start([prompt], [stream], [eval], [useGlobal], [ignoreUndefined])#

+

Starts a REPL with prompt as the prompt and stream for all I/O. prompt +is optional and defaults to > . stream is optional and defaults to +process.stdin. eval is optional too and defaults to async wrapper for +eval(). + +

+

If useGlobal is set to true, then the repl will use the global object, +instead of running scripts in a separate context. Defaults to false. + +

+

If ignoreUndefined is set to true, then the repl will not output return value +of command if it's undefined. Defaults to false. + +

+

You can use your own eval function if it has following signature: + +

+
function eval(cmd, callback) {
+  callback(null, result);
+}
+

Multiple REPLs may be started against the same running instance of node. Each +will share the same global object but will have unique I/O. + +

+

Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket: + +

+
var net = require("net"),
+    repl = require("repl");
+
+connections = 0;
+
+repl.start("node via stdin> ");
+
+net.createServer(function (socket) {
+  connections += 1;
+  repl.start("node via Unix socket> ", socket);
+}).listen("/tmp/node-repl-sock");
+
+net.createServer(function (socket) {
+  connections += 1;
+  repl.start("node via TCP socket> ", socket);
+}).listen(5001);
+

Running this program from the command line will start a REPL on stdin. Other +REPL clients may connect through the Unix socket or TCP socket. telnet is useful +for connecting to TCP sockets, and socat can be used to connect to both Unix and +TCP sockets. + +

+

By starting a REPL from a Unix socket-based server instead of stdin, you can +connect to a long-running node process without restarting it. + + +

+

REPL Features#

+ + +

Inside the REPL, Control+D will exit. Multi-line expressions can be input. +Tab completion is supported for both global and local variables. + +

+

The special variable _ (underscore) contains the result of the last expression. + +

+
> [ "a", "b", "c" ]
+[ 'a', 'b', 'c' ]
+> _.length
+3
+> _ += 1
+4
+

The REPL provides access to any variables in the global scope. You can expose +a variable to the REPL explicitly by assigning it to the context object +associated with each REPLServer. For example: + +

+
// repl_test.js
+var repl = require("repl"),
+    msg = "message";
+
+repl.start().context.m = msg;
+

Things in the context object appear as local within the REPL: + +

+
mjr:~$ node repl_test.js
+> m
+'message'
+

There are a few special REPL commands: + +

+
    +
  • .break - While inputting a multi-line expression, sometimes you get lost +or just don't care about completing it. .break will start over.
    • +
  • .clear - Resets the context object to an empty object and clears any +multi-line expression.
    • +
  • .exit - Close the I/O stream, which will cause the REPL to exit.
    • +
  • .help - Show this list of special commands.
    • +
  • .save - Save the current REPL session to a file
    +

    .save ./file/to/save.js

    +
    +
    • +
  • .load - Load a file into the current REPL session.
    +

    .load ./file/to/load.js

    +
    +
    • +
+

The following key combinations in the REPL have these special effects: + +

+
    +
  • <ctrl>C - Similar to the .break keyword. Terminates the current +command. Press twice on a blank line to forcibly exit.
    • +
  • <ctrl>D - Similar to the .exit keyword.
    • +
+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/os.html @@ -0,0 +1,233 @@ + + + + + os Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

os#

+
Stability: 4 - API Frozen
+

Provides a few basic operating-system related utility functions. + +

+

Use require('os') to access this module. + +

+

os.hostname()#

+

Returns the hostname of the operating system. + +

+

os.type()#

+

Returns the operating system name. + +

+

os.platform()#

+

Returns the operating system platform. + +

+

os.arch()#

+

Returns the operating system CPU architecture. + +

+

os.release()#

+

Returns the operating system release. + +

+

os.uptime()#

+

Returns the system uptime in seconds. + +

+

os.loadavg()#

+

Returns an array containing the 1, 5, and 15 minute load averages. + +

+

os.totalmem()#

+

Returns the total amount of system memory in bytes. + +

+

os.freemem()#

+

Returns the amount of free system memory in bytes. + +

+

os.cpus()#

+

Returns an array of objects containing information about each CPU/core installed: model, speed (in MHz), and times (an object containing the number of CPU ticks spent in: user, nice, sys, idle, and irq). + +

+

Example inspection of os.cpus: + +

+
[ { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 252020,
+       nice: 0,
+       sys: 30340,
+       idle: 1070356870,
+       irq: 0 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 306960,
+       nice: 0,
+       sys: 26980,
+       idle: 1071569080,
+       irq: 0 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 248450,
+       nice: 0,
+       sys: 21750,
+       idle: 1070919370,
+       irq: 0 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 256880,
+       nice: 0,
+       sys: 19430,
+       idle: 1070905480,
+       irq: 20 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 511580,
+       nice: 20,
+       sys: 40900,
+       idle: 1070842510,
+       irq: 0 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 291660,
+       nice: 0,
+       sys: 34360,
+       idle: 1070888000,
+       irq: 10 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 308260,
+       nice: 0,
+       sys: 55410,
+       idle: 1071129970,
+       irq: 880 } },
+  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
+    speed: 2926,
+    times:
+     { user: 266450,
+       nice: 1480,
+       sys: 34920,
+       idle: 1072572010,
+       irq: 30 } } ]
+

os.networkInterfaces()#

+

Get a list of network interfaces: + +

+
{ lo0: 
+   [ { address: '::1', family: 'IPv6', internal: true },
+     { address: 'fe80::1', family: 'IPv6', internal: true },
+     { address: '127.0.0.1', family: 'IPv4', internal: true } ],
+  en1: 
+   [ { address: 'fe80::cabc:c8ff:feef:f996', family: 'IPv6',
+       internal: false },
+     { address: '10.0.1.123', family: 'IPv4', internal: false } ],
+  vmnet1: [ { address: '10.99.99.254', family: 'IPv4', internal: false } ],
+  vmnet8: [ { address: '10.88.88.1', family: 'IPv4', internal: false } ],
+  ppp0: [ { address: '10.2.0.231', family: 'IPv4', internal: false } ] }
+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/tls.json @@ -0,0 +1,281 @@ +{ + "source": "doc/api/tls.markdown", + "modules": [ + { + "textRaw": "TLS (SSL)", + "name": "tls_(ssl)", + "stability": 3, + "stabilityText": "Stable", + "desc": "

Use require('tls') to access this module.\n\n

\n

The tls module uses OpenSSL to provide Transport Layer Security and/or\nSecure Socket Layer: encrypted stream communication.\n\n

\n

TLS/SSL is a public/private key infrastructure. Each client and each\nserver must have a private key. A private key is created like this\n\n

\n
openssl genrsa -out ryans-key.pem 1024
\n

All severs and some clients need to have a certificate. Certificates are public\nkeys signed by a Certificate Authority or self-signed. The first step to\ngetting a certificate is to create a "Certificate Signing Request" (CSR)\nfile. This is done with:\n\n

\n
openssl req -new -key ryans-key.pem -out ryans-csr.pem
\n

To create a self-signed certificate with the CSR, do this:\n\n

\n
openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem
\n

Alternatively you can send the CSR to a Certificate Authority for signing.\n\n

\n

(TODO: docs on creating a CA, for now interested users should just look at\ntest/fixtures/keys/Makefile in the Node source code)\n\n

\n

To create .pfx or .p12, do this:\n\n

\n
openssl pkcs12 -export -in agent5-cert.pem -inkey agent5-key.pem \\\n    -certfile ca-cert.pem -out agent5.pfx
\n
    \n
  • in: certificate
    • \n
  • inkey: private key
    • \n
  • certfile: all CA certs concatenated in one file like\ncat ca1-cert.pem ca2-cert.pem > ca-cert.pem
    • \n
\n", + "miscs": [ + { + "textRaw": "Client-initiated renegotiation attack mitigation", + "name": "Client-initiated renegotiation attack mitigation", + "type": "misc", + "desc": "

The TLS protocol lets the client renegotiate certain aspects of the TLS session.\nUnfortunately, session renegotiation requires a disproportional amount of\nserver-side resources, which makes it a potential vector for denial-of-service\nattacks.\n\n

\n

To mitigate this, renegotiations are limited to three times every 10 minutes. An\nerror is emitted on the CleartextStream instance when\nthe threshold is exceeded. The limits are configurable:\n\n

\n
    \n

  • tls.CLIENT_RENEG_LIMIT: renegotiation limit, default is 3.

    \n
    • \n

  • tls.CLIENT_RENEG_WINDOW: renegotiation window in seconds, default is

    \n
                           10 minutes.
    \n
    • \n
\n

Don't change the defaults unless you know what you are doing.\n\n

\n

To test your server, connect to it with openssl s_client -connect address:port\nand tap R<CR> (that's the letter R followed by a carriage return) a few\ntimes.\n\n\n

\n" + }, + { + "textRaw": "NPN and SNI", + "name": "NPN and SNI", + "type": "misc", + "desc": "

NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS\nhandshake extensions allowing you:\n\n

\n
    \n
  • NPN - to use one TLS server for multiple protocols (HTTP, SPDY)
    • \n
  • SNI - to use one TLS server for multiple hostnames with different SSL\ncertificates.
    • \n
\n" + } + ], + "methods": [ + { + "textRaw": "tls.createServer(options, [secureConnectionListener])", + "type": "method", + "name": "createServer", + "desc": "

Creates a new tls.Server.\nThe connectionListener argument is automatically set as a listener for the\nsecureConnection event.\nThe options object has these possibilities:\n\n

\n
    \n

  • pfx: A string or Buffer containing the private key, certificate and\nCA certs of the server in PFX or PKCS12 format. (Mutually exclusive with\nthe key, cert and ca options.)

    \n
    • \n

  • key: A string or Buffer containing the private key of the server in\nPEM format. (Required)

    \n
    • \n

  • passphrase: A string of passphrase for the private key or pfx.

    \n
    • \n

  • cert: A string or Buffer containing the certificate key of the server in\nPEM format. (Required)

    \n
    • \n

  • ca: An array of strings or Buffers of trusted certificates. If this is\nomitted several well known "root" CAs will be used, like VeriSign.\nThese are used to authorize connections.

    \n
    • \n

  • ciphers: A string describing the ciphers to use or exclude. Consult\nhttp://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for\ndetails on the format.

    \n
    • \n

  • requestCert: If true the server will request a certificate from\nclients that connect and attempt to verify that certificate. Default:\nfalse.

    \n
    • \n

  • rejectUnauthorized: If true the server will reject any connection\nwhich is not authorized with the list of supplied CAs. This option only\nhas an effect if requestCert is true. Default: false.

    \n
    • \n

  • NPNProtocols: An array or Buffer of possible NPN protocols. (Protocols\nshould be ordered by their priority).

    \n
    • \n

  • SNICallback: A function that will be called if client supports SNI TLS\nextension. Only one argument will be passed to it: servername. And\nSNICallback should return SecureContext instance.\n(You can use crypto.createCredentials(...).context to get proper\nSecureContext). If SNICallback wasn't provided - default callback with\nhigh-level API will be used (see below).

    \n
    • \n

  • sessionIdContext: A string containing a opaque identifier for session\nresumption. If requestCert is true, the default is MD5 hash value\ngenerated from command-line. Otherwise, the default is not provided.

    \n
    • \n
\n

Here is a simple example echo server:\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  key: fs.readFileSync('server-key.pem'),\n  cert: fs.readFileSync('server-cert.pem'),\n\n  // This is necessary only if using the client certificate authentication.\n  requestCert: true,\n\n  // This is necessary only if the client uses the self-signed certificate.\n  ca: [ fs.readFileSync('client-cert.pem') ]\n};\n\nvar server = tls.createServer(options, function(cleartextStream) {\n  console.log('server connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  cleartextStream.write("welcome!\\n");\n  cleartextStream.setEncoding('utf8');\n  cleartextStream.pipe(cleartextStream);\n});\nserver.listen(8000, function() {\n  console.log('server bound');\n});
\n

Or\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('server.pfx'),\n\n  // This is necessary only if using the client certificate authentication.\n  requestCert: true,\n\n};\n\nvar server = tls.createServer(options, function(cleartextStream) {\n  console.log('server connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  cleartextStream.write("welcome!\\n");\n  cleartextStream.setEncoding('utf8');\n  cleartextStream.pipe(cleartextStream);\n});\nserver.listen(8000, function() {\n  console.log('server bound');\n});
\n

You can test this server by connecting to it with openssl s_client:\n\n\n

\n
openssl s_client -connect 127.0.0.1:8000
\n", + "signatures": [ + { + "params": [ + { + "name": "options" + }, + { + "name": "secureConnectionListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "tls.connect(port, [host], [options], [secureConnectListener])", + "type": "method", + "name": "connect", + "desc": "

Creates a new client connection to the given port and host. (If host\ndefaults to localhost.) options should be an object which specifies\n\n

\n
    \n

  • pfx: A string or Buffer containing the private key, certificate and\nCA certs of the server in PFX or PKCS12 format.

    \n
    • \n

  • key: A string or Buffer containing the private key of the client in\nPEM format.

    \n
    • \n

  • passphrase: A string of passphrase for the private key or pfx.

    \n
    • \n

  • cert: A string or Buffer containing the certificate key of the client in\nPEM format.

    \n
    • \n

  • ca: An array of strings or Buffers of trusted certificates. If this is\nomitted several well known "root" CAs will be used, like VeriSign.\nThese are used to authorize connections.

    \n
    • \n

  • NPNProtocols: An array of string or Buffer containing supported NPN\nprotocols. Buffer should have following format: 0x05hello0x05world,\nwhere first byte is next protocol name's length. (Passing array should\nusually be much simpler: ['hello', 'world'].)

    \n
    • \n

  • servername: Servername for SNI (Server Name Indication) TLS extension.

    \n
    • \n

  • socket: Establish secure connection on a given socket rather than\ncreating a new socket. If this option is specified, host and port\nare ignored. This is intended FOR INTERNAL USE ONLY. As with all\nundocumented APIs in Node, they should not be used.

    \n
    • \n
\n

The secureConnectListener parameter will be added as a listener for the\n'secureConnect' event.\n\n

\n

tls.connect() returns a CleartextStream object.\n\n

\n

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

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  // These are necessary only if using the client certificate authentication\n  key: fs.readFileSync('client-key.pem'),\n  cert: fs.readFileSync('client-cert.pem'),\n\n  // This is necessary only if the server uses the self-signed certificate\n  ca: [ fs.readFileSync('server-cert.pem') ]\n};\n\nvar cleartextStream = tls.connect(8000, options, function() {\n  console.log('client connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  process.stdin.pipe(cleartextStream);\n  process.stdin.resume();\n});\ncleartextStream.setEncoding('utf8');\ncleartextStream.on('data', function(data) {\n  console.log(data);\n});\ncleartextStream.on('end', function() {\n  server.close();\n});
\n

Or\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('client.pfx')\n};\n\nvar cleartextStream = tls.connect(8000, options, function() {\n  console.log('client connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  process.stdin.pipe(cleartextStream);\n  process.stdin.resume();\n});\ncleartextStream.setEncoding('utf8');\ncleartextStream.on('data', function(data) {\n  console.log(data);\n});\ncleartextStream.on('end', function() {\n  server.close();\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "port" + }, + { + "name": "host", + "optional": true + }, + { + "name": "options", + "optional": true + }, + { + "name": "secureConnectListener", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])", + "type": "method", + "name": "createSecurePair", + "desc": "

Creates a new secure pair object with two streams, one of which reads/writes\nencrypted data, and one reads/writes cleartext data.\nGenerally the encrypted one is piped to/from an incoming encrypted data stream,\nand the cleartext one is used as a replacement for the initial encrypted stream.\n\n

\n
    \n

  • credentials: A credentials object from crypto.createCredentials( ... )

    \n
    • \n

  • isServer: A boolean indicating whether this tls connection should be\nopened as a server or a client.

    \n
    • \n

  • requestCert: A boolean indicating whether a server should request a\ncertificate from a connecting client. Only applies to server connections.

    \n
    • \n

  • rejectUnauthorized: A boolean indicating whether a server should\nautomatically reject clients with invalid certificates. Only applies to\nservers with requestCert enabled.

    \n
    • \n
\n

tls.createSecurePair() returns a SecurePair object with\ncleartext and encrypted stream properties.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "credentials", + "optional": true + }, + { + "name": "isServer", + "optional": true + }, + { + "name": "requestCert", + "optional": true + }, + { + "name": "rejectUnauthorized", + "optional": true + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: SecurePair", + "type": "class", + "name": "SecurePair", + "desc": "

Returned by tls.createSecurePair.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'secure'", + "type": "event", + "name": "secure", + "desc": "

The event is emitted from the SecurePair once the pair has successfully\nestablished a secure connection.\n\n

\n

Similarly to the checking for the server 'secureConnection' event,\npair.cleartext.authorized should be checked to confirm whether the certificate\nused properly authorized.\n\n

\n", + "params": [] + } + ] + }, + { + "textRaw": "Class: tls.Server", + "type": "class", + "name": "tls.Server", + "desc": "

This class is a subclass of net.Server and has the same methods on it.\nInstead of accepting just raw TCP connections, this accepts encrypted\nconnections using TLS or SSL.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'secureConnection'", + "type": "event", + "name": "secureConnection", + "desc": "

function (cleartextStream) {}\n\n

\n

This event is emitted after a new connection has been successfully\nhandshaked. The argument is a instance of\nCleartextStream. It has all the common stream methods\nand events.\n\n

\n

cleartextStream.authorized is a boolean value which indicates if the\nclient has verified by one of the supplied certificate authorities for the\nserver. If cleartextStream.authorized is false, then\ncleartextStream.authorizationError is set to describe how authorization\nfailed. Implied but worth mentioning: depending on the settings of the TLS\nserver, you unauthorized connections may be accepted.\ncleartextStream.npnProtocol is a string containing selected NPN protocol.\ncleartextStream.servername is a string containing servername requested with\nSNI.\n\n\n

\n", + "params": [] + }, + { + "textRaw": "Event: 'clientError'", + "type": "event", + "name": "clientError", + "desc": "

function (exception) { }\n\n

\n

When a client connection emits an 'error' event before secure connection is\nestablished - it will be forwarded here.\n\n\n

\n", + "params": [] + } + ], + "methods": [ + { + "textRaw": "server.listen(port, [host], [callback])", + "type": "method", + "name": "listen", + "desc": "

Begin accepting connections on the specified port and host. If the\nhost is omitted, the server will accept connections directed to any\nIPv4 address (INADDR_ANY).\n\n

\n

This function is asynchronous. The last parameter callback will be called\nwhen the server has been bound.\n\n

\n

See net.Server for more information.\n\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "port" + }, + { + "name": "host", + "optional": true + }, + { + "name": "callback", + "optional": true + } + ] + } + ] + }, + { + "textRaw": "server.close()", + "type": "method", + "name": "close", + "desc": "

Stops the server from accepting new connections. This function is\nasynchronous, the server is finally closed when the server emits a 'close'\nevent.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "server.address()", + "type": "method", + "name": "address", + "desc": "

Returns the bound address and port of the server as reported by the operating\nsystem.\nSee net.Server.address() for more information.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "server.addContext(hostname, credentials)", + "type": "method", + "name": "addContext", + "desc": "

Add secure context that will be used if client request's SNI hostname is\nmatching passed hostname (wildcards can be used). credentials can contain\nkey, cert and ca.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "hostname" + }, + { + "name": "credentials" + } + ] + } + ] + } + ], + "properties": [ + { + "textRaw": "server.maxConnections", + "name": "maxConnections", + "desc": "

Set this property to reject connections when the server's connection count\ngets high.\n\n

\n" + }, + { + "textRaw": "server.connections", + "name": "connections", + "desc": "

The number of concurrent connections on the server.\n\n\n

\n" + } + ] + }, + { + "textRaw": "Class: tls.CleartextStream", + "type": "class", + "name": "tls.CleartextStream", + "desc": "

This is a stream on top of the Encrypted stream that makes it possible to\nread/write an encrypted data as a cleartext data.\n\n

\n

This instance implements a duplex Stream interfaces.\nIt has all the common stream methods and events.\n\n

\n

A ClearTextStream is the clear member of a SecurePair object.\n\n

\n", + "events": [ + { + "textRaw": "Event: 'secureConnect'", + "type": "event", + "name": "secureConnect", + "desc": "

This event is emitted after a new connection has been successfully handshaked. \nThe listener will be called no matter if the server's certificate was\nauthorized or not. It is up to the user to test cleartextStream.authorized\nto see if the server certificate was signed by one of the specified CAs.\nIf cleartextStream.authorized === false then the error can be found in\ncleartextStream.authorizationError. Also if NPN was used - you can check\ncleartextStream.npnProtocol for negotiated protocol.\n\n

\n", + "params": [] + } + ], + "properties": [ + { + "textRaw": "cleartextStream.authorized", + "name": "authorized", + "desc": "

A boolean that is true if the peer certificate was signed by one of the\nspecified CAs, otherwise false\n\n

\n" + }, + { + "textRaw": "cleartextStream.authorizationError", + "name": "authorizationError", + "desc": "

The reason why the peer's certificate has not been verified. This property\nbecomes available only when cleartextStream.authorized === false.\n\n

\n" + }, + { + "textRaw": "cleartextStream.remoteAddress", + "name": "remoteAddress", + "desc": "

The string representation of the remote IP address. For example,\n'74.125.127.100' or '2001:4860:a005::68'.\n\n

\n" + }, + { + "textRaw": "cleartextStream.remotePort", + "name": "remotePort", + "desc": "

The numeric representation of the remote port. For example, 443.\n

\n" + } + ], + "methods": [ + { + "textRaw": "cleartextStream.getPeerCertificate()", + "type": "method", + "name": "getPeerCertificate", + "desc": "

Returns an object representing the peer's certificate. The returned object has\nsome properties corresponding to the field of the certificate.\n\n

\n

Example:\n\n

\n
{ subject: \n   { C: 'UK',\n     ST: 'Acknack Ltd',\n     L: 'Rhys Jones',\n     O: 'node.js',\n     OU: 'Test TLS Certificate',\n     CN: 'localhost' },\n  issuer: \n   { C: 'UK',\n     ST: 'Acknack Ltd',\n     L: 'Rhys Jones',\n     O: 'node.js',\n     OU: 'Test TLS Certificate',\n     CN: 'localhost' },\n  valid_from: 'Nov 11 09:52:22 2009 GMT',\n  valid_to: 'Nov  6 09:52:22 2029 GMT',\n  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF' }
\n

If the peer does not provide a certificate, it returns null or an empty\nobject.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "cleartextStream.address()", + "type": "method", + "name": "address", + "desc": "

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

\n", + "signatures": [ + { + "params": [] + } + ] + } + ] + } + ], + "type": "module", + "displayName": "TLS (SSL)" + } + ] +} --- /dev/null +++ b/doc/api/_toc.html @@ -0,0 +1,127 @@ + + + + + Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + + +
+ + + + + + + + + + --- /dev/null +++ b/doc/api/documentation.html @@ -0,0 +1,172 @@ + + + + + About this Documentation Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ +
+

Table of Contents

+ + +
+ +
+

About this Documentation#

+ + +

The goal of this documentation is to comprehensively explain the Node.js +API, both from a reference as well as a conceptual point of view. Each +section describes a built-in module or high-level concept. + +

+

Where appropriate, property types, method arguments, and the arguments +provided to event handlers are detailed in a list underneath the topic +heading. + +

+

Every .html document has a corresponding .json document presenting +the same information in a structured manner. This feature is +experimental, and added for the benefit of IDEs and other utilities that +wish to do programmatic things with the documentation. + +

+

Every .html and .json file is generated based on the corresponding +.markdown file in the doc/api/ folder in node's source tree. The +documentation is generated using the tools/doc/generate.js program. +The HTML template is located at doc/template.html. + +

+

Stability Index#

+ + +

Throughout the documentation, you will see indications of a section's +stability. The Node.js API is still somewhat changing, and as it +matures, certain parts are more reliable than others. Some are so +proven, and so relied upon, that they are unlikely to ever change at +all. Others are brand new and experimental, or known to be hazardous +and in the process of being redesigned. + +

+

The notices look like this: + +

+
Stability: 1 Experimental
+

The stability indices are as follows: + +

+
    +
  • 0 - Deprecated This feature is known to be problematic, and changes are +planned. Do not rely on it. Use of the feature may cause warnings. Backwards +compatibility should not be expected.
    • +
+
    +
  • 1 - Experimental This feature was introduced recently, and may change +or be removed in future versions. Please try it out and provide feedback. +If it addresses a use-case that is important to you, tell the node core team.
    • +
+
    +
  • 2 - Unstable The API is in the process of settling, but has not yet had +sufficient real-world testing to be considered stable. Backwards-compatibility +will be maintained if reasonable.
    • +
+
    +
  • 3 - Stable The API has proven satisfactory, but cleanup in the underlying +code may cause minor changes. Backwards-compatibility is guaranteed.
    • +
+
    +
  • 4 - API Frozen This API has been tested extensively in production and is +unlikely to ever have to change.
    • +
+
    +
  • 5 - Locked Unless serious bugs are found, this code will not ever +change. Please do not suggest changes in this area; they will be refused.
    • +
+

JSON Output#

+
Stability: 1 - Experimental
+

Every HTML file in the markdown has a corresponding JSON file with the +same data. + +

+

This feature is new as of node v0.6.12. It is experimental. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/synopsis.json @@ -0,0 +1,11 @@ +{ + "source": "doc/api/synopsis.markdown", + "miscs": [ + { + "textRaw": "Synopsis", + "name": "Synopsis", + "type": "misc", + "desc": "

An example of a web server written with Node which responds with 'Hello\nWorld':\n\n

\n
var http = require('http');\n\nhttp.createServer(function (request, response) {\n  response.writeHead(200, {'Content-Type': 'text/plain'});\n  response.end('Hello World\\n');\n}).listen(8124);\n\nconsole.log('Server running at http://127.0.0.1:8124/');
\n

To run the server, put the code into a file called example.js and execute\nit with the node program\n\n

\n
> node example.js\nServer running at http://127.0.0.1:8124/
\n

All of the examples in the documentation can be run similarly.\n

\n" + } + ] +} --- /dev/null +++ b/doc/api/https.html @@ -0,0 +1,285 @@ + + + + + HTTPS Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

HTTPS#

+
Stability: 3 - Stable
+

HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a +separate module. + +

+

Class: https.Server#

+

This class is a subclass of tls.Server and emits events same as +http.Server. See http.Server for more information. + +

+

https.createServer(options, [requestListener])#

+

Returns a new HTTPS web server object. The options is similar to +tls.createServer(). The requestListener is a function which is +automatically added to the 'request' event. + +

+

Example: + +

+
// curl -k https://localhost:8000/
+var https = require('https');
+var fs = require('fs');
+
+var options = {
+  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
+  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
+};
+
+https.createServer(options, function (req, res) {
+  res.writeHead(200);
+  res.end("hello world\n");
+}).listen(8000);
+

Or + +

+
var https = require('https');
+var fs = require('fs');
+
+var options = {
+  pfx: fs.readFileSync('server.pfx')
+};
+
+https.createServer(options, function (req, res) {
+  res.writeHead(200);
+  res.end("hello world\n");
+}).listen(8000);
+

https.request(options, callback)#

+

Makes a request to a secure web server. +All options from http.request() are valid. + +

+

Example: + +

+
var https = require('https');
+
+var options = {
+  host: 'encrypted.google.com',
+  port: 443,
+  path: '/',
+  method: 'GET'
+};
+
+var req = https.request(options, function(res) {
+  console.log("statusCode: ", res.statusCode);
+  console.log("headers: ", res.headers);
+
+  res.on('data', function(d) {
+    process.stdout.write(d);
+  });
+});
+req.end();
+
+req.on('error', function(e) {
+  console.error(e);
+});
+

The options argument has the following options + +

+
    +
  • host: IP or domain of host to make request to. Defaults to 'localhost'.
    • +
  • port: port of host to request to. Defaults to 443.
    • +
  • path: Path to request. Default '/'.
    • +

  • method: HTTP request method. Default 'GET'.

    +
    • +

  • host: A domain name or IP address of the server to issue the request to. +Defaults to 'localhost'.

    +
    • +
  • hostname: To support url.parse() hostname is preferred over host
    • +
  • port: Port of remote server. Defaults to 443.
    • +
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • +
  • path: Request path. Defaults to '/'. Should include query string if any. +E.G. '/index.html?page=12'
    • +
  • headers: An object containing request headers.
    • +
  • auth: Basic authentication i.e. 'user:password' to compute an +Authorization header.
    • +
  • agent: Controls Agent behavior. When an Agent is +used request will default to Connection: keep-alive. Possible values:
      +
    • undefined (default): use globalAgent for this +host and port.
      • +
    • Agent object: explicitly use the passed in Agent.
      • +
    • false: opts out of connection pooling with an Agent, defaults request to +Connection: close.
      • +
    +
    • +
+

The following options from tls.connect() can also be +specified. However, a globalAgent silently ignores these. + +

+
    +
  • pfx: Certificate, Private key and CA certificates to use for SSL. Default null.
    • +
  • key: Private key to use for SSL. Default null.
    • +
  • passphrase: A string of passphrase for the private key or pfx. Default null.
    • +
  • cert: Public x509 certificate to use. Default null.
    • +
  • ca: An authority certificate or array of authority certificates to check +the remote host against.
    • +
+

In order to specify these options, use a custom Agent. + +

+

Example: + +

+
var options = {
+  host: 'encrypted.google.com',
+  port: 443,
+  path: '/',
+  method: 'GET',
+  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
+  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
+};
+options.agent = new https.Agent(options);
+
+var req = https.request(options, function(res) {
+  ...
+}
+

Or does not use an Agent. + +

+

Example: + +

+
var options = {
+  host: 'encrypted.google.com',
+  port: 443,
+  path: '/',
+  method: 'GET',
+  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
+  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
+  agent: false
+};
+
+var req = https.request(options, function(res) {
+  ...
+}
+

https.get(options, callback)#

+

Like http.get() but for HTTPS. + +

+

Example: + +

+
var https = require('https');
+
+https.get({ host: 'encrypted.google.com', path: '/' }, function(res) {
+  console.log("statusCode: ", res.statusCode);
+  console.log("headers: ", res.headers);
+
+  res.on('data', function(d) {
+    process.stdout.write(d);
+  });
+
+}).on('error', function(e) {
+  console.error(e);
+});
+

Class: https.Agent#

+

An Agent object for HTTPS similar to http.Agent. +See https.request() for more information. + + +

+

https.globalAgent#

+

Global instance of https.Agent which is used as the default +for all HTTPS client requests. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/readline.json @@ -0,0 +1,154 @@ +{ + "source": "doc/api/readline.markdown", + "modules": [ + { + "textRaw": "Readline", + "name": "readline", + "stability": 3, + "stabilityText": "Stable", + "desc": "

To use this module, do require('readline'). Readline allows reading of a\nstream (such as STDIN) on a line-by-line basis.\n\n

\n

Note that once you've invoked this module, your node program will not\nterminate until you've closed the interface, and the STDIN stream. Here's how\nto allow your program to gracefully terminate:\n\n

\n
var rl = require('readline');\n\nvar i = rl.createInterface(process.stdin, process.stdout, null);\ni.question("What do you think of node.js?", function(answer) {\n  // TODO: Log the answer in a database\n  console.log("Thank you for your valuable feedback.");\n\n  // These two lines together allow the program to terminate. Without\n  // them, it would run forever.\n  i.close();\n  process.stdin.destroy();\n});
\n", + "methods": [ + { + "textRaw": "rl.createInterface(input, output, completer)", + "type": "method", + "name": "createInterface", + "desc": "

Takes two streams and creates a readline interface. The completer function\nis used for autocompletion. When given a substring, it returns [[substr1,\nsubstr2, ...], originalsubstring].\n\n

\n

Also completer can be run in async mode if it accepts two arguments:\n\n

\n

function completer(linePartial, callback) {\n callback(null, [['123'], linePartial]);\n }\n\n

\n

createInterface is commonly used with process.stdin and\nprocess.stdout in order to accept user input:\n\n

\n
var readline = require('readline'),\n  rl = readline.createInterface(process.stdin, process.stdout);
\n", + "signatures": [ + { + "params": [ + { + "name": "input" + }, + { + "name": "output" + }, + { + "name": "completer" + } + ] + } + ] + } + ], + "classes": [ + { + "textRaw": "Class: Interface", + "type": "class", + "name": "Interface", + "desc": "

The class that represents a readline interface with a stdin and stdout\nstream.\n\n

\n", + "methods": [ + { + "textRaw": "rl.setPrompt(prompt, length)", + "type": "method", + "name": "setPrompt", + "desc": "

Sets the prompt, for example when you run node on the command line, you see\n> , which is node's prompt.\n\n

\n", + "signatures": [ + { + "params": [ + { + "name": "prompt" + }, + { + "name": "length" + } + ] + } + ] + }, + { + "textRaw": "rl.prompt()", + "type": "method", + "name": "prompt", + "desc": "

Readies readline for input from the user, putting the current setPrompt\noptions on a new line, giving the user a new spot to write.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "rl.question(query, callback)", + "type": "method", + "name": "question", + "desc": "

Prepends the prompt with query and invokes callback with the user's\nresponse. Displays the query to the user, and then invokes callback with the\nuser's response after it has been typed.\n\n

\n

Example usage:\n\n

\n
interface.question('What is your favorite food?', function(answer) {\n  console.log('Oh, so your favorite food is ' + answer);\n});
\n", + "signatures": [ + { + "params": [ + { + "name": "query" + }, + { + "name": "callback" + } + ] + } + ] + }, + { + "textRaw": "rl.close()", + "type": "method", + "name": "close", + "desc": "

Closes tty.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "rl.pause()", + "type": "method", + "name": "pause", + "desc": "

Pauses tty.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "rl.resume()", + "type": "method", + "name": "resume", + "desc": "

Resumes tty.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + }, + { + "textRaw": "rl.write()", + "type": "method", + "name": "write", + "desc": "

Writes to tty.\n\n

\n", + "signatures": [ + { + "params": [] + } + ] + } + ], + "events": [ + { + "textRaw": "Event: 'line'", + "type": "event", + "name": "line", + "desc": "

function (line) {}\n\n

\n

Emitted whenever the in stream receives a \\n, usually received when the\nuser hits enter, or return. This is a good hook to listen for user input.\n\n

\n

Example of listening for line:\n\n

\n
rl.on('line', function (cmd) {\n  console.log('You just typed: '+cmd);\n});
\n", + "params": [] + }, + { + "textRaw": "Event: 'close'", + "type": "event", + "name": "close", + "desc": "

function () {}\n\n

\n

Emitted whenever the in stream receives a ^C or ^D, respectively known\nas SIGINT and EOT. This is a good way to know the user is finished using\nyour program.\n\n

\n

Example of listening for close, and exiting the program afterward:\n\n

\n
rl.on('close', function() {\n  console.log('goodbye!');\n  process.exit(0);\n});
\n

Here's an example of how to use all these together to craft a tiny command\nline interface:\n\n

\n
var readline = require('readline'),\n  rl = readline.createInterface(process.stdin, process.stdout),\n  prefix = 'OHAI> ';\n\nrl.on('line', function(line) {\n  switch(line.trim()) {\n    case 'hello':\n      console.log('world!');\n      break;\n    default:\n      console.log('Say what? I might have heard `' + line.trim() + '`');\n      break;\n  }\n  rl.setPrompt(prefix, prefix.length);\n  rl.prompt();\n}).on('close', function() {\n  console.log('Have a great day!');\n  process.exit(0);\n});\nconsole.log(prefix + 'Good to see you. Try typing stuff.');\nrl.setPrompt(prefix, prefix.length);\nrl.prompt();
\n

Take a look at this slightly more complicated\nexample, and\nhttp-console for a real-life use\ncase.\n

\n", + "params": [] + } + ] + } + ], + "type": "module", + "displayName": "Readline" + } + ] +} --- /dev/null +++ b/doc/api/debugger.html @@ -0,0 +1,237 @@ + + + + + Debugger Node.js v0.6.19 Manual & Documentation + + + + + +
+ + + +
+
+ + +
+
+

Node.js v0.6.19 Manual & Documentation

+ +
+
+ + + +
+

Debugger#

+
Stability: 3 - Stable
+ + +

V8 comes with an extensive debugger which is accessible out-of-process via a +simple TCP protocol. +Node has a built-in client for this debugger. To use this, start Node with the +debug argument; a prompt will appear: + +

+
% node debug myscript.js
+< debugger listening on port 5858
+connecting... ok
+break in /home/indutny/Code/git/indutny/myscript.js:1
+  1 x = 5;
+  2 setTimeout(function () {
+  3   debugger;
+debug>
+

Node's debugger client doesn't support the full range of commands, but +simple step and inspection is possible. By putting the statement debugger; +into the source code of your script, you will enable a breakpoint. + +

+

For example, suppose myscript.js looked like this: + +

+
// myscript.js
+x = 5;
+setTimeout(function () {
+  debugger;
+  console.log("world");
+}, 1000);
+console.log("hello");
+

Then once the debugger is run, it will break on line 4. + +

+
% node debug myscript.js
+< debugger listening on port 5858
+connecting... ok
+break in /home/indutny/Code/git/indutny/myscript.js:1
+  1 x = 5;
+  2 setTimeout(function () {
+  3   debugger;
+debug> cont
+< hello
+break in /home/indutny/Code/git/indutny/myscript.js:3
+  1 x = 5;
+  2 setTimeout(function () {
+  3   debugger;
+  4   console.log("world");
+  5 }, 1000);
+debug> next
+break in /home/indutny/Code/git/indutny/myscript.js:4
+  2 setTimeout(function () {
+  3   debugger;
+  4   console.log("world");
+  5 }, 1000);
+  6 console.log("hello");
+debug> repl
+Press Ctrl + C to leave debug repl
+> x
+5
+> 2+2
+4
+debug> next
+< world
+break in /home/indutny/Code/git/indutny/myscript.js:5
+  3   debugger;
+  4   console.log("world");
+  5 }, 1000);
+  6 console.log("hello");
+  7
+debug> quit
+%
+

The repl command allows you to evaluate code remotely. The next command +steps over to the next line. There are a few other commands available and more +to come. Type help to see others. + +

+

Watchers#

+

You can watch expression and variable values while debugging your code. +On every breakpoint each expression from the watchers list will be evaluated +in the current context and displayed just before the breakpoint's source code +listing. + +

+

To start watching an expression, type watch("my_expression"). watchers +prints the active watchers. To remove a watcher, type +unwatch("my_expression"). + +

+

Commands reference#

+

Stepping#

+
    +
  • cont, c - Continue execution
    • +
  • next, n - Step next
    • +
  • step, s - Step in
    • +
  • out, o - Step out
    • +
+

Breakpoints#

+
    +
  • setBreakpoint(), sb() - Set breakpoint on current line
    • +
  • setBreakpoint('fn()'), sb(...) - Set breakpoint on a first statement in +functions body
    • +
  • setBreakpoint('script.js', 1), sb(...) - Set breakpoint on first line of +script.js
    • +
  • clearBreakpoint, cb(...) - Clear breakpoint
    • +
+

Info#

+
    +
  • backtrace, bt - Print backtrace of current execution frame
    • +
  • list(5) - List scripts source code with 5 line context (5 lines before and +after)
    • +
  • watch(expr) - Add expression to watch list
    • +
  • unwatch(expr) - Remove expression from watch list
    • +
  • watchers - List all watchers and their values (automatically listed on each +breakpoint)
    • +
  • repl - Open debugger's repl for evaluation in debugging script's context
    • +
+

Execution control#

+
    +
  • run - Run script (automatically runs on debugger's start)
    • +
  • restart - Restart script
    • +
  • kill - Kill script
    • +
+

Various#

+
    +
  • scripts - List all loaded scripts
    • +
  • version - Display v8's version
    • +
+

Advanced Usage#

+

The V8 debugger can be enabled and accessed either by starting Node with +the --debug command-line flag or by signaling an existing Node process +with SIGUSR1. +

+ +
+
+
+ + + + + + + + + + --- /dev/null +++ b/doc/api/assets/sh.css @@ -0,0 +1,23 @@ +.sh_sourceCode { + font-weight: normal; + font-style: normal; +} + +.sh_sourceCode .sh_symbol , .sh_sourceCode .sh_cbracket { + color: #333; +} + +.sh_sourceCode .sh_keyword { + color: #c96; +} + +.sh_sourceCode .sh_string, .sh_sourceCode .sh_regexp, .sh_sourceCode .sh_number, +.sh_sourceCode .sh_specialchar +{ + color: #690; +} + +.sh_sourceCode .sh_comment { + color: #666; +} + --- /dev/null +++ b/doc/api/assets/style.css @@ -0,0 +1,493 @@ +/*--------------------- Layout and Typography ----------------------------*/ +html { + -webkit-font-smoothing: antialiased; +} + +body { + font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif; + font-size: 14px; + line-height: 180%; + color: black; + margin: 0; padding: 49px 0 0 0; + border-top: 6px #8CC84B solid; +} +a { + color: #480; + text-decoration: underline; +} + a:visited { + color: #46483e; + text-decoration: underline; + } + a:hover, a:focus { + text-decoration: none; + } + + code a:hover { + background: none; + color: #b950b7; + } + +#changelog #gtoc { + display: none; +} + +#gtoc p { + margin:0; + font-size:18px; + line-height: 30px; +} + +#gtoc a { + font-family: Georgia, FreeSerif, Times, serif; + text-decoration: none; + color: #46483e; +} + +#gtoc a:hover { + color: #669900; + text-decoration: underline; +} + +.notice { + display: block; + padding: 1em; + margin: 1.4667em 0 2.9334em; + background:#FFF6BF; + color:#514721; + border:1px solid #FFD324; +} + .notice p { + margin: 0; + } + +ul.plain { + list-style: none; +} + +abbr { + border-bottom: 1px dotted #454545; +} + +p { + margin: 0 0 1.4667em 0; + position: relative; + text-rendering: optimizeLegibility; +} + +.apidoc #apicontent p, .apidoc #apicontent li { + font-size: 15px; + line-height: 22px; + color: #000; + font-family: Georgia, FreeSerif, Times, serif; +} + +ol, ul, dl { + margin: 0 0 1em 0; + padding: 0; +} + +ol ul, ol ol, ol dl, +ul ul, ul ol, ul dl, +dl ul, dl ol, dl dl { + margin-bottom: 0; +} + +ol p:first-child, ul p:first-child, dl p:first-child { + margin-bottom: 0; +} + +ul, ol { + margin-left: 2em; +} + + +dl dt { + position: relative; + margin: 1.5em 0 0; +} + +dl dd { + position: relative; + margin: 0 1em 0; +} + +dd + dt.pre { + margin-top: 1.6em; +} + +h1, h2, h3, h4, h5, h6 { + font-family: Helvetica, Arial, sans-serif; + color: #000; + text-rendering: optimizeLegibility; + position: relative; +} + +header h1 { + font-family: Georgia, FreeSerif, Times, serif; + font-size: 30px; + font-weight: normal; + line-height: 36px; + color: #480; + margin: 15px 0 11px; +} + +h1 { + font-size: 29px; + line-height: 33px; + margin: 2em 0 15px; +} + +#toc + h1 { + margin-top:1em; + padding-top:0; +} + +h2 { + font-size: 1.4em; + line-height: 1.0909em; + margin: 1.5em 0 0.5em; +} + +h2 + h2 { + margin: 0 0 0.5em; +} + +h3 { + font-size: 1.3em; + line-height: 1.1282em; + margin: 2.2em 0 0.5em; +} + +h3 + h3 { + margin: 0 0 0.5em; +} + + h2, h3, h4 { + position:relative; + padding-right:40px; + } + h1 span, h2 span, h3 span, h4 span { + font-size:25px; + position:absolute; + display:block; + top:0; + right:0; + opacity: 0.3; + } + h1 span:hover, h2 span:hover, h3 span:hover, h4 span:hover { + opacity: 1; + } + h1 span a, h2 span a, h3 span a, h4 span a { + font-size: 0.8em; + color: #000; + text-decoration: none; + font-family: Helvetica, Arial, sans-serif; + font-weight:bold; + } + + h1 span a.top, h3 span a.top, h3 span a.top, h4 span a.top { + /* XXX Get an image and clean up these two links + * so that they look nice next to one another. + * http://www.chrisglass.com/work/nodejs/website/v05/docs.html + * -isaacs + */ + display:none; + } + +h5 { + font-size: 1.125em; + line-height: 1.4em; +} + +h6 { + font-size: 1em; + line-height: 1.4667em; +} + + pre, tt, code { + font-size: 14px; + line-height: 1.5438em; + font-family: Monaco, Consolas, "Lucida Console", monospace; + margin: 0; padding: 0; + } + + .pre { + font-family: Monaco, Consolas, "Lucida Console", monospace; + line-height: 1.5438em; + font-size: 0.95em; + } + + pre { + padding: 1em 1.6em 1em 1.2em; + vertical-align: top; + background: #f8f8f8; + border: 1px solid #e8e8e8; + border-width: 1px 1px 1px 6px; + margin: -0.5em 0 1.1em; + overflow-x:auto; + } + + pre + h3 { + margin-top: 2.225em; + } + +code.pre { + white-space: pre; +} + +#intro { + width: 775px; + margin: 0 auto; + text-align: center; + color: #d2d8ba; + + /* preload platform-icons.png */ + background-image: url(http://nodejs.org/images/platform-icons.png); + background-repeat: no-repeat; + background-position: -999em -999em; +} + +#intro.interior #logo { + margin-left: -298px; + border:0; +} + +hr { + background: none; + border: medium none; + border-bottom: 1px solid #ccc; + margin: 1em 0; +} + +#toc { + font-size:15px; + line-height:1.5em; + line-height: 22px; + padding-top:4px; +} + + #toc h2 { + font-size: 15px; + line-height: 21px; + margin: 0 0 0.5em; + } + + #toc h2 a { + float: right; + } + + #toc hr { + margin: 1em 0 2em; + } + + #toc ul, #api-section-index #apicontent ul li, #api-section-index #apicontent ul { + font-family: Georgia, FreeSerif, Times, serif; + color:#666!important; + } + + #toc ul a { + text-decoration:none; + border-bottom:1px dotted #480; + } + #toc ul a:hover, #toc ul a:focus { + border-bottom:1px dotted #fff; + color:#000; + } + + +p tt, p code { + background: #f8f8ff; + border: 1px solid #dedede; + padding: 0 0.2em; +} + +#content { + width: 953px; + margin: 0 auto; + overflow: visible; + clear: both; + display: block; +} + +#column1.interior { + width: 749px; + float: right; + padding-top: 7px; + padding-top: 11px; + font-size:18px; +} + +#column2.interior { + width: 140px; + float: left; + margin-top: -55px; + overflow: visible; +} + +#column2.interior ul { + margin-left: 0; +} + +#column2.interior li { + list-style-type: none; +} + +#column2.interior li a { + display: block; + padding: 0 0 0 35px; + color: #878b78; + text-transform: uppercase; + text-decoration: none; + font-size: 11px; + line-height: 23px; +} + +#column2.interior li a.home { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px 3px; } +#column2.interior li a.download { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -21px; } +#column2.interior li a.about { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -45px; } +#column2.interior li a.npm { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -69px; } +#column2.interior li a.docs { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -93px; } +#column2.interior li a.blog { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -117px; } +#column2.interior li a.community { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -141px; } +#column2.interior li a.logos { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -165px; } +#column2.interior li a.jobs { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -189px; } + +#column2.interior li a.home.current { background-position: 2px 3px; } +#column2.interior li a.download.current { background-position: 2px -21px; } +#column2.interior li a.about.current { background-position: 2px -45px; } +#column2.interior li a.npm.current { background-position: 2px -69px; } +#column2.interior li a.docs.current { background-position: 2px -93px; } +#column2.interior li a.blog.current { background-position: 2px -117px; } +#column2.interior li a.community.current { background-position: 2px -141px; } +#column2.interior li a.logos.current { background-position: 2px -165px; } +#column2.interior li a.jobs.current { background-position: 2px -189px; } +#column2.interior li a.current { color: #8cc84b; font-weight: bold; } + +#column2.interior li a.home:hover { background-position: -331px 3px; } +#column2.interior li a.download:hover { background-position: -331px -21px; } +#column2.interior li a.about:hover { background-position: -331px -45px; } +#column2.interior li a.npm:hover { background-position: -331px -69px; } +#column2.interior li a.docs:hover { background-position: -331px -93px; } +#column2.interior li a.blog:hover { background-position: -331px -117px; } +#column2.interior li a.community:hover { background-position: -331px -141px; } +#column2.interior li a.logos:hover { background-position: -331px -165px; } +#column2.interior li a.jobs:hover { background-position: -331px -189px; } +#column2.interior li a:hover { color: #000000; text-decoration: none; } + +#column2.interior li + li { + border-top: 1px solid #c1c7ac; +} +#column2.interior p.twitter { + padding-top: 20px; +} + +#column2.interior p.twitter a { + background: url(http://nodejs.org/images/twitter-bird.png) no-repeat 0 4px; + padding-left: 37px; + text-decoration: none; +} + +#column2.interior p.twitter a:hover { + text-decoration: underline; +} + +a.totop { + font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif; + font-weight: bold; + text-indent: -9999999px; + background: url(http://nodejs.org/images/anchor.png) no-repeat top left; + margin-right: 7px; + display: block; + width: 13px; + border-bottom: 1px solid #cccccc; +} + +a.anchor { + font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif; + font-weight: bold; + text-indent: -9999999px; + background: url(http://nodejs.org/images/anchor.png) no-repeat top right; + display: block; + width: 13px; + border-bottom: 1px solid #cccccc; +} +#footer { + width: 942px; + margin: 150px auto 55px auto; + padding:0; +} + +#footer p { + font-size: 11px; + line-height:1em; + padding: 0 0 0 195px; + color: #666; +} + +#footer p, #footer li { + font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif; +} + +#footer a { + text-decoration:none; + border:none; + color: #480; +} +#footer a:hover { + color:#000; +} + +#footer p a { + border-bottom:1px dotted #480; + color: #878b78; +} + +#footer ul { + background: url(http://nodejs.org/images/footer-logo-alt.png) left 17px no-repeat; + padding: 23px 0 0 195px; + height: 26px; + margin-left: -1px; + border-top: 1px solid #626557; +} + +#footer ul li { + list-style-type: none; + float: left; + font-size: 12px; + margin:0!important; + padding:0; + height: 12px; +} + +#footer ul li a { + margin: 0; + padding: 0 6px 0 0; + display: block; + height:12px; + line-height:12px; +} + +#footer ul li + li { + margin-left: 3px; +} + +#footer ul li + li a { + padding: 0 6px 0 6px; + border-left: 1px solid #878b78; +} + +#footer ul li a.twitter { + background: url(http://nodejs.org/images/twitter-bird.png) no-repeat 5px 0px; + padding-left: 25px; +} + +/* simpler clearfix */ +.clearfix:after { + content: "."; + display: block; + height: 0; + clear: both; + visibility: hidden; +} + --- a/doc/api/api/_toc.html +++ /dev/null @@ -1,127 +0,0 @@ - - - - - Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - - -
- - - - - - - - - - --- a/doc/api/api/_toc.json +++ /dev/null @@ -1,379 +0,0 @@ -{ - "source": "doc/api/_toc.markdown", - "desc": [ - { - "type": "list_start", - "ordered": false - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[About these Docs](documentation.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Synopsis](synopsis.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Globals](globals.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[STDIO](stdio.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Timers](timers.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Modules](modules.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[C/C++ Addons](addons.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Process](process.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Utilities](util.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Events](events.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Buffer](buffer.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Stream](stream.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Crypto](crypto.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[TLS/SSL](tls.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[String Decoder](string_decoder.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[File System](fs.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Path](path.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Net](net.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[UDP/Datagram](dgram.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[DNS](dns.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[HTTP](http.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[HTTPS](https.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[URL](url.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Query Strings](querystring.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Readline](readline.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[REPL](repl.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[VM](vm.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Child Processes](child_process.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Assertion Testing](assert.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[TTY](tty.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[ZLIB](zlib.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[OS](os.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Debugger](debugger.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Cluster](cluster.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "Appendixes" - }, - { - "type": "list_start", - "ordered": false - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Appendix 1: Recommended Third-party Modules](appendix_1.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_end" - }, - { - "type": "list_item_end" - }, - { - "type": "list_end" - } - ] -} --- a/doc/api/api/addons.html +++ /dev/null @@ -1,725 +0,0 @@ - - - - - Addons Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Addons#

-

Addons are dynamically linked shared objects. They can provide glue to C and -C++ libraries. The API (at the moment) is rather complex, involving -knowledge of several libraries: - -

-
    -

  • V8 JavaScript, a C++ library. Used for interfacing with JavaScript: -creating objects, calling functions, etc. Documented mostly in the -v8.h header file (deps/v8/include/v8.h in the Node source tree), -which is also available online.

    -
    • -

  • libuv, C event loop library. Anytime one -needs to wait for a file descriptor to become readable, wait for a timer, or -wait for a signal to received one will need to interface with libuv. That is, -if you perform any I/O, libuv will need to be used.

    -
    • -

  • Internal Node libraries. Most importantly is the node::ObjectWrap -class which you will likely want to derive from.

    -
    • -

  • Others. Look in deps/ for what else is available.

    -
    • -
-

Node statically compiles all its dependencies into the executable. When -compiling your module, you don't need to worry about linking to any of these -libraries. - - -

-

Hello world#

-

To get started let's make a small Addon which is the C++ equivalent of -the following Javascript code: - -

-
exports.hello = function() { return 'world'; };
-

First we create a file hello.cc: - -

-
#include <node.h>
-#include <v8.h>
-
-using namespace v8;
-
-Handle<Value> Method(const Arguments& args) {
-  HandleScope scope;
-  return scope.Close(String::New("world"));
-}
-
-void init(Handle<Object> target) {
-  target->Set(String::NewSymbol("hello"),
-      FunctionTemplate::New(Method)->GetFunction());
-}
-NODE_MODULE(hello, init)
-

Note that all Node addons must export an initialization function: - -

-
void Initialize (Handle<Object> target);
-NODE_MODULE(module_name, Initialize)
-

There is no semi-colon after NODE_MODULE as it's not a function (see node.h). - -

-

The module_name needs to match the filename of the final binary (minus the -.node suffix). - -

-

The source code needs to be built into hello.node, the binary Addon. To -do this we create a file called wscript which is python code and looks -like this: - -

-
srcdir = '.'
-blddir = 'build'
-VERSION = '0.0.1'
-
-def set_options(opt):
-  opt.tool_options('compiler_cxx')
-
-def configure(conf):
-  conf.check_tool('compiler_cxx')
-  conf.check_tool('node_addon')
-
-def build(bld):
-  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
-  obj.target = 'hello'
-  obj.source = 'hello.cc'
-

Running node-waf configure build will create a file -build/default/hello.node which is our Addon. - -

-

node-waf is just WAF, the python-based build system. node-waf is -provided for the ease of users. - -

-

You can now use the binary addon in a Node project hello.js by pointing require to -the recently built module: - -

-
var addon = require('./build/Release/hello');
-
-console.log(addon.hello()); // 'world'
-

Please see patterns below for further information or -

-

https://github.com/pietern/hiredis-node for an example in production. - - -

-

Addon patterns#

-

Below are some addon patterns to help you get started. Consult the online -v8 reference for help with the various v8 -calls, and v8's Embedder's Guide -for an explanation of several concepts used such as handles, scopes, -function templates, etc. - -

-

To compile these examples, create the wscript file below and run -node-waf configure build: - -

-
srcdir = '.'
-blddir = 'build'
-VERSION = '0.0.1'
-
-def set_options(opt):
-  opt.tool_options('compiler_cxx')
-
-def configure(conf):
-  conf.check_tool('compiler_cxx')
-  conf.check_tool('node_addon')
-
-def build(bld):
-  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
-  obj.target = 'addon'
-  obj.source = ['addon.cc']
-

In cases where there is more than one .cc file, simply add the file name to the -obj.source array, e.g.: - -

-
obj.source = ['addon.cc', 'myexample.cc']
-

Function arguments#

-

The following pattern illustrates how to read arguments from JavaScript -function calls and return a result. This is the main and only needed source -addon.cc: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-
-using namespace v8;
-
-Handle<Value> Add(const Arguments& args) {
-  HandleScope scope;
-
-  if (args.Length() < 2) {
-    ThrowException(Exception::TypeError(String::New("Wrong number of arguments")));
-    return scope.Close(Undefined());
-  }
-
-  if (!args[0]->IsNumber() || !args[1]->IsNumber()) {
-    ThrowException(Exception::TypeError(String::New("Wrong arguments")));
-    return scope.Close(Undefined());
-  }
-
-  Local<Number> num = Number::New(args[0]->NumberValue() +
-      args[1]->NumberValue());
-  return scope.Close(num);
-}
-
-void Init(Handle<Object> target) {
-  target->Set(String::NewSymbol("add"),
-      FunctionTemplate::New(Add)->GetFunction());
-}
-
-NODE_MODULE(addon, Init)
-

You can test it with the following JavaScript snippet: - -

-
var addon = require('./build/Release/addon');
-
-console.log( 'This should be eight:', addon.add(3,5) );
-

Callbacks#

-

You can pass JavaScript functions to a C++ function and execute them from -there. Here's addon.cc: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-
-using namespace v8;
-
-Handle<Value> RunCallback(const Arguments& args) {
-  HandleScope scope;
-
-  Local<Function> cb = Local<Function>::Cast(args[0]);
-  const unsigned argc = 1;
-  Local<Value> argv[argc] = { Local<Value>::New(String::New("hello world")) };
-  cb->Call(Context::GetCurrent()->Global(), argc, argv);
-
-  return scope.Close(Undefined());
-}
-
-void Init(Handle<Object> target) {
-  target->Set(String::NewSymbol("runCallback"),
-      FunctionTemplate::New(RunCallback)->GetFunction());
-}
-
-NODE_MODULE(addon, Init)
-

To test it run the following JavaScript snippet: - -

-
var addon = require('./build/Release/addon');
-
-addon.runCallback(function(msg){
-  console.log(msg); // 'hello world'
-});
-

Object factory#

-

You can create and return new objects from within a C++ function with this -addon.cc pattern, which returns an object with property msg that echoes -the string passed to createObject(): - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-
-using namespace v8;
-
-Handle<Value> CreateObject(const Arguments& args) {
-  HandleScope scope;
-
-  Local<Object> obj = Object::New();
-  obj->Set(String::NewSymbol("msg"), args[0]->ToString());
-
-  return scope.Close(obj);
-}
-
-void Init(Handle<Object> target) {
-  target->Set(String::NewSymbol("createObject"),
-      FunctionTemplate::New(CreateObject)->GetFunction());
-}
-
-NODE_MODULE(addon, Init)
-

To test it in JavaScript: - -

-
var addon = require('./build/Release/addon');
-
-var obj1 = addon.createObject('hello');
-var obj2 = addon.createObject('world');
-console.log(obj1.msg+' '+obj2.msg); // 'hello world'
-

Function factory#

-

This pattern illustrates how to create and return a JavaScript function that -wraps a C++ function: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-
-using namespace v8;
-
-Handle<Value> MyFunction(const Arguments& args) {
-  HandleScope scope;
-  return scope.Close(String::New("hello world"));
-}
-
-Handle<Value> CreateFunction(const Arguments& args) {
-  HandleScope scope;
-
-  Local<FunctionTemplate> tpl = FunctionTemplate::New(MyFunction);
-  Local<Function> fn = tpl->GetFunction();
-  fn->SetName(String::NewSymbol("theFunction")); // omit this to make it anonymous
-
-  return scope.Close(fn);
-}
-
-void Init(Handle<Object> target) {
-  target->Set(String::NewSymbol("createFunction"),
-      FunctionTemplate::New(CreateFunction)->GetFunction());
-}
-
-NODE_MODULE(addon, Init)
-

To test: - -

-
var addon = require('./build/Release/addon');
-
-var fn = addon.createFunction();
-console.log(fn()); // 'hello world'
-

Wrapping C++ objects#

-

Here we will create a wrapper for a C++ object/class MyObject that can be -instantiated in JavaScript through the new operator. First prepare the main -module addon.cc: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-void InitAll(Handle<Object> target) {
-  MyObject::Init(target);
-}
-
-NODE_MODULE(addon, InitAll)
-

Then in myobject.h make your wrapper inherit from node::ObjectWrap: - -

-
#ifndef MYOBJECT_H
-#define MYOBJECT_H
-
-#include <node.h>
-
-class MyObject : public node::ObjectWrap {
- public:
-  static void Init(v8::Handle<v8::Object> target);
-
- private:
-  MyObject();
-  ~MyObject();
-
-  static v8::Handle<v8::Value> New(const v8::Arguments& args);
-  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);
-  double counter_;
-};
-
-#endif
-

And in myobject.cc implement the various methods that you want to expose. -Here we expose the method plusOne by adding it to the constructor's -prototype: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-MyObject::MyObject() {};
-MyObject::~MyObject() {};
-
-void MyObject::Init(Handle<Object> target) {
-  // Prepare constructor template
-  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
-  tpl->SetClassName(String::NewSymbol("MyObject"));
-  tpl->InstanceTemplate()->SetInternalFieldCount(1);
-  // Prototype
-  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),
-      FunctionTemplate::New(PlusOne)->GetFunction());
-
-  Persistent<Function> constructor = Persistent<Function>::New(tpl->GetFunction());
-  target->Set(String::NewSymbol("MyObject"), constructor);
-}
-
-Handle<Value> MyObject::New(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj = new MyObject();
-  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
-  obj->Wrap(args.This());
-
-  return args.This();
-}
-
-Handle<Value> MyObject::PlusOne(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());
-  obj->counter_ += 1;
-
-  return scope.Close(Number::New(obj->counter_));
-}
-

Test it with: - -

-
var addon = require('./build/Release/addon');
-
-var obj = new addon.MyObject(10);
-console.log( obj.plusOne() ); // 11
-console.log( obj.plusOne() ); // 12
-console.log( obj.plusOne() ); // 13
-

Factory of wrapped objects#

-

This is useful when you want to be able to create native objects without -explicitly instantiating them with the new operator in JavaScript, e.g. - -

-
var obj = addon.createObject();
-// instead of:
-// var obj = new addon.Object();
-

Let's register our createObject method in addon.cc: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-Handle<Value> CreateObject(const Arguments& args) {
-  HandleScope scope;
-  return scope.Close(MyObject::NewInstance(args));
-}
-
-void InitAll(Handle<Object> target) {
-  MyObject::Init();
-
-  target->Set(String::NewSymbol("createObject"),
-      FunctionTemplate::New(CreateObject)->GetFunction());
-}
-
-NODE_MODULE(addon, InitAll)
-

In myobject.h we now introduce the static method NewInstance that takes -care of instantiating the object (i.e. it does the job of new in JavaScript): - -

-
#define BUILDING_NODE_EXTENSION
-#ifndef MYOBJECT_H
-#define MYOBJECT_H
-
-#include <node.h>
-
-class MyObject : public node::ObjectWrap {
- public:
-  static void Init();
-  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);
-
- private:
-  MyObject();
-  ~MyObject();
-
-  static v8::Persistent<v8::Function> constructor;
-  static v8::Handle<v8::Value> New(const v8::Arguments& args);
-  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);
-  double counter_;
-};
-
-#endif
-

The implementation is similar to the above in myobject.cc: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-MyObject::MyObject() {};
-MyObject::~MyObject() {};
-
-Persistent<Function> MyObject::constructor;
-
-void MyObject::Init() {
-  // Prepare constructor template
-  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
-  tpl->SetClassName(String::NewSymbol("MyObject"));
-  tpl->InstanceTemplate()->SetInternalFieldCount(1);
-  // Prototype
-  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),
-      FunctionTemplate::New(PlusOne)->GetFunction());
-
-  constructor = Persistent<Function>::New(tpl->GetFunction());
-}
-
-Handle<Value> MyObject::New(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj = new MyObject();
-  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
-  obj->Wrap(args.This());
-
-  return args.This();
-}
-
-Handle<Value> MyObject::NewInstance(const Arguments& args) {
-  HandleScope scope;
-
-  const unsigned argc = 1;
-  Handle<Value> argv[argc] = { args[0] };
-  Local<Object> instance = constructor->NewInstance(argc, argv);
-
-  return scope.Close(instance);
-}
-
-Handle<Value> MyObject::PlusOne(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());
-  obj->counter_ += 1;
-
-  return scope.Close(Number::New(obj->counter_));
-}
-

Test it with: - -

-
var addon = require('./build/Release/addon');
-
-var obj = addon.createObject(10);
-console.log( obj.plusOne() ); // 11
-console.log( obj.plusOne() ); // 12
-console.log( obj.plusOne() ); // 13
-
-var obj2 = addon.createObject(20);
-console.log( obj2.plusOne() ); // 21
-console.log( obj2.plusOne() ); // 22
-console.log( obj2.plusOne() ); // 23
-

Passing wrapped objects around#

-

In addition to wrapping and returning C++ objects, you can pass them around -by unwrapping them with Node's node::ObjectWrap::Unwrap helper function. -In the following addon.cc we introduce a function add() that can take on two -MyObject objects: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-Handle<Value> CreateObject(const Arguments& args) {
-  HandleScope scope;
-  return scope.Close(MyObject::NewInstance(args));
-}
-
-Handle<Value> Add(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(
-      args[0]->ToObject());
-  MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(
-      args[1]->ToObject());
-
-  double sum = obj1->Val() + obj2->Val();
-  return scope.Close(Number::New(sum));
-}
-
-void InitAll(Handle<Object> target) {
-  MyObject::Init();
-
-  target->Set(String::NewSymbol("createObject"),
-      FunctionTemplate::New(CreateObject)->GetFunction());
-
-  target->Set(String::NewSymbol("add"),
-      FunctionTemplate::New(Add)->GetFunction());
-}
-
-NODE_MODULE(addon, InitAll)
-

To make things interesting we introduce a public method in myobject.h so we -can probe private values after unwrapping the object: - -

-
#define BUILDING_NODE_EXTENSION
-#ifndef MYOBJECT_H
-#define MYOBJECT_H
-
-#include <node.h>
-
-class MyObject : public node::ObjectWrap {
- public:
-  static void Init();
-  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);
-  double Val() const { return val_; }
-
- private:
-  MyObject();
-  ~MyObject();
-
-  static v8::Persistent<v8::Function> constructor;
-  static v8::Handle<v8::Value> New(const v8::Arguments& args);
-  double val_;
-};
-
-#endif
-

The implementation of myobject.cc is similar as before: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-MyObject::MyObject() {};
-MyObject::~MyObject() {};
-
-Persistent<Function> MyObject::constructor;
-
-void MyObject::Init() {
-  // Prepare constructor template
-  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
-  tpl->SetClassName(String::NewSymbol("MyObject"));
-  tpl->InstanceTemplate()->SetInternalFieldCount(1);
-
-  constructor = Persistent<Function>::New(tpl->GetFunction());
-}
-
-Handle<Value> MyObject::New(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj = new MyObject();
-  obj->val_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
-  obj->Wrap(args.This());
-
-  return args.This();
-}
-
-Handle<Value> MyObject::NewInstance(const Arguments& args) {
-  HandleScope scope;
-
-  const unsigned argc = 1;
-  Handle<Value> argv[argc] = { args[0] };
-  Local<Object> instance = constructor->NewInstance(argc, argv);
-
-  return scope.Close(instance);
-}
-

Test it with: - -

-
var addon = require('./build/Release/addon');
-
-var obj1 = addon.createObject(10);
-var obj2 = addon.createObject(20);
-var result = addon.add(obj1, obj2);
-
-console.log(result); // 30
- -
-
-
- - - - - - - - - - --- a/doc/api/api/addons.json +++ /dev/null @@ -1,79 +0,0 @@ -{ - "source": "doc/api/addons.markdown", - "modules": [ - { - "textRaw": "Addons", - "name": "addons", - "desc": "

Addons are dynamically linked shared objects. They can provide glue to C and\nC++ libraries. The API (at the moment) is rather complex, involving\nknowledge of several libraries:\n\n

\n
    \n

  • V8 JavaScript, a C++ library. Used for interfacing with JavaScript:\ncreating objects, calling functions, etc. Documented mostly in the\nv8.h header file (deps/v8/include/v8.h in the Node source tree),\nwhich is also available online.

    \n
    • \n

  • libuv, C event loop library. Anytime one\nneeds to wait for a file descriptor to become readable, wait for a timer, or\nwait for a signal to received one will need to interface with libuv. That is,\nif you perform any I/O, libuv will need to be used.

    \n
    • \n

  • Internal Node libraries. Most importantly is the node::ObjectWrap\nclass which you will likely want to derive from.

    \n
    • \n

  • Others. Look in deps/ for what else is available.

    \n
    • \n
\n

Node statically compiles all its dependencies into the executable. When\ncompiling your module, you don't need to worry about linking to any of these\nlibraries.\n\n\n

\n", - "modules": [ - { - "textRaw": "Hello world", - "name": "hello_world", - "desc": "

To get started let's make a small Addon which is the C++ equivalent of\nthe following Javascript code:\n\n

\n
exports.hello = function() { return 'world'; };
\n

First we create a file hello.cc:\n\n

\n
#include <node.h>\n#include <v8.h>\n\nusing namespace v8;\n\nHandle<Value> Method(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(String::New("world"));\n}\n\nvoid init(Handle<Object> target) {\n  target->Set(String::NewSymbol("hello"),\n      FunctionTemplate::New(Method)->GetFunction());\n}\nNODE_MODULE(hello, init)
\n

Note that all Node addons must export an initialization function:\n\n

\n
void Initialize (Handle<Object> target);\nNODE_MODULE(module_name, Initialize)
\n

There is no semi-colon after NODE_MODULE as it's not a function (see node.h).\n\n

\n

The module_name needs to match the filename of the final binary (minus the\n.node suffix).\n\n

\n

The source code needs to be built into hello.node, the binary Addon. To\ndo this we create a file called wscript which is python code and looks\nlike this:\n\n

\n
srcdir = '.'\nblddir = 'build'\nVERSION = '0.0.1'\n\ndef set_options(opt):\n  opt.tool_options('compiler_cxx')\n\ndef configure(conf):\n  conf.check_tool('compiler_cxx')\n  conf.check_tool('node_addon')\n\ndef build(bld):\n  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')\n  obj.target = 'hello'\n  obj.source = 'hello.cc'
\n

Running node-waf configure build will create a file\nbuild/default/hello.node which is our Addon.\n\n

\n

node-waf is just WAF, the python-based build system. node-waf is\nprovided for the ease of users.\n\n

\n

You can now use the binary addon in a Node project hello.js by pointing require to\nthe recently built module:\n\n

\n
var addon = require('./build/Release/hello');\n\nconsole.log(addon.hello()); // 'world'
\n

Please see patterns below for further information or\n

\n

https://github.com/pietern/hiredis-node for an example in production.\n\n\n

\n", - "type": "module", - "displayName": "Hello world" - }, - { - "textRaw": "Addon patterns", - "name": "addon_patterns", - "desc": "

Below are some addon patterns to help you get started. Consult the online\nv8 reference for help with the various v8\ncalls, and v8's Embedder's Guide\nfor an explanation of several concepts used such as handles, scopes,\nfunction templates, etc.\n\n

\n

To compile these examples, create the wscript file below and run\nnode-waf configure build:\n\n

\n
srcdir = '.'\nblddir = 'build'\nVERSION = '0.0.1'\n\ndef set_options(opt):\n  opt.tool_options('compiler_cxx')\n\ndef configure(conf):\n  conf.check_tool('compiler_cxx')\n  conf.check_tool('node_addon')\n\ndef build(bld):\n  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')\n  obj.target = 'addon'\n  obj.source = ['addon.cc']
\n

In cases where there is more than one .cc file, simply add the file name to the\nobj.source array, e.g.:\n\n

\n
obj.source = ['addon.cc', 'myexample.cc']
\n", - "modules": [ - { - "textRaw": "Function arguments", - "name": "function_arguments", - "desc": "

The following pattern illustrates how to read arguments from JavaScript\nfunction calls and return a result. This is the main and only needed source\naddon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> Add(const Arguments& args) {\n  HandleScope scope;\n\n  if (args.Length() < 2) {\n    ThrowException(Exception::TypeError(String::New("Wrong number of arguments")));\n    return scope.Close(Undefined());\n  }\n\n  if (!args[0]->IsNumber() || !args[1]->IsNumber()) {\n    ThrowException(Exception::TypeError(String::New("Wrong arguments")));\n    return scope.Close(Undefined());\n  }\n\n  Local<Number> num = Number::New(args[0]->NumberValue() +\n      args[1]->NumberValue());\n  return scope.Close(num);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("add"),\n      FunctionTemplate::New(Add)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

You can test it with the following JavaScript snippet:\n\n

\n
var addon = require('./build/Release/addon');\n\nconsole.log( 'This should be eight:', addon.add(3,5) );
\n", - "type": "module", - "displayName": "Function arguments" - }, - { - "textRaw": "Callbacks", - "name": "callbacks", - "desc": "

You can pass JavaScript functions to a C++ function and execute them from\nthere. Here's addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> RunCallback(const Arguments& args) {\n  HandleScope scope;\n\n  Local<Function> cb = Local<Function>::Cast(args[0]);\n  const unsigned argc = 1;\n  Local<Value> argv[argc] = { Local<Value>::New(String::New("hello world")) };\n  cb->Call(Context::GetCurrent()->Global(), argc, argv);\n\n  return scope.Close(Undefined());\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("runCallback"),\n      FunctionTemplate::New(RunCallback)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test it run the following JavaScript snippet:\n\n

\n
var addon = require('./build/Release/addon');\n\naddon.runCallback(function(msg){\n  console.log(msg); // 'hello world'\n});
\n", - "type": "module", - "displayName": "Callbacks" - }, - { - "textRaw": "Object factory", - "name": "object_factory", - "desc": "

You can create and return new objects from within a C++ function with this\naddon.cc pattern, which returns an object with property msg that echoes\nthe string passed to createObject():\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n\n  Local<Object> obj = Object::New();\n  obj->Set(String::NewSymbol("msg"), args[0]->ToString());\n\n  return scope.Close(obj);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test it in JavaScript:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj1 = addon.createObject('hello');\nvar obj2 = addon.createObject('world');\nconsole.log(obj1.msg+' '+obj2.msg); // 'hello world'
\n", - "type": "module", - "displayName": "Object factory" - }, - { - "textRaw": "Function factory", - "name": "function_factory", - "desc": "

This pattern illustrates how to create and return a JavaScript function that\nwraps a C++ function:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> MyFunction(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(String::New("hello world"));\n}\n\nHandle<Value> CreateFunction(const Arguments& args) {\n  HandleScope scope;\n\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(MyFunction);\n  Local<Function> fn = tpl->GetFunction();\n  fn->SetName(String::NewSymbol("theFunction")); // omit this to make it anonymous\n\n  return scope.Close(fn);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("createFunction"),\n      FunctionTemplate::New(CreateFunction)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar fn = addon.createFunction();\nconsole.log(fn()); // 'hello world'
\n", - "type": "module", - "displayName": "Function factory" - }, - { - "textRaw": "Wrapping C++ objects", - "name": "wrapping_c++_objects", - "desc": "

Here we will create a wrapper for a C++ object/class MyObject that can be\ninstantiated in JavaScript through the new operator. First prepare the main\nmodule addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init(target);\n}\n\nNODE_MODULE(addon, InitAll)
\n

Then in myobject.h make your wrapper inherit from node::ObjectWrap:\n\n

\n
#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init(v8::Handle<v8::Object> target);\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);\n  double counter_;\n};\n\n#endif
\n

And in myobject.cc implement the various methods that you want to expose.\nHere we expose the method plusOne by adding it to the constructor's\nprototype:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nvoid MyObject::Init(Handle<Object> target) {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n  // Prototype\n  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),\n      FunctionTemplate::New(PlusOne)->GetFunction());\n\n  Persistent<Function> constructor = Persistent<Function>::New(tpl->GetFunction());\n  target->Set(String::NewSymbol("MyObject"), constructor);\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::PlusOne(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n  obj->counter_ += 1;\n\n  return scope.Close(Number::New(obj->counter_));\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj = new addon.MyObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13
\n", - "type": "module", - "displayName": "Wrapping C++ objects" - }, - { - "textRaw": "Factory of wrapped objects", - "name": "factory_of_wrapped_objects", - "desc": "

This is useful when you want to be able to create native objects without\nexplicitly instantiating them with the new operator in JavaScript, e.g.\n\n

\n
var obj = addon.createObject();\n// instead of:\n// var obj = new addon.Object();
\n

Let's register our createObject method in addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(MyObject::NewInstance(args));\n}\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init();\n\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n}\n\nNODE_MODULE(addon, InitAll)
\n

In myobject.h we now introduce the static method NewInstance that takes\ncare of instantiating the object (i.e. it does the job of new in JavaScript):\n\n

\n
#define BUILDING_NODE_EXTENSION\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init();\n  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Persistent<v8::Function> constructor;\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);\n  double counter_;\n};\n\n#endif
\n

The implementation is similar to the above in myobject.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nPersistent<Function> MyObject::constructor;\n\nvoid MyObject::Init() {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n  // Prototype\n  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),\n      FunctionTemplate::New(PlusOne)->GetFunction());\n\n  constructor = Persistent<Function>::New(tpl->GetFunction());\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::NewInstance(const Arguments& args) {\n  HandleScope scope;\n\n  const unsigned argc = 1;\n  Handle<Value> argv[argc] = { args[0] };\n  Local<Object> instance = constructor->NewInstance(argc, argv);\n\n  return scope.Close(instance);\n}\n\nHandle<Value> MyObject::PlusOne(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n  obj->counter_ += 1;\n\n  return scope.Close(Number::New(obj->counter_));\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj = addon.createObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13\n\nvar obj2 = addon.createObject(20);\nconsole.log( obj2.plusOne() ); // 21\nconsole.log( obj2.plusOne() ); // 22\nconsole.log( obj2.plusOne() ); // 23
\n", - "type": "module", - "displayName": "Factory of wrapped objects" - }, - { - "textRaw": "Passing wrapped objects around", - "name": "passing_wrapped_objects_around", - "desc": "

In addition to wrapping and returning C++ objects, you can pass them around\nby unwrapping them with Node's node::ObjectWrap::Unwrap helper function.\nIn the following addon.cc we introduce a function add() that can take on two\nMyObject objects:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(MyObject::NewInstance(args));\n}\n\nHandle<Value> Add(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(\n      args[0]->ToObject());\n  MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(\n      args[1]->ToObject());\n\n  double sum = obj1->Val() + obj2->Val();\n  return scope.Close(Number::New(sum));\n}\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init();\n\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n\n  target->Set(String::NewSymbol("add"),\n      FunctionTemplate::New(Add)->GetFunction());\n}\n\nNODE_MODULE(addon, InitAll)
\n

To make things interesting we introduce a public method in myobject.h so we\ncan probe private values after unwrapping the object:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init();\n  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);\n  double Val() const { return val_; }\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Persistent<v8::Function> constructor;\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  double val_;\n};\n\n#endif
\n

The implementation of myobject.cc is similar as before:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nPersistent<Function> MyObject::constructor;\n\nvoid MyObject::Init() {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n\n  constructor = Persistent<Function>::New(tpl->GetFunction());\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->val_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::NewInstance(const Arguments& args) {\n  HandleScope scope;\n\n  const unsigned argc = 1;\n  Handle<Value> argv[argc] = { args[0] };\n  Local<Object> instance = constructor->NewInstance(argc, argv);\n\n  return scope.Close(instance);\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj1 = addon.createObject(10);\nvar obj2 = addon.createObject(20);\nvar result = addon.add(obj1, obj2);\n\nconsole.log(result); // 30
\n", - "type": "module", - "displayName": "Passing wrapped objects around" - } - ], - "type": "module", - "displayName": "Addon patterns" - } - ], - "type": "module", - "displayName": "Addons" - } - ] -} --- a/doc/api/api/all.html +++ /dev/null @@ -1,9097 +0,0 @@ - - - - - About this Documentation Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- -
-

Table of Contents

- - -
- -
-

About this Documentation#

- - -

The goal of this documentation is to comprehensively explain the Node.js -API, both from a reference as well as a conceptual point of view. Each -section describes a built-in module or high-level concept. - -

-

Where appropriate, property types, method arguments, and the arguments -provided to event handlers are detailed in a list underneath the topic -heading. - -

-

Every .html document has a corresponding .json document presenting -the same information in a structured manner. This feature is -experimental, and added for the benefit of IDEs and other utilities that -wish to do programmatic things with the documentation. - -

-

Every .html and .json file is generated based on the corresponding -.markdown file in the doc/api/ folder in node's source tree. The -documentation is generated using the tools/doc/generate.js program. -The HTML template is located at doc/template.html. - -

-

Stability Index#

- - -

Throughout the documentation, you will see indications of a section's -stability. The Node.js API is still somewhat changing, and as it -matures, certain parts are more reliable than others. Some are so -proven, and so relied upon, that they are unlikely to ever change at -all. Others are brand new and experimental, or known to be hazardous -and in the process of being redesigned. - -

-

The notices look like this: - -

-
Stability: 1 Experimental
-

The stability indices are as follows: - -

-
    -
  • 0 - Deprecated This feature is known to be problematic, and changes are -planned. Do not rely on it. Use of the feature may cause warnings. Backwards -compatibility should not be expected.
    • -
-
    -
  • 1 - Experimental This feature was introduced recently, and may change -or be removed in future versions. Please try it out and provide feedback. -If it addresses a use-case that is important to you, tell the node core team.
    • -
-
    -
  • 2 - Unstable The API is in the process of settling, but has not yet had -sufficient real-world testing to be considered stable. Backwards-compatibility -will be maintained if reasonable.
    • -
-
    -
  • 3 - Stable The API has proven satisfactory, but cleanup in the underlying -code may cause minor changes. Backwards-compatibility is guaranteed.
    • -
-
    -
  • 4 - API Frozen This API has been tested extensively in production and is -unlikely to ever have to change.
    • -
-
    -
  • 5 - Locked Unless serious bugs are found, this code will not ever -change. Please do not suggest changes in this area; they will be refused.
    • -
-

JSON Output#

-
Stability: 1 - Experimental
-

Every HTML file in the markdown has a corresponding JSON file with the -same data. - -

-

This feature is new as of node v0.6.12. It is experimental. - -

-

Synopsis#

- - -

An example of a web server written with Node which responds with 'Hello -World': - -

-
var http = require('http');
-
-http.createServer(function (request, response) {
-  response.writeHead(200, {'Content-Type': 'text/plain'});
-  response.end('Hello World\n');
-}).listen(8124);
-
-console.log('Server running at http://127.0.0.1:8124/');
-

To run the server, put the code into a file called example.js and execute -it with the node program - -

-
> node example.js
-Server running at http://127.0.0.1:8124/
-

All of the examples in the documentation can be run similarly. - -

-

Global Objects#

- - -

These objects are available in all modules. Some of these objects aren't -actually in the global scope but in the module scope - this will be noted. - -

-

global#

- - -
    -
  • {Object} The global namespace object.
    • -
-

In browsers, the top-level scope is the global scope. That means that in -browsers if you're in the global scope var something will define a global -variable. In Node this is different. The top-level scope is not the global -scope; var something inside a Node module will be local to that module. - -

-

process#

- - -
    -
  • {Object}
    • -
-

The process object. See the process object section. - -

-

console#

- - -
    -
  • {Object}
    • -
-

Used to print to stdout and stderr. See the stdio section. - -

-

Buffer#

- - -
    -
  • {Object}
    • -
-

Used to handle binary data. See the buffer section. - -

-

require()#

- - -
    -
  • {Function}
    • -
-

To require modules. See the Modules section. -require isn't actually a global but rather local to each module. - - -

-

require.resolve()#

-

Use the internal require() machinery to look up the location of a module, -but rather than loading the module, just return the resolved filename. - -

-

require.cache#

-
    -
  • Object
    • -
-

Modules are cached in this object when they are required. By deleting a key -value from this object, the next require will reload the module. - -

-

__filename#

- - -
    -
  • {String}
    • -
-

The filename of the code being executed. This is the resolved absolute path -of this code file. For a main program this is not necessarily the same -filename used in the command line. The value inside a module is the path -to that module file. - -

-

Example: running node example.js from /Users/mjr - -

-
console.log(__filename);
-// /Users/mjr/example.js
-

__filename isn't actually a global but rather local to each module. - -

-

__dirname#

- - -
    -
  • {String}
    • -
-

The name of the directory that the currently executing script resides in. - -

-

Example: running node example.js from /Users/mjr - -

-
console.log(__dirname);
-// /Users/mjr
-

__dirname isn't actually a global but rather local to each module. - - -

-

module#

- - -
    -
  • {Object}
    • -
-

A reference to the current module. In particular -module.exports is the same as the exports object. See src/node.js -for more information. -module isn't actually a global but rather local to each module. - - -

-

exports#

- - -

An object which is shared between all instances of the current module and -made accessible through require(). -exports is the same as the module.exports object. See src/node.js -for more information. -exports isn't actually a global but rather local to each module. - -

-

See the module system documentation for more -information. - -

-

See the module section for more information. - -

-

setTimeout(cb, ms)#

-

clearTimeout(t)#

-

setInterval(cb, ms)#

-

clearInterval(t)#

- - -

The timer functions are global variables. See the timers section. - -

-

console#

-
Stability: 4 - API Frozen
-
    -
  • {Object}
    • -
- - -

For printing to stdout and stderr. Similar to the console object functions -provided by most web browsers, here the output is sent to stdout or stderr. - - -

-

console.log()#

-

Prints to stdout with newline. This function can take multiple arguments in a -printf()-like way. Example: - -

-
console.log('count: %d', count);
-

If formatting elements are not found in the first string then util.inspect -is used on each argument. -See util.format() for more information. - -

-

console.info()#

-

Same as console.log. - -

-

console.warn()#

-

console.error()#

-

Same as console.log but prints to stderr. - -

-

console.dir(obj)#

-

Uses util.inspect on obj and prints resulting string to stderr. - -

-

console.time(label)#

-

Mark a time. - - -

-

console.timeEnd(label)#

-

Finish timer, record output. Example - -

-
console.time('100-elements');
-for (var i = 0; i < 100; i++) {
-  ;
-}
-console.timeEnd('100-elements');
-

console.trace()#

-

Print a stack trace to stderr of the current position. - -

-

console.assert()#

-

Same as assert.ok(). - - -

-

Timers#

-
Stability: 5 - Locked
-

All of the timer functions are globals. You do not need to require() -this module in order to use them. - -

-

setTimeout(callback, delay, [arg], [...])#

-

To schedule execution of a one-time callback after delay milliseconds. Returns a -timeoutId for possible use with clearTimeout(). Optionally you can -also pass arguments to the callback. - -

-

It is important to note that your callback will probably not be called in exactly -delay milliseconds - Node.js makes no guarantees about the exact timing of when -the callback will fire, nor of the ordering things will fire in. The callback will -be called as close as possible to the time specified. - -

-

clearTimeout(timeoutId)#

-

Prevents a timeout from triggering. - -

-

setInterval(callback, delay, [arg], [...])#

-

To schedule the repeated execution of callback every delay milliseconds. -Returns a intervalId for possible use with clearInterval(). Optionally -you can also pass arguments to the callback. - -

-

clearInterval(intervalId)#

-

Stops a interval from triggering. - -

-

Modules#

-
Stability: 5 - Locked
- - -

Node has a simple module loading system. In Node, files and modules are in -one-to-one correspondence. As an example, foo.js loads the module -circle.js in the same directory. - -

-

The contents of foo.js: - -

-
var circle = require('./circle.js');
-console.log( 'The area of a circle of radius 4 is '
-           + circle.area(4));
-

The contents of circle.js: - -

-
var PI = Math.PI;
-
-exports.area = function (r) {
-  return PI * r * r;
-};
-
-exports.circumference = function (r) {
-  return 2 * PI * r;
-};
-

The module circle.js has exported the functions area() and -circumference(). To export an object, add to the special exports -object. - -

-

Variables -local to the module will be private. In this example the variable PI is -private to circle.js. - -

-

The module system is implemented in the require("module") module. - -

-

Cycles#

- - -

When there are circular require() calls, a module might not be -done being executed when it is returned. - -

-

Consider this situation: - -

-

a.js: - -

-
console.log('a starting');
-exports.done = false;
-var b = require('./b.js');
-console.log('in a, b.done = %j', b.done);
-exports.done = true;
-console.log('a done');
-

b.js: - -

-
console.log('b starting');
-exports.done = false;
-var a = require('./a.js');
-console.log('in b, a.done = %j', a.done);
-exports.done = true;
-console.log('b done');
-

main.js: - -

-
console.log('main starting');
-var a = require('./a.js');
-var b = require('./b.js');
-console.log('in main, a.done=%j, b.done=%j', a.done, b.done);
-

When main.js loads a.js, then a.js in turn loads b.js. At that -point, b.js tries to load a.js. In order to prevent an infinite -loop an unfinished copy of the a.js exports object is returned to the -b.js module. b.js then finishes loading, and its exports object is -provided to the a.js module. - -

-

By the time main.js has loaded both modules, they're both finished. -The output of this program would thus be: - -

-
$ node main.js
-main starting
-a starting
-b starting
-in b, a.done = false
-b done
-in a, b.done = true
-a done
-in main, a.done=true, b.done=true
-

If you have cyclic module dependencies in your program, make sure to -plan accordingly. - -

-

Core Modules#

- - -

Node has several modules compiled into the binary. These modules are -described in greater detail elsewhere in this documentation. - -

-

The core modules are defined in node's source in the lib/ folder. - -

-

Core modules are always preferentially loaded if their identifier is -passed to require(). For instance, require('http') will always -return the built in HTTP module, even if there is a file by that name. - -

-

File Modules#

- - -

If the exact filename is not found, then node will attempt to load the -required filename with the added extension of .js, .json, and then .node. - -

-

.js files are interpreted as JavaScript text files, and .json files are -parsed as JSON text files. .node files are interpreted as compiled addon -modules loaded with dlopen. - -

-

A module prefixed with '/' is an absolute path to the file. For -example, require('/home/marco/foo.js') will load the file at -/home/marco/foo.js. - -

-

A module prefixed with './' is relative to the file calling require(). -That is, circle.js must be in the same directory as foo.js for -require('./circle') to find it. - -

-

Without a leading '/' or './' to indicate a file, the module is either a -"core module" or is loaded from a node_modules folder. - -

-

Loading from node_modules Folders#

- - -

If the module identifier passed to require() is not a native module, -and does not begin with '/', '../', or './', then node starts at the -parent directory of the current module, and adds /node_modules, and -attempts to load the module from that location. - -

-

If it is not found there, then it moves to the parent directory, and so -on, until the root of the tree is reached. - -

-

For example, if the file at '/home/ry/projects/foo.js' called -require('bar.js'), then node would look in the following locations, in -this order: - -

-
    -
  • /home/ry/projects/node_modules/bar.js
    • -
  • /home/ry/node_modules/bar.js
    • -
  • /home/node_modules/bar.js
    • -
  • /node_modules/bar.js
    • -
-

This allows programs to localize their dependencies, so that they do not -clash. - -

-

Folders as Modules#

- - -

It is convenient to organize programs and libraries into self-contained -directories, and then provide a single entry point to that library. -There are three ways in which a folder may be passed to require() as -an argument. - -

-

The first is to create a package.json file in the root of the folder, -which specifies a main module. An example package.json file might -look like this: - -

-
{ "name" : "some-library",
-  "main" : "./lib/some-library.js" }
-

If this was in a folder at ./some-library, then -require('./some-library') would attempt to load -./some-library/lib/some-library.js. - -

-

This is the extent of Node's awareness of package.json files. - -

-

If there is no package.json file present in the directory, then node -will attempt to load an index.js or index.node file out of that -directory. For example, if there was no package.json file in the above -example, then require('./some-library') would attempt to load: - -

-
    -
  • ./some-library/index.js
    • -
  • ./some-library/index.node
    • -
-

Caching#

- - -

Modules are cached after the first time they are loaded. This means -(among other things) that every call to require('foo') will get -exactly the same object returned, if it would resolve to the same file. - -

-

Multiple calls to require('foo') may not cause the module code to be -executed multiple times. This is an important feature. With it, -"partially done" objects can be returned, thus allowing transitive -dependencies to be loaded even when they would cause cycles. - -

-

If you want to have a module execute code multiple times, then export a -function, and call that function. - -

-

Module Caching Caveats#

- - -

Modules are cached based on their resolved filename. Since modules may -resolve to a different filename based on the location of the calling -module (loading from node_modules folders), it is not a guarantee -that require('foo') will always return the exact same object, if it -would resolve to different files. - -

-

The module Object#

- - - -
    -
  • {Object}
    • -
-

In each module, the module free variable is a reference to the object -representing the current module. In particular -module.exports is the same as the exports object. -module isn't actually a global but rather local to each module. - -

-

module.exports#

-
    -
  • Object
    • -
-

The exports object is created by the Module system. Sometimes this is not -acceptable, many want their module to be an instance of some class. To do this -assign the desired export object to module.exports. For example suppose we -were making a module called a.js - -

-
var EventEmitter = require('events').EventEmitter;
-
-module.exports = new EventEmitter();
-
-// Do some work, and after some time emit
-// the 'ready' event from the module itself.
-setTimeout(function() {
-  module.exports.emit('ready');
-}, 1000);
-

Then in another file we could do - -

-
var a = require('./a');
-a.on('ready', function() {
-  console.log('module a is ready');
-});
-

Note that assignment to module.exports must be done immediately. It cannot be -done in any callbacks. This does not work: - -

-

x.js: - -

-
setTimeout(function() {
-  module.exports = { a: "hello" };
-}, 0);
-

y.js: - -

-
var x = require('./x');
-console.log(x.a);
-

module.require(id)#

-
    -
  • id String
    • -
  • Return: Object exports from the resolved module
    • -
-

The module.require method provides a way to load a module as if -require() was called from the original module. - -

-

Note that in order to do this, you must get a reference to the module -object. Since require() returns the exports, and the module is -typically only available within a specific module's code, it must be -explicitly exported in order to be used. - - -

-

module.id#

-
    -
  • String
    • -
-

The identifier for the module. Typically this is the fully resolved -filename. - - -

-

module.filename#

-
    -
  • String
    • -
-

The fully resolved filename to the module. - - -

-

module.loaded#

-
    -
  • Boolean
    • -
-

Whether or not the module is done loading, or is in the process of -loading. - - -

-

module.parent#

-
    -
  • Module Object
    • -
-

The module that required this one. - - -

-

module.children#

-
    -
  • Array
    • -
-

The module objects required by this one. - - - -

-

All Together...#

- - -

To get the exact filename that will be loaded when require() is called, use -the require.resolve() function. - -

-

Putting together all of the above, here is the high-level algorithm -in pseudocode of what require.resolve does: - -

-
require(X) from module at path Y
-1. If X is a core module,
-   a. return the core module
-   b. STOP
-2. If X begins with './' or '/' or '../'
-   a. LOAD_AS_FILE(Y + X)
-   b. LOAD_AS_DIRECTORY(Y + X)
-3. LOAD_NODE_MODULES(X, dirname(Y))
-4. THROW "not found"
-
-LOAD_AS_FILE(X)
-1. If X is a file, load X as JavaScript text.  STOP
-2. If X.js is a file, load X.js as JavaScript text.  STOP
-3. If X.node is a file, load X.node as binary addon.  STOP
-
-LOAD_AS_DIRECTORY(X)
-1. If X/package.json is a file,
-   a. Parse X/package.json, and look for "main" field.
-   b. let M = X + (json main field)
-   c. LOAD_AS_FILE(M)
-2. If X/index.js is a file, load X/index.js as JavaScript text.  STOP
-3. If X/index.node is a file, load X/index.node as binary addon.  STOP
-
-LOAD_NODE_MODULES(X, START)
-1. let DIRS=NODE_MODULES_PATHS(START)
-2. for each DIR in DIRS:
-   a. LOAD_AS_FILE(DIR/X)
-   b. LOAD_AS_DIRECTORY(DIR/X)
-
-NODE_MODULES_PATHS(START)
-1. let PARTS = path split(START)
-2. let ROOT = index of first instance of "node_modules" in PARTS, or 0
-3. let I = count of PARTS - 1
-4. let DIRS = []
-5. while I > ROOT,
-   a. if PARTS[I] = "node_modules" CONTINUE
-   c. DIR = path join(PARTS[0 .. I] + "node_modules")
-   b. DIRS = DIRS + DIR
-   c. let I = I - 1
-6. return DIRS
-

Loading from the global folders#

- - -

If the NODE_PATH environment variable is set to a colon-delimited list -of absolute paths, then node will search those paths for modules if they -are not found elsewhere. (Note: On Windows, NODE_PATH is delimited by -semicolons instead of colons.) - -

-

Additionally, node will search in the following locations: - -

-
    -
  • 1: $HOME/.node_modules
    • -
  • 2: $HOME/.node_libraries
    • -
  • 3: $PREFIX/lib/node
    • -
-

Where $HOME is the user's home directory, and $PREFIX is node's -configured installPrefix. - -

-

These are mostly for historic reasons. You are highly encouraged to -place your dependencies locally in node_modules folders. They will be -loaded faster, and more reliably. - -

-

Accessing the main module#

- - -

When a file is run directly from Node, require.main is set to its -module. That means that you can determine whether a file has been run -directly by testing - -

-
require.main === module
-

For a file foo.js, this will be true if run via node foo.js, but -false if run by require('./foo'). - -

-

Because module provides a filename property (normally equivalent to -__filename), the entry point of the current application can be obtained -by checking require.main.filename. - -

-

Addenda: Package Manager Tips#

- - -

The semantics of Node's require() function were designed to be general -enough to support a number of sane directory structures. Package manager -programs such as dpkg, rpm, and npm will hopefully find it possible to -build native packages from Node modules without modification. - -

-

Below we give a suggested directory structure that could work: - -

-

Let's say that we wanted to have the folder at -/usr/lib/node/<some-package>/<some-version> hold the contents of a -specific version of a package. - -

-

Packages can depend on one another. In order to install package foo, you -may have to install a specific version of package bar. The bar package -may itself have dependencies, and in some cases, these dependencies may even -collide or form cycles. - -

-

Since Node looks up the realpath of any modules it loads (that is, -resolves symlinks), and then looks for their dependencies in the -node_modules folders as described above, this situation is very simple to -resolve with the following architecture: - -

-
    -
  • /usr/lib/node/foo/1.2.3/ - Contents of the foo package, version 1.2.3.
    • -
  • /usr/lib/node/bar/4.3.2/ - Contents of the bar package that foo -depends on.
    • -
  • /usr/lib/node/foo/1.2.3/node_modules/bar - Symbolic link to -/usr/lib/node/bar/4.3.2/.
    • -
  • /usr/lib/node/bar/4.3.2/node_modules/* - Symbolic links to the packages -that bar depends on.
    • -
-

Thus, even if a cycle is encountered, or if there are dependency -conflicts, every module will be able to get a version of its dependency -that it can use. - -

-

When the code in the foo package does require('bar'), it will get the -version that is symlinked into /usr/lib/node/foo/1.2.3/node_modules/bar. -Then, when the code in the bar package calls require('quux'), it'll get -the version that is symlinked into -/usr/lib/node/bar/4.3.2/node_modules/quux. - -

-

Furthermore, to make the module lookup process even more optimal, rather -than putting packages directly in /usr/lib/node, we could put them in -/usr/lib/node_modules/<name>/<version>. Then node will not bother -looking for missing dependencies in /usr/node_modules or /node_modules. - -

-

In order to make modules available to the node REPL, it might be useful to -also add the /usr/lib/node_modules folder to the $NODE_PATH environment -variable. Since the module lookups using node_modules folders are all -relative, and based on the real path of the files making the calls to -require(), the packages themselves can be anywhere. - -

-

Addons#

-

Addons are dynamically linked shared objects. They can provide glue to C and -C++ libraries. The API (at the moment) is rather complex, involving -knowledge of several libraries: - -

-
    -

  • V8 JavaScript, a C++ library. Used for interfacing with JavaScript: -creating objects, calling functions, etc. Documented mostly in the -v8.h header file (deps/v8/include/v8.h in the Node source tree), -which is also available online.

    -
    • -

  • libuv, C event loop library. Anytime one -needs to wait for a file descriptor to become readable, wait for a timer, or -wait for a signal to received one will need to interface with libuv. That is, -if you perform any I/O, libuv will need to be used.

    -
    • -

  • Internal Node libraries. Most importantly is the node::ObjectWrap -class which you will likely want to derive from.

    -
    • -

  • Others. Look in deps/ for what else is available.

    -
    • -
-

Node statically compiles all its dependencies into the executable. When -compiling your module, you don't need to worry about linking to any of these -libraries. - - -

-

Hello world#

-

To get started let's make a small Addon which is the C++ equivalent of -the following Javascript code: - -

-
exports.hello = function() { return 'world'; };
-

First we create a file hello.cc: - -

-
#include <node.h>
-#include <v8.h>
-
-using namespace v8;
-
-Handle<Value> Method(const Arguments& args) {
-  HandleScope scope;
-  return scope.Close(String::New("world"));
-}
-
-void init(Handle<Object> target) {
-  target->Set(String::NewSymbol("hello"),
-      FunctionTemplate::New(Method)->GetFunction());
-}
-NODE_MODULE(hello, init)
-

Note that all Node addons must export an initialization function: - -

-
void Initialize (Handle<Object> target);
-NODE_MODULE(module_name, Initialize)
-

There is no semi-colon after NODE_MODULE as it's not a function (see node.h). - -

-

The module_name needs to match the filename of the final binary (minus the -.node suffix). - -

-

The source code needs to be built into hello.node, the binary Addon. To -do this we create a file called wscript which is python code and looks -like this: - -

-
srcdir = '.'
-blddir = 'build'
-VERSION = '0.0.1'
-
-def set_options(opt):
-  opt.tool_options('compiler_cxx')
-
-def configure(conf):
-  conf.check_tool('compiler_cxx')
-  conf.check_tool('node_addon')
-
-def build(bld):
-  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
-  obj.target = 'hello'
-  obj.source = 'hello.cc'
-

Running node-waf configure build will create a file -build/default/hello.node which is our Addon. - -

-

node-waf is just WAF, the python-based build system. node-waf is -provided for the ease of users. - -

-

You can now use the binary addon in a Node project hello.js by pointing require to -the recently built module: - -

-
var addon = require('./build/Release/hello');
-
-console.log(addon.hello()); // 'world'
-

Please see patterns below for further information or -

-

https://github.com/pietern/hiredis-node for an example in production. - - -

-

Addon patterns#

-

Below are some addon patterns to help you get started. Consult the online -v8 reference for help with the various v8 -calls, and v8's Embedder's Guide -for an explanation of several concepts used such as handles, scopes, -function templates, etc. - -

-

To compile these examples, create the wscript file below and run -node-waf configure build: - -

-
srcdir = '.'
-blddir = 'build'
-VERSION = '0.0.1'
-
-def set_options(opt):
-  opt.tool_options('compiler_cxx')
-
-def configure(conf):
-  conf.check_tool('compiler_cxx')
-  conf.check_tool('node_addon')
-
-def build(bld):
-  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')
-  obj.target = 'addon'
-  obj.source = ['addon.cc']
-

In cases where there is more than one .cc file, simply add the file name to the -obj.source array, e.g.: - -

-
obj.source = ['addon.cc', 'myexample.cc']
-

Function arguments#

-

The following pattern illustrates how to read arguments from JavaScript -function calls and return a result. This is the main and only needed source -addon.cc: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-
-using namespace v8;
-
-Handle<Value> Add(const Arguments& args) {
-  HandleScope scope;
-
-  if (args.Length() < 2) {
-    ThrowException(Exception::TypeError(String::New("Wrong number of arguments")));
-    return scope.Close(Undefined());
-  }
-
-  if (!args[0]->IsNumber() || !args[1]->IsNumber()) {
-    ThrowException(Exception::TypeError(String::New("Wrong arguments")));
-    return scope.Close(Undefined());
-  }
-
-  Local<Number> num = Number::New(args[0]->NumberValue() +
-      args[1]->NumberValue());
-  return scope.Close(num);
-}
-
-void Init(Handle<Object> target) {
-  target->Set(String::NewSymbol("add"),
-      FunctionTemplate::New(Add)->GetFunction());
-}
-
-NODE_MODULE(addon, Init)
-

You can test it with the following JavaScript snippet: - -

-
var addon = require('./build/Release/addon');
-
-console.log( 'This should be eight:', addon.add(3,5) );
-

Callbacks#

-

You can pass JavaScript functions to a C++ function and execute them from -there. Here's addon.cc: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-
-using namespace v8;
-
-Handle<Value> RunCallback(const Arguments& args) {
-  HandleScope scope;
-
-  Local<Function> cb = Local<Function>::Cast(args[0]);
-  const unsigned argc = 1;
-  Local<Value> argv[argc] = { Local<Value>::New(String::New("hello world")) };
-  cb->Call(Context::GetCurrent()->Global(), argc, argv);
-
-  return scope.Close(Undefined());
-}
-
-void Init(Handle<Object> target) {
-  target->Set(String::NewSymbol("runCallback"),
-      FunctionTemplate::New(RunCallback)->GetFunction());
-}
-
-NODE_MODULE(addon, Init)
-

To test it run the following JavaScript snippet: - -

-
var addon = require('./build/Release/addon');
-
-addon.runCallback(function(msg){
-  console.log(msg); // 'hello world'
-});
-

Object factory#

-

You can create and return new objects from within a C++ function with this -addon.cc pattern, which returns an object with property msg that echoes -the string passed to createObject(): - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-
-using namespace v8;
-
-Handle<Value> CreateObject(const Arguments& args) {
-  HandleScope scope;
-
-  Local<Object> obj = Object::New();
-  obj->Set(String::NewSymbol("msg"), args[0]->ToString());
-
-  return scope.Close(obj);
-}
-
-void Init(Handle<Object> target) {
-  target->Set(String::NewSymbol("createObject"),
-      FunctionTemplate::New(CreateObject)->GetFunction());
-}
-
-NODE_MODULE(addon, Init)
-

To test it in JavaScript: - -

-
var addon = require('./build/Release/addon');
-
-var obj1 = addon.createObject('hello');
-var obj2 = addon.createObject('world');
-console.log(obj1.msg+' '+obj2.msg); // 'hello world'
-

Function factory#

-

This pattern illustrates how to create and return a JavaScript function that -wraps a C++ function: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-
-using namespace v8;
-
-Handle<Value> MyFunction(const Arguments& args) {
-  HandleScope scope;
-  return scope.Close(String::New("hello world"));
-}
-
-Handle<Value> CreateFunction(const Arguments& args) {
-  HandleScope scope;
-
-  Local<FunctionTemplate> tpl = FunctionTemplate::New(MyFunction);
-  Local<Function> fn = tpl->GetFunction();
-  fn->SetName(String::NewSymbol("theFunction")); // omit this to make it anonymous
-
-  return scope.Close(fn);
-}
-
-void Init(Handle<Object> target) {
-  target->Set(String::NewSymbol("createFunction"),
-      FunctionTemplate::New(CreateFunction)->GetFunction());
-}
-
-NODE_MODULE(addon, Init)
-

To test: - -

-
var addon = require('./build/Release/addon');
-
-var fn = addon.createFunction();
-console.log(fn()); // 'hello world'
-

Wrapping C++ objects#

-

Here we will create a wrapper for a C++ object/class MyObject that can be -instantiated in JavaScript through the new operator. First prepare the main -module addon.cc: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-void InitAll(Handle<Object> target) {
-  MyObject::Init(target);
-}
-
-NODE_MODULE(addon, InitAll)
-

Then in myobject.h make your wrapper inherit from node::ObjectWrap: - -

-
#ifndef MYOBJECT_H
-#define MYOBJECT_H
-
-#include <node.h>
-
-class MyObject : public node::ObjectWrap {
- public:
-  static void Init(v8::Handle<v8::Object> target);
-
- private:
-  MyObject();
-  ~MyObject();
-
-  static v8::Handle<v8::Value> New(const v8::Arguments& args);
-  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);
-  double counter_;
-};
-
-#endif
-

And in myobject.cc implement the various methods that you want to expose. -Here we expose the method plusOne by adding it to the constructor's -prototype: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-MyObject::MyObject() {};
-MyObject::~MyObject() {};
-
-void MyObject::Init(Handle<Object> target) {
-  // Prepare constructor template
-  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
-  tpl->SetClassName(String::NewSymbol("MyObject"));
-  tpl->InstanceTemplate()->SetInternalFieldCount(1);
-  // Prototype
-  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),
-      FunctionTemplate::New(PlusOne)->GetFunction());
-
-  Persistent<Function> constructor = Persistent<Function>::New(tpl->GetFunction());
-  target->Set(String::NewSymbol("MyObject"), constructor);
-}
-
-Handle<Value> MyObject::New(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj = new MyObject();
-  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
-  obj->Wrap(args.This());
-
-  return args.This();
-}
-
-Handle<Value> MyObject::PlusOne(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());
-  obj->counter_ += 1;
-
-  return scope.Close(Number::New(obj->counter_));
-}
-

Test it with: - -

-
var addon = require('./build/Release/addon');
-
-var obj = new addon.MyObject(10);
-console.log( obj.plusOne() ); // 11
-console.log( obj.plusOne() ); // 12
-console.log( obj.plusOne() ); // 13
-

Factory of wrapped objects#

-

This is useful when you want to be able to create native objects without -explicitly instantiating them with the new operator in JavaScript, e.g. - -

-
var obj = addon.createObject();
-// instead of:
-// var obj = new addon.Object();
-

Let's register our createObject method in addon.cc: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-Handle<Value> CreateObject(const Arguments& args) {
-  HandleScope scope;
-  return scope.Close(MyObject::NewInstance(args));
-}
-
-void InitAll(Handle<Object> target) {
-  MyObject::Init();
-
-  target->Set(String::NewSymbol("createObject"),
-      FunctionTemplate::New(CreateObject)->GetFunction());
-}
-
-NODE_MODULE(addon, InitAll)
-

In myobject.h we now introduce the static method NewInstance that takes -care of instantiating the object (i.e. it does the job of new in JavaScript): - -

-
#define BUILDING_NODE_EXTENSION
-#ifndef MYOBJECT_H
-#define MYOBJECT_H
-
-#include <node.h>
-
-class MyObject : public node::ObjectWrap {
- public:
-  static void Init();
-  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);
-
- private:
-  MyObject();
-  ~MyObject();
-
-  static v8::Persistent<v8::Function> constructor;
-  static v8::Handle<v8::Value> New(const v8::Arguments& args);
-  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);
-  double counter_;
-};
-
-#endif
-

The implementation is similar to the above in myobject.cc: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-MyObject::MyObject() {};
-MyObject::~MyObject() {};
-
-Persistent<Function> MyObject::constructor;
-
-void MyObject::Init() {
-  // Prepare constructor template
-  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
-  tpl->SetClassName(String::NewSymbol("MyObject"));
-  tpl->InstanceTemplate()->SetInternalFieldCount(1);
-  // Prototype
-  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),
-      FunctionTemplate::New(PlusOne)->GetFunction());
-
-  constructor = Persistent<Function>::New(tpl->GetFunction());
-}
-
-Handle<Value> MyObject::New(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj = new MyObject();
-  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
-  obj->Wrap(args.This());
-
-  return args.This();
-}
-
-Handle<Value> MyObject::NewInstance(const Arguments& args) {
-  HandleScope scope;
-
-  const unsigned argc = 1;
-  Handle<Value> argv[argc] = { args[0] };
-  Local<Object> instance = constructor->NewInstance(argc, argv);
-
-  return scope.Close(instance);
-}
-
-Handle<Value> MyObject::PlusOne(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());
-  obj->counter_ += 1;
-
-  return scope.Close(Number::New(obj->counter_));
-}
-

Test it with: - -

-
var addon = require('./build/Release/addon');
-
-var obj = addon.createObject(10);
-console.log( obj.plusOne() ); // 11
-console.log( obj.plusOne() ); // 12
-console.log( obj.plusOne() ); // 13
-
-var obj2 = addon.createObject(20);
-console.log( obj2.plusOne() ); // 21
-console.log( obj2.plusOne() ); // 22
-console.log( obj2.plusOne() ); // 23
-

Passing wrapped objects around#

-

In addition to wrapping and returning C++ objects, you can pass them around -by unwrapping them with Node's node::ObjectWrap::Unwrap helper function. -In the following addon.cc we introduce a function add() that can take on two -MyObject objects: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-Handle<Value> CreateObject(const Arguments& args) {
-  HandleScope scope;
-  return scope.Close(MyObject::NewInstance(args));
-}
-
-Handle<Value> Add(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(
-      args[0]->ToObject());
-  MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(
-      args[1]->ToObject());
-
-  double sum = obj1->Val() + obj2->Val();
-  return scope.Close(Number::New(sum));
-}
-
-void InitAll(Handle<Object> target) {
-  MyObject::Init();
-
-  target->Set(String::NewSymbol("createObject"),
-      FunctionTemplate::New(CreateObject)->GetFunction());
-
-  target->Set(String::NewSymbol("add"),
-      FunctionTemplate::New(Add)->GetFunction());
-}
-
-NODE_MODULE(addon, InitAll)
-

To make things interesting we introduce a public method in myobject.h so we -can probe private values after unwrapping the object: - -

-
#define BUILDING_NODE_EXTENSION
-#ifndef MYOBJECT_H
-#define MYOBJECT_H
-
-#include <node.h>
-
-class MyObject : public node::ObjectWrap {
- public:
-  static void Init();
-  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);
-  double Val() const { return val_; }
-
- private:
-  MyObject();
-  ~MyObject();
-
-  static v8::Persistent<v8::Function> constructor;
-  static v8::Handle<v8::Value> New(const v8::Arguments& args);
-  double val_;
-};
-
-#endif
-

The implementation of myobject.cc is similar as before: - -

-
#define BUILDING_NODE_EXTENSION
-#include <node.h>
-#include "myobject.h"
-
-using namespace v8;
-
-MyObject::MyObject() {};
-MyObject::~MyObject() {};
-
-Persistent<Function> MyObject::constructor;
-
-void MyObject::Init() {
-  // Prepare constructor template
-  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);
-  tpl->SetClassName(String::NewSymbol("MyObject"));
-  tpl->InstanceTemplate()->SetInternalFieldCount(1);
-
-  constructor = Persistent<Function>::New(tpl->GetFunction());
-}
-
-Handle<Value> MyObject::New(const Arguments& args) {
-  HandleScope scope;
-
-  MyObject* obj = new MyObject();
-  obj->val_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();
-  obj->Wrap(args.This());
-
-  return args.This();
-}
-
-Handle<Value> MyObject::NewInstance(const Arguments& args) {
-  HandleScope scope;
-
-  const unsigned argc = 1;
-  Handle<Value> argv[argc] = { args[0] };
-  Local<Object> instance = constructor->NewInstance(argc, argv);
-
-  return scope.Close(instance);
-}
-

Test it with: - -

-
var addon = require('./build/Release/addon');
-
-var obj1 = addon.createObject(10);
-var obj2 = addon.createObject(20);
-var result = addon.add(obj1, obj2);
-
-console.log(result); // 30
-

process#

- - -

The process object is a global object and can be accessed from anywhere. -It is an instance of EventEmitter. - - -

-

Event: 'exit'#

-

Emitted when the process is about to exit. This is a good hook to perform -constant time checks of the module's state (like for unit tests). The main -event loop will no longer be run after the 'exit' callback finishes, so -timers may not be scheduled. - -

-

Example of listening for exit: - -

-
process.on('exit', function () {
-  process.nextTick(function () {
-   console.log('This will not run');
-  });
-  console.log('About to exit.');
-});
-

Event: 'uncaughtException'#

-

Emitted when an exception bubbles all the way back to the event loop. If a -listener is added for this exception, the default action (which is to print -a stack trace and exit) will not occur. - -

-

Example of listening for uncaughtException: - -

-
process.on('uncaughtException', function (err) {
-  console.log('Caught exception: ' + err);
-});
-
-setTimeout(function () {
-  console.log('This will still run.');
-}, 500);
-
-// Intentionally cause an exception, but don't catch it.
-nonexistentFunc();
-console.log('This will not run.');
-

Note that uncaughtException is a very crude mechanism for exception -handling. Using try / catch in your program will give you more control over -your program's flow. Especially for server programs that are designed to -stay running forever, uncaughtException can be a useful safety mechanism. - - -

-

Signal Events#

- - - -

Emitted when the processes receives a signal. See sigaction(2) for a list of -standard POSIX signal names such as SIGINT, SIGUSR1, etc. - -

-

Example of listening for SIGINT: - -

-
// Start reading from stdin so we don't exit.
-process.stdin.resume();
-
-process.on('SIGINT', function () {
-  console.log('Got SIGINT.  Press Control-D to exit.');
-});
-

An easy way to send the SIGINT signal is with Control-C in most terminal -programs. - - -

-

process.stdout#

-

A Writable Stream to stdout. - -

-

Example: the definition of console.log - -

-
console.log = function (d) {
-  process.stdout.write(d + '\n');
-};
-

process.stderr and process.stdout are unlike other streams in Node in -that writes to them are usually blocking. They are blocking in the case -that they refer to regular files or TTY file descriptors. In the case they -refer to pipes, they are non-blocking like other streams. - - -

-

process.stderr#

-

A writable stream to stderr. - -

-

process.stderr and process.stdout are unlike other streams in Node in -that writes to them are usually blocking. They are blocking in the case -that they refer to regular files or TTY file descriptors. In the case they -refer to pipes, they are non-blocking like other streams. - - -

-

process.stdin#

-

A Readable Stream for stdin. The stdin stream is paused by default, so one -must call process.stdin.resume() to read from it. - -

-

Example of opening standard input and listening for both events: - -

-
process.stdin.resume();
-process.stdin.setEncoding('utf8');
-
-process.stdin.on('data', function (chunk) {
-  process.stdout.write('data: ' + chunk);
-});
-
-process.stdin.on('end', function () {
-  process.stdout.write('end');
-});
-

process.argv#

-

An array containing the command line arguments. The first element will be -'node', the second element will be the name of the JavaScript file. The -next elements will be any additional command line arguments. - -

-
// print process.argv
-process.argv.forEach(function (val, index, array) {
-  console.log(index + ': ' + val);
-});
-

This will generate: - -

-
$ node process-2.js one two=three four
-0: node
-1: /Users/mjr/work/node/process-2.js
-2: one
-3: two=three
-4: four
-

process.execPath#

-

This is the absolute pathname of the executable that started the process. - -

-

Example: - -

-
/usr/local/bin/node
-

process.chdir(directory)#

-

Changes the current working directory of the process or throws an exception if that fails. - -

-
console.log('Starting directory: ' + process.cwd());
-try {
-  process.chdir('/tmp');
-  console.log('New directory: ' + process.cwd());
-}
-catch (err) {
-  console.log('chdir: ' + err);
-}
-

process.cwd()#

-

Returns the current working directory of the process. - -

-
console.log('Current directory: ' + process.cwd());
-

process.env#

-

An object containing the user environment. See environ(7). - - -

-

process.exit([code])#

-

Ends the process with the specified code. If omitted, exit uses the -'success' code 0. - -

-

To exit with a 'failure' code: - -

-
process.exit(1);
-

The shell that executed node should see the exit code as 1. - - -

-

process.getgid()#

-

Gets the group identity of the process. (See getgid(2).) -This is the numerical group id, not the group name. - -

-
console.log('Current gid: ' + process.getgid());
-

process.setgid(id)#

-

Sets the group identity of the process. (See setgid(2).) This accepts either -a numerical ID or a groupname string. If a groupname is specified, this method -blocks while resolving it to a numerical ID. - -

-
console.log('Current gid: ' + process.getgid());
-try {
-  process.setgid(501);
-  console.log('New gid: ' + process.getgid());
-}
-catch (err) {
-  console.log('Failed to set gid: ' + err);
-}
-

process.getuid()#

-

Gets the user identity of the process. (See getuid(2).) -This is the numerical userid, not the username. - -

-
console.log('Current uid: ' + process.getuid());
-

process.setuid(id)#

-

Sets the user identity of the process. (See setuid(2).) This accepts either -a numerical ID or a username string. If a username is specified, this method -blocks while resolving it to a numerical ID. - -

-
console.log('Current uid: ' + process.getuid());
-try {
-  process.setuid(501);
-  console.log('New uid: ' + process.getuid());
-}
-catch (err) {
-  console.log('Failed to set uid: ' + err);
-}
-

process.version#

-

A compiled-in property that exposes NODE_VERSION. - -

-
console.log('Version: ' + process.version);
-

process.versions#

-

A property exposing version strings of node and its dependencies. - -

-
console.log(process.versions);
-

Will output: - -

-
{ node: '0.4.12',
-  v8: '3.1.8.26',
-  ares: '1.7.4',
-  ev: '4.4',
-  openssl: '1.0.0e-fips' }
-

process.installPrefix#

-

A compiled-in property that exposes NODE_PREFIX. - -

-
console.log('Prefix: ' + process.installPrefix);
-

process.kill(pid, [signal])#

-

Send a signal to a process. pid is the process id and signal is the -string describing the signal to send. Signal names are strings like -'SIGINT' or 'SIGUSR1'. If omitted, the signal will be 'SIGTERM'. -See kill(2) for more information. - -

-

Note that just because the name of this function is process.kill, it is -really just a signal sender, like the kill system call. The signal sent -may do something other than kill the target process. - -

-

Example of sending a signal to yourself: - -

-
process.on('SIGHUP', function () {
-  console.log('Got SIGHUP signal.');
-});
-
-setTimeout(function () {
-  console.log('Exiting.');
-  process.exit(0);
-}, 100);
-
-process.kill(process.pid, 'SIGHUP');
-

process.pid#

-

The PID of the process. - -

-
console.log('This process is pid ' + process.pid);
-

process.title#

-

Getter/setter to set what is displayed in 'ps'. - - -

-

process.arch#

-

What processor architecture you're running on: 'arm', 'ia32', or 'x64'. - -

-
console.log('This processor architecture is ' + process.arch);
-

process.platform#

-

What platform you're running on. 'linux2', 'darwin', etc. - -

-
console.log('This platform is ' + process.platform);
-

process.memoryUsage()#

-

Returns an object describing the memory usage of the Node process -measured in bytes. - -

-
var util = require('util');
-
-console.log(util.inspect(process.memoryUsage()));
-

This will generate: - -

-
{ rss: 4935680,
-  heapTotal: 1826816,
-  heapUsed: 650472 }
-

heapTotal and heapUsed refer to V8's memory usage. - - -

-

process.nextTick(callback)#

-

On the next loop around the event loop call this callback. -This is not a simple alias to setTimeout(fn, 0), it's much more -efficient. - -

-
process.nextTick(function () {
-  console.log('nextTick callback');
-});
-

process.umask([mask])#

-

Sets or reads the process's file mode creation mask. Child processes inherit -the mask from the parent process. Returns the old mask if mask argument is -given, otherwise returns the current mask. - -

-
var oldmask, newmask = 0644;
-
-oldmask = process.umask(newmask);
-console.log('Changed umask from: ' + oldmask.toString(8) +
-            ' to ' + newmask.toString(8));
-

process.uptime()#

-

Number of seconds Node has been running. - -

-

util#

-
Stability: 5 - Locked
-

These functions are in the module 'util'. Use require('util') to access -them. - - -

-

util.format()#

-

Returns a formatted string using the first argument as a printf-like format. - -

-

The first argument is a string that contains zero or more placeholders. -Each placeholder is replaced with the converted value from its corresponding -argument. Supported placeholders are: - -

-
    -
  • %s - String.
    • -
  • %d - Number (both integer and float).
    • -
  • %j - JSON.
    • -
  • %% - single percent sign ('%'). This does not consume an argument.
    • -
-

If the placeholder does not have a corresponding argument, the placeholder is -not replaced. - -

-
util.format('%s:%s', 'foo'); // 'foo:%s'
-

If there are more arguments than placeholders, the extra arguments are -converted to strings with util.inspect() and these strings are concatenated, -delimited by a space. - -

-
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
-

If the first argument is not a format string then util.format() returns -a string that is the concatenation of all its arguments separated by spaces. -Each argument is converted to a string with util.inspect(). - -

-
util.format(1, 2, 3); // '1 2 3'
-

util.debug(string)#

-

A synchronous output function. Will block the process and -output string immediately to stderr. - -

-
require('util').debug('message on stderr');
-

util.log(string)#

-

Output with timestamp on stdout. - -

-
require('util').log('Timestamped message.');
-

util.inspect(object, [showHidden], [depth], [colors])#

-

Return a string representation of object, which is useful for debugging. - -

-

If showHidden is true, then the object's non-enumerable properties will be -shown too. Defaults to false. - -

-

If depth is provided, it tells inspect how many times to recurse while -formatting the object. This is useful for inspecting large complicated objects. - -

-

The default is to only recurse twice. To make it recurse indefinitely, pass -in null for depth. - -

-

If colors is true, the output will be styled with ANSI color codes. -Defaults to false. - -

-

Example of inspecting all properties of the util object: - -

-
var util = require('util');
-
-console.log(util.inspect(util, true, null));
-

util.isArray(object)#

-

Returns true if the given "object" is an Array. false otherwise. - -

-
var util = require('util');
-
-util.isArray([])
-  // true
-util.isArray(new Array)
-  // true
-util.isArray({})
-  // false
-

util.isRegExp(object)#

-

Returns true if the given "object" is a RegExp. false otherwise. - -

-
var util = require('util');
-
-util.isRegExp(/some regexp/)
-  // true
-util.isRegExp(new RegExp('another regexp'))
-  // true
-util.isRegExp({})
-  // false
-

util.isDate(object)#

-

Returns true if the given "object" is a Date. false otherwise. - -

-
var util = require('util');
-
-util.isDate(new Date())
-  // true
-util.isDate(Date())
-  // false (without 'new' returns a String)
-util.isDate({})
-  // false
-

util.isError(object)#

-

Returns true if the given "object" is an Error. false otherwise. - -

-
var util = require('util');
-
-util.isError(new Error())
-  // true
-util.isError(new TypeError())
-  // true
-util.isError({ name: 'Error', message: 'an error occurred' })
-  // false
-

util.pump(readableStream, writableStream, [callback])#

-

Experimental - -

-

Read the data from readableStream and send it to the writableStream. -When writableStream.write(data) returns false readableStream will be -paused until the drain event occurs on the writableStream. callback gets -an error as its only argument and is called when writableStream is closed or -when an error occurs. - - -

-

util.inherits(constructor, superConstructor)#

-

Inherit the prototype methods from one -constructor -into another. The prototype of constructor will be set to a new -object created from superConstructor. - -

-

As an additional convenience, superConstructor will be accessible -through the constructor.super_ property. - -

-
var util = require("util");
-var events = require("events");
-
-function MyStream() {
-    events.EventEmitter.call(this);
-}
-
-util.inherits(MyStream, events.EventEmitter);
-
-MyStream.prototype.write = function(data) {
-    this.emit("data", data);
-}
-
-var stream = new MyStream();
-
-console.log(stream instanceof events.EventEmitter); // true
-console.log(MyStream.super_ === events.EventEmitter); // true
-
-stream.on("data", function(data) {
-    console.log('Received data: "' + data + '"');
-})
-stream.write("It works!"); // Received data: "It works!"
-

Events#

-
Stability: 4 - API Frozen
- - -

Many objects in Node emit events: a net.Server emits an event each time -a peer connects to it, a fs.readStream emits an event when the file is -opened. All objects which emit events are instances of events.EventEmitter. -You can access this module by doing: require("events"); - -

-

Typically, event names are represented by a camel-cased string, however, -there aren't any strict restrictions on that, as any string will be accepted. - -

-

Functions can then be attached to objects, to be executed when an event -is emitted. These functions are called listeners. - - -

-

Class: events.EventEmitter#

-

To access the EventEmitter class, require('events').EventEmitter. - -

-

When an EventEmitter instance experiences an error, the typical action is -to emit an 'error' event. Error events are treated as a special case in node. -If there is no listener for it, then the default action is to print a stack -trace and exit the program. - -

-

All EventEmitters emit the event 'newListener' when new listeners are -added. - -

-

emitter.addListener(event, listener)#

-

emitter.on(event, listener)#

-

Adds a listener to the end of the listeners array for the specified event. - -

-
server.on('connection', function (stream) {
-  console.log('someone connected!');
-});
-

emitter.once(event, listener)#

-

Adds a one time listener for the event. This listener is -invoked only the next time the event is fired, after which -it is removed. - -

-
server.once('connection', function (stream) {
-  console.log('Ah, we have our first user!');
-});
-

emitter.removeListener(event, listener)#

-

Remove a listener from the listener array for the specified event. -Caution: changes array indices in the listener array behind the listener. - -

-
var callback = function(stream) {
-  console.log('someone connected!');
-};
-server.on('connection', callback);
-// ...
-server.removeListener('connection', callback);
-

emitter.removeAllListeners([event])#

-

Removes all listeners, or those of the specified event. - - -

-

emitter.setMaxListeners(n)#

-

By default EventEmitters will print a warning if more than 10 listeners are -added for a particular event. This is a useful default which helps finding memory leaks. -Obviously not all Emitters should be limited to 10. This function allows -that to be increased. Set to zero for unlimited. - - -

-

emitter.listeners(event)#

-

Returns an array of listeners for the specified event. This array can be -manipulated, e.g. to remove listeners. - -

-
server.on('connection', function (stream) {
-  console.log('someone connected!');
-});
-console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
-

emitter.emit(event, [arg1], [arg2], [...])#

-

Execute each of the listeners in order with the supplied arguments. - -

-

Event: 'newListener'#

-
    -
  • event String The event name
    • -
  • listener Function The event handler function
    • -
-

This event is emitted any time someone adds a new listener. - -

-

Buffer#

-
Stability: 3 - Stable
-

Pure Javascript is Unicode friendly but not nice to binary data. When -dealing with TCP streams or the file system, it's necessary to handle octet -streams. Node has several strategies for manipulating, creating, and -consuming octet streams. - -

-

Raw data is stored in instances of the Buffer class. A Buffer is similar -to an array of integers but corresponds to a raw memory allocation outside -the V8 heap. A Buffer cannot be resized. - -

-

The Buffer class is a global, making it very rare that one would need -to ever require('buffer'). - -

-

Converting between Buffers and JavaScript string objects requires an explicit -encoding method. Here are the different string encodings. - -

-
    -

  • 'ascii' - for 7 bit ASCII data only. This encoding method is very fast, and -will strip the high bit if set. -Note that this encoding converts a null character ('\0' or '\u0000') into -0x20 (character code of a space). If you want to convert a null character -into 0x00, you should use 'utf8'.

    -
    • -

  • 'utf8' - Multi byte encoded Unicode characters. Many web pages and other document formats use UTF-8.

    -
    • -

  • 'ucs2' - 2-bytes, little endian encoded Unicode characters. It can encode -only BMP(Basic Multilingual Plane, U+0000 - U+FFFF).

    -
    • -

  • 'base64' - Base64 string encoding.

    -
    • -

  • 'binary' - A way of encoding raw binary data into strings by using only -the first 8 bits of each character. This encoding method is deprecated and -should be avoided in favor of Buffer objects where possible. This encoding -will be removed in future versions of Node.

    -
    • -

  • 'hex' - Encode each byte as two hexidecimal characters.

    -
    • -
-

Class: Buffer#

-

The Buffer class is a global type for dealing with binary data directly. -It can be constructed in a variety of ways. - -

-

new Buffer(size)#

-
    -
  • size Number
    • -
-

Allocates a new buffer of size octets. - -

-

new Buffer(array)#

-
    -
  • array Array
    • -
-

Allocates a new buffer using an array of octets. - -

-

new Buffer(str, [encoding])#

-
    -
  • str String - string to encode.
    • -
  • encoding String - encoding to use, Optional.
    • -
-

Allocates a new buffer containing the given str. -encoding defaults to 'utf8'. - -

-

buf.write(string, [offset], [length], [encoding])#

-
    -
  • string String - data to be written to buffer
    • -
  • offset Number, Optional, Default: 0
    • -
  • length Number, Optional, Default: buffer.length - offset
    • -
  • encoding String, Optional, Default: 'utf8'
    • -
-

Writes string to the buffer at offset using the given encoding. -offset defaults to 0, encoding defaults to 'utf8'. length is -the number of bytes to write. Returns number of octets written. If buffer did -not contain enough space to fit the entire string, it will write a partial -amount of the string. length defaults to buffer.length - offset. -The method will not write partial characters. - -

-
buf = new Buffer(256);
-len = buf.write('\u00bd + \u00bc = \u00be', 0);
-console.log(len + " bytes: " + buf.toString('utf8', 0, len));
-

The number of characters written (which may be different than the number of -bytes written) is set in Buffer._charsWritten and will be overwritten the -next time buf.write() is called. - - -

-

buf.toString([encoding], [start], [end])#

-
    -
  • encoding String, Optional, Default: 'utf8'
    • -
  • start Number, Optional, Default: 0
    • -
  • end Number, Optional, Default: buffer.length
    • -
-

Decodes and returns a string from buffer data encoded with encoding -(defaults to 'utf8') beginning at start (defaults to 0) and ending at -end (defaults to buffer.length). - -

-

See buffer.write() example, above. - - -

-

buf[index]#

- - - -

Get and set the octet at index. The values refer to individual bytes, -so the legal range is between 0x00 and 0xFF hex or 0 and 255. - -

-

Example: copy an ASCII string into a buffer, one byte at a time: - -

-
str = "node.js";
-buf = new Buffer(str.length);
-
-for (var i = 0; i < str.length ; i++) {
-  buf[i] = str.charCodeAt(i);
-}
-
-console.log(buf);
-
-// node.js
-

Class Method: Buffer.isBuffer(obj)#

-
    -
  • obj Object
    • -
  • Return: Boolean
    • -
-

Tests if obj is a Buffer. - -

-

Class Method: Buffer.byteLength(string, [encoding])#

-
    -
  • string String
    • -
  • encoding String, Optional, Default: 'utf8'
    • -
  • Return: Number
    • -
-

Gives the actual byte length of a string. encoding defaults to 'utf8'. -This is not the same as String.prototype.length since that returns the -number of characters in a string. - -

-

Example: - -

-
str = '\u00bd + \u00bc = \u00be';
-
-console.log(str + ": " + str.length + " characters, " +
-  Buffer.byteLength(str, 'utf8') + " bytes");
-
-// ½ + ¼ = ¾: 9 characters, 12 bytes
-

buf.length#

-
    -
  • Number
    • -
-

The size of the buffer in bytes. Note that this is not necessarily the size -of the contents. length refers to the amount of memory allocated for the -buffer object. It does not change when the contents of the buffer are changed. - -

-
buf = new Buffer(1234);
-
-console.log(buf.length);
-buf.write("some string", "ascii", 0);
-console.log(buf.length);
-
-// 1234
-// 1234
-

buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])#

-
    -
  • targetBuffer Buffer object - Buffer to copy into
    • -
  • targetStart Number, Optional, Default: 0
    • -
  • sourceStart Number, Optional, Default: 0
    • -
  • sourceEnd Number, Optional, Default: buffer.length
    • -
-

Does copy between buffers. The source and target regions can be overlapped. -targetStart and sourceStart default to 0. -sourceEnd defaults to buffer.length. - -

-

Example: build two Buffers, then copy buf1 from byte 16 through byte 19 -into buf2, starting at the 8th byte in buf2. - -

-
buf1 = new Buffer(26);
-buf2 = new Buffer(26);
-
-for (var i = 0 ; i < 26 ; i++) {
-  buf1[i] = i + 97; // 97 is ASCII a
-  buf2[i] = 33; // ASCII !
-}
-
-buf1.copy(buf2, 8, 16, 20);
-console.log(buf2.toString('ascii', 0, 25));
-
-// !!!!!!!!qrst!!!!!!!!!!!!!
-

buf.slice([start], [end])#

-
    -
  • start Number, Optional, Default: 0
    • -
  • end Number, Optional, Default: buffer.length
    • -
-

Returns a new buffer which references the same memory as the old, but offset -and cropped by the start (defaults to 0) and end (defaults to -buffer.length) indexes. - -

-

Modifying the new buffer slice will modify memory in the original buffer! - -

-

Example: build a Buffer with the ASCII alphabet, take a slice, then modify one -byte from the original Buffer. - -

-
var buf1 = new Buffer(26);
-
-for (var i = 0 ; i < 26 ; i++) {
-  buf1[i] = i + 97; // 97 is ASCII a
-}
-
-var buf2 = buf1.slice(0, 3);
-console.log(buf2.toString('ascii', 0, buf2.length));
-buf1[0] = 33;
-console.log(buf2.toString('ascii', 0, buf2.length));
-
-// abc
-// !bc
-

buf.readUInt8(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads an unsigned 8 bit integer from the buffer at the specified offset. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-
-buf[0] = 0x3;
-buf[1] = 0x4;
-buf[2] = 0x23;
-buf[3] = 0x42;
-
-for (ii = 0; ii < buf.length; ii++) {
-  console.log(buf.readUInt8(ii));
-}
-
-// 0x3
-// 0x4
-// 0x23
-// 0x42
-

buf.readUInt16LE(offset, [noAssert])#

-

buf.readUInt16BE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads an unsigned 16 bit integer from the buffer at the specified offset with -specified endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-
-buf[0] = 0x3;
-buf[1] = 0x4;
-buf[2] = 0x23;
-buf[3] = 0x42;
-
-console.log(buf.readUInt16BE(0));
-console.log(buf.readUInt16LE(0));
-console.log(buf.readUInt16BE(1));
-console.log(buf.readUInt16LE(1));
-console.log(buf.readUInt16BE(2));
-console.log(buf.readUInt16LE(2));
-
-// 0x0304
-// 0x0403
-// 0x0423
-// 0x2304
-// 0x2342
-// 0x4223
-

buf.readUInt32LE(offset, [noAssert])#

-

buf.readUInt32BE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads an unsigned 32 bit integer from the buffer at the specified offset with -specified endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-
-buf[0] = 0x3;
-buf[1] = 0x4;
-buf[2] = 0x23;
-buf[3] = 0x42;
-
-console.log(buf.readUInt32BE(0));
-console.log(buf.readUInt32LE(0));
-
-// 0x03042342
-// 0x42230403
-

buf.readInt8(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads a signed 8 bit integer from the buffer at the specified offset. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Works as buffer.readUInt8, except buffer contents are treated as two's -complement signed values. - -

-

buf.readInt16LE(offset, [noAssert])#

-

buf.readInt16BE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads a signed 16 bit integer from the buffer at the specified offset with -specified endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Works as buffer.readUInt16*, except buffer contents are treated as two's -complement signed values. - -

-

buf.readInt32LE(offset, [noAssert])#

-

buf.readInt32BE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads a signed 32 bit integer from the buffer at the specified offset with -specified endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Works as buffer.readUInt32*, except buffer contents are treated as two's -complement signed values. - -

-

buf.readFloatLE(offset, [noAssert])#

-

buf.readFloatBE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads a 32 bit float from the buffer at the specified offset with specified -endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-
-buf[0] = 0x00;
-buf[1] = 0x00;
-buf[2] = 0x80;
-buf[3] = 0x3f;
-
-console.log(buf.readFloatLE(0));
-
-// 0x01
-

buf.readDoubleLE(offset, [noAssert])#

-

buf.readDoubleBE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads a 64 bit double from the buffer at the specified offset with specified -endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(8);
-
-buf[0] = 0x55;
-buf[1] = 0x55;
-buf[2] = 0x55;
-buf[3] = 0x55;
-buf[4] = 0x55;
-buf[5] = 0x55;
-buf[6] = 0xd5;
-buf[7] = 0x3f;
-
-console.log(buf.readDoubleLE(0));
-
-// 0.3333333333333333
-

buf.writeUInt8(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset. Note, value must be a -valid unsigned 8 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-buf.writeUInt8(0x3, 0);
-buf.writeUInt8(0x4, 1);
-buf.writeUInt8(0x23, 2);
-buf.writeUInt8(0x42, 3);
-
-console.log(buf);
-
-// <Buffer 03 04 23 42>
-

buf.writeUInt16LE(value, offset, [noAssert])#

-

buf.writeUInt16BE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid unsigned 16 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-buf.writeUInt16BE(0xdead, 0);
-buf.writeUInt16BE(0xbeef, 2);
-
-console.log(buf);
-
-buf.writeUInt16LE(0xdead, 0);
-buf.writeUInt16LE(0xbeef, 2);
-
-console.log(buf);
-
-// <Buffer de ad be ef>
-// <Buffer ad de ef be>
-

buf.writeUInt32LE(value, offset, [noAssert])#

-

buf.writeUInt32BE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid unsigned 32 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-buf.writeUInt32BE(0xfeedface, 0);
-
-console.log(buf);
-
-buf.writeUInt32LE(0xfeedface, 0);
-
-console.log(buf);
-
-// <Buffer fe ed fa ce>
-// <Buffer ce fa ed fe>
-

buf.writeInt8(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset. Note, value must be a -valid signed 8 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Works as buffer.writeUInt8, except value is written out as a two's complement -signed integer into buffer. - -

-

buf.writeInt16LE(value, offset, [noAssert])#

-

buf.writeInt16BE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid signed 16 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Works as buffer.writeUInt16*, except value is written out as a two's -complement signed integer into buffer. - -

-

buf.writeInt32LE(value, offset, [noAssert])#

-

buf.writeInt32BE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid signed 32 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Works as buffer.writeUInt32*, except value is written out as a two's -complement signed integer into buffer. - -

-

buf.writeFloatLE(value, offset, [noAssert])#

-

buf.writeFloatBE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid 32 bit float. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-buf.writeFloatBE(0xcafebabe, 0);
-
-console.log(buf);
-
-buf.writeFloatLE(0xcafebabe, 0);
-
-console.log(buf);
-
-// <Buffer 4f 4a fe bb>
-// <Buffer bb fe 4a 4f>
-

buf.writeDoubleLE(value, offset, [noAssert])#

-

buf.writeDoubleBE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid 64 bit double. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(8);
-buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
-
-console.log(buf);
-
-buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
-
-console.log(buf);
-
-// <Buffer 43 eb d5 b7 dd f9 5f d7>
-// <Buffer d7 5f f9 dd b7 d5 eb 43>
-

buf.fill(value, [offset], [end])#

-
    -
  • value
    • -
  • offset Number, Optional
    • -
  • end Number, Optional
    • -
-

Fills the buffer with the specified value. If the offset (defaults to 0) -and end (defaults to buffer.length) are not given it will fill the entire -buffer. - -

-
var b = new Buffer(50);
-b.fill("h");
-

buffer.INSPECT_MAX_BYTES#

-
    -
  • Number, Default: 50
    • -
-

How many bytes will be returned when buffer.inspect() is called. This can -be overridden by user modules. - -

-

Note that this is a property on the buffer module returned by -require('buffer'), not on the Buffer global, or a buffer instance. - -

-

Class: SlowBuffer#

-

This class is primarily for internal use. JavaScript programs should -use Buffer instead of using SlowBuffer. - -

-

In order to avoid the overhead of allocating many C++ Buffer objects for -small blocks of memory in the lifetime of a server, Node allocates memory -in 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it -will be backed by a parent SlowBuffer object. If it is larger than this, -then Node will allocate a SlowBuffer slab for it directly. - -

-

Stream#

-
Stability: 2 - Unstable
-

A stream is an abstract interface implemented by various objects in Node. -For example a request to an HTTP server is a stream, as is stdout. Streams -are readable, writable, or both. All streams are instances of EventEmitter. - -

-

You can load up the Stream base class by doing require('stream'). - -

-

Readable Stream#

- - -

A Readable Stream has the following methods, members, and events. - -

-

Event: 'data'#

-

function (data) { } - -

-

The 'data' event emits either a Buffer (by default) or a string if -setEncoding() was used. - -

-

Note that the data will be lost if there is no listener when a -Readable Stream emits a 'data' event. - -

-

Event: 'end'#

-

function () { } - -

-

Emitted when the stream has received an EOF (FIN in TCP terminology). -Indicates that no more 'data' events will happen. If the stream is also -writable, it may be possible to continue writing. - -

-

Event: 'error'#

-

function (exception) { } - -

-

Emitted if there was an error receiving data. - -

-

Event: 'close'#

-

function () { } - -

-

Emitted when the underlying file descriptor has been closed. Not all streams -will emit this. (For example, an incoming HTTP request will not emit -'close'.) - -

-

stream.readable#

-

A boolean that is true by default, but turns false after an 'error' -occurred, the stream came to an 'end', or destroy() was called. - -

-

stream.setEncoding(encoding)#

-

Makes the data event emit a string instead of a Buffer. encoding can be -'utf8', 'ascii', or 'base64'. - -

-

stream.pause()#

-

Pauses the incoming 'data' events. - -

-

stream.resume()#

-

Resumes the incoming 'data' events after a pause(). - -

-

stream.destroy()#

-

Closes the underlying file descriptor. Stream will not emit any more events. - -

-

stream.pipe(destination, [options])#

-

This is a Stream.prototype method available on all Streams. - -

-

Connects this read stream to destination WriteStream. Incoming -data on this stream gets written to destination. The destination and source -streams are kept in sync by pausing and resuming as necessary. - -

-

This function returns the destination stream. - -

-

Emulating the Unix cat command: - -

-
process.stdin.resume();
-process.stdin.pipe(process.stdout);
-

By default end() is called on the destination when the source stream emits -end, so that destination is no longer writable. Pass { end: false } as -options to keep the destination stream open. - -

-

This keeps process.stdout open so that "Goodbye" can be written at the end. - -

-
process.stdin.resume();
-
-process.stdin.pipe(process.stdout, { end: false });
-
-process.stdin.on("end", function() {
-  process.stdout.write("Goodbye\n");
-});
-

Writable Stream#

- - -

A Writable Stream has the following methods, members, and events. - -

-

Event: 'drain'#

-

function () { } - -

-

After a write() method returned false, this event is emitted to -indicate that it is safe to write again. - -

-

Event: 'error'#

-

function (exception) { } - -

-

Emitted on error with the exception exception. - -

-

Event: 'close'#

-

function () { } - -

-

Emitted when the underlying file descriptor has been closed. - -

-

Event: 'pipe'#

-

function (src) { } - -

-

Emitted when the stream is passed to a readable stream's pipe method. - -

-

stream.writable#

-

A boolean that is true by default, but turns false after an 'error' -occurred or end() / destroy() was called. - -

-

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)#

-

Same as the above except with a raw buffer. - -

-

stream.end()#

-

Terminates the stream with EOF or FIN. -This call will allow queued write data to be sent before closing the stream. - -

-

stream.end(string, encoding)#

-

Sends string with the given encoding and terminates the stream with EOF -or FIN. This is useful to reduce the number of packets sent. - -

-

stream.end(buffer)#

-

Same as above but with a buffer. - -

-

stream.destroy()#

-

Closes the underlying file descriptor. Stream will not emit any more events. -Any queued write data will not be sent. - -

-

stream.destroySoon()#

-

After the write queue is drained, close the file descriptor. destroySoon() -can still destroy straight away, as long as there is no data left in the queue -for writes. - -

-

Crypto#

-
Stability: 3 - Stable
-

Use require('crypto') to access this module. - -

-

The crypto module requires OpenSSL to be available on the underlying platform. -It offers a way of encapsulating secure credentials to be used as part -of a secure HTTPS net or http connection. - -

-

It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods. - -

-

crypto.createCredentials(details)#

-

Creates a credentials object, with the optional details being a dictionary with keys: - -

-
    -
  • pfx : A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
    • -
  • key : a string holding the PEM encoded private key
    • -
  • cert : a string holding the PEM encoded certificate
    • -
  • passphrase : A string of passphrase for the private key or pfx
    • -
  • ca : either a string or list of strings of PEM encoded CA certificates to trust.
    • -
  • ciphers: a string describing the ciphers to use or exclude. Consult -http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details -on the format.
    • -
-

If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in -

-

http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt. - - -

-

crypto.createHash(algorithm)#

-

Creates and returns a hash object, a cryptographic hash with the given algorithm -which can be used to generate hash digests. - -

-

algorithm is dependent on the available algorithms supported by the version -of OpenSSL on the platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', etc. -On recent releases, openssl list-message-digest-algorithms will display the available digest algorithms. - -

-

Example: this program that takes the sha1 sum of a file - -

-
var filename = process.argv[2];
-var crypto = require('crypto');
-var fs = require('fs');
-
-var shasum = crypto.createHash('sha1');
-
-var s = fs.ReadStream(filename);
-s.on('data', function(d) {
-  shasum.update(d);
-});
-
-s.on('end', function() {
-  var d = shasum.digest('hex');
-  console.log(d + '  ' + filename);
-});
-

Class: Hash#

-

The class for creating hash digests of data. - -

-

Returned by crypto.createHash. - -

-

hash.update(data, [input_encoding])#

-

Updates the hash content with the given data, the encoding of which is given -in input_encoding and can be 'utf8', 'ascii' or 'binary'. -Defaults to 'binary'. -This can be called many times with new data as it is streamed. - -

-

hash.digest([encoding])#

-

Calculates the digest of all of the passed data to be hashed. -The encoding can be 'hex', 'binary' or 'base64'. -Defaults to 'binary'. - -

-

Note: hash object can not be used after digest() method been called. - - -

-

crypto.createHmac(algorithm, key)#

-

Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key. - -

-

algorithm is dependent on the available algorithms supported by OpenSSL - see createHash above. -key is the hmac key to be used. - -

-

Class: Hmac#

-

Class for creating cryptographic hmac content. - -

-

Returned by crypto.createHmac. - -

-

hmac.update(data)#

-

Update the hmac content with the given data. -This can be called many times with new data as it is streamed. - -

-

hmac.digest([encoding])#

-

Calculates the digest of all of the passed data to the hmac. -The encoding can be 'hex', 'binary' or 'base64'. -Defaults to 'binary'. - -

-

Note: hmac object can not be used after digest() method been called. - - -

-

crypto.createCipher(algorithm, password)#

-

Creates and returns a cipher object, with the given algorithm and password. - -

-

algorithm is dependent on OpenSSL, examples are 'aes192', etc. -On recent releases, openssl list-cipher-algorithms will display the -available cipher algorithms. -password is used to derive key and IV, which must be 'binary' encoded -string (See the Buffer section for more information). - -

-

crypto.createCipheriv(algorithm, key, iv)#

-

Creates and returns a cipher object, with the given algorithm, key and iv. - -

-

algorithm is the same as the createCipher(). key is a raw key used in -algorithm. iv is an Initialization vector. key and iv must be 'binary' -encoded string (See the Buffer section for more information). - -

-

Class: Cipher#

-

Class for encrypting data. - -

-

Returned by crypto.createCipher and crypto.createCipheriv. - -

-

cipher.update(data, [input_encoding], [output_encoding])#

-

Updates the cipher with data, the encoding of which is given in -input_encoding and can be 'utf8', 'ascii' or 'binary'. -Defaults to 'binary'. - -

-

The output_encoding specifies the output format of the enciphered data, -and can be 'binary', 'base64' or 'hex'. Defaults to 'binary'. - -

-

Returns the enciphered contents, and can be called many times with new data as it is streamed. - -

-

cipher.final([output_encoding])#

-

Returns any remaining enciphered contents, with output_encoding being one of: -'binary', 'base64' or 'hex'. Defaults to 'binary'. - -

-

Note: cipher object can not be used after final() method been called. - - -

-

crypto.createDecipher(algorithm, password)#

-

Creates and returns a decipher object, with the given algorithm and key. -This is the mirror of the createCipher() above. - -

-

crypto.createDecipheriv(algorithm, key, iv)#

-

Creates and returns a decipher object, with the given algorithm, key and iv. -This is the mirror of the createCipheriv() above. - -

-

Class: Decipher#

-

Class for decrypting data. - -

-

Returned by crypto.createDecipher and crypto.createDecipheriv. - -

-

decipher.update(data, [input_encoding], [output_encoding])#

-

Updates the decipher with data, which is encoded in 'binary', 'base64' -or 'hex'. Defaults to 'binary'. - -

-

The output_decoding specifies in what format to return the deciphered -plaintext: 'binary', 'ascii' or 'utf8'. Defaults to 'binary'. - -

-

decipher.final([output_encoding])#

-

Returns any remaining plaintext which is deciphered, -with output_encoding being one of: 'binary', 'ascii' or 'utf8'. -Defaults to 'binary'. - -

-

Note: decipher object can not be used after final() method been called. - - -

-

crypto.createSign(algorithm)#

-

Creates and returns a signing object, with the given algorithm. -On recent OpenSSL releases, openssl list-public-key-algorithms will display -the available signing algorithms. Examples are 'RSA-SHA256'. - -

-

Class: Signer#

-

Class for generating signatures. - -

-

Returned by crypto.createSign. - -

-

signer.update(data)#

-

Updates the signer object with data. -This can be called many times with new data as it is streamed. - -

-

signer.sign(private_key, [output_format])#

-

Calculates the signature on all the updated data passed through the signer. -private_key is a string containing the PEM encoded private key for signing. - -

-

Returns the signature in output_format which can be 'binary', 'hex' or -'base64'. Defaults to 'binary'. - -

-

Note: signer object can not be used after sign() method been called. - -

-

crypto.createVerify(algorithm)#

-

Creates and returns a verification object, with the given algorithm. -This is the mirror of the signing object above. - -

-

Class: Verify#

-

Class for verifying signatures. - -

-

Returned by crypto.createVerify. - -

-

verifier.update(data)#

-

Updates the verifier object with data. -This can be called many times with new data as it is streamed. - -

-

verifier.verify(object, signature, [signature_format])#

-

Verifies the signed data by using the object and signature. object is a -string containing a PEM encoded object, which can be one of RSA public key, -DSA public key, or X.509 certificate. signature is the previously calculated -signature for the data, in the signature_format which can be 'binary', -'hex' or 'base64'. Defaults to 'binary'. - -

-

Returns true or false depending on the validity of the signature for the data and public key. - -

-

Note: verifier object can not be used after verify() method been called. - -

-

crypto.createDiffieHellman(prime_length)#

-

Creates a Diffie-Hellman key exchange object and generates a prime of the -given bit length. The generator used is 2. - -

-

crypto.createDiffieHellman(prime, [encoding])#

-

Creates a Diffie-Hellman key exchange object using the supplied prime. The -generator used is 2. Encoding can be 'binary', 'hex', or 'base64'. -Defaults to 'binary'. - -

-

Class: DiffieHellman#

-

The class for creating Diffie-Hellman key exchanges. - -

-

Returned by crypto.createDiffieHellman. - -

-

diffieHellman.generateKeys([encoding])#

-

Generates private and public Diffie-Hellman key values, and returns the -public key in the specified encoding. This key should be transferred to the -other party. Encoding can be 'binary', 'hex', or 'base64'. -Defaults to 'binary'. - -

-

diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])#

-

Computes the shared secret using other_public_key as the other party's -public key and returns the computed shared secret. Supplied key is -interpreted using specified input_encoding, and secret is encoded using -specified output_encoding. Encodings can be 'binary', 'hex', or -'base64'. The input encoding defaults to 'binary'. -If no output encoding is given, the input encoding is used as output encoding. - -

-

diffieHellman.getPrime([encoding])#

-

Returns the Diffie-Hellman prime in the specified encoding, which can be -'binary', 'hex', or 'base64'. Defaults to 'binary'. - -

-

diffieHellman.getGenerator([encoding])#

-

Returns the Diffie-Hellman prime in the specified encoding, which can be -'binary', 'hex', or 'base64'. Defaults to 'binary'. - -

-

diffieHellman.getPublicKey([encoding])#

-

Returns the Diffie-Hellman public key in the specified encoding, which can -be 'binary', 'hex', or 'base64'. Defaults to 'binary'. - -

-

diffieHellman.getPrivateKey([encoding])#

-

Returns the Diffie-Hellman private key in the specified encoding, which can -be 'binary', 'hex', or 'base64'. Defaults to 'binary'. - -

-

diffieHellman.setPublicKey(public_key, [encoding])#

-

Sets the Diffie-Hellman public key. Key encoding can be 'binary', 'hex', -or 'base64'. Defaults to 'binary'. - -

-

diffieHellman.setPrivateKey(public_key, [encoding])#

-

Sets the Diffie-Hellman private key. Key encoding can be 'binary', 'hex', -or 'base64'. Defaults to 'binary'. - -

-

crypto.pbkdf2(password, salt, iterations, keylen, callback)#

-

Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive -a key of given length from the given password, salt and iterations. -The callback gets two arguments (err, derivedKey). - -

-

crypto.randomBytes(size, [callback])#

-

Generates cryptographically strong pseudo-random data. Usage: - -

-
// async
-crypto.randomBytes(256, function(ex, buf) {
-  if (ex) throw ex;
-  console.log('Have %d bytes of random data: %s', buf.length, buf);
-});
-
-// sync
-try {
-  var buf = crypto.randomBytes(256);
-  console.log('Have %d bytes of random data: %s', buf.length, buf);
-} catch (ex) {
-  // handle error
-}
-

TLS (SSL)#

-
Stability: 3 - Stable
-

Use require('tls') to access this module. - -

-

The tls module uses OpenSSL to provide Transport Layer Security and/or -Secure Socket Layer: encrypted stream communication. - -

-

TLS/SSL is a public/private key infrastructure. Each client and each -server must have a private key. A private key is created like this - -

-
openssl genrsa -out ryans-key.pem 1024
-

All severs and some clients need to have a certificate. Certificates are public -keys signed by a Certificate Authority or self-signed. The first step to -getting a certificate is to create a "Certificate Signing Request" (CSR) -file. This is done with: - -

-
openssl req -new -key ryans-key.pem -out ryans-csr.pem
-

To create a self-signed certificate with the CSR, do this: - -

-
openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem
-

Alternatively you can send the CSR to a Certificate Authority for signing. - -

-

(TODO: docs on creating a CA, for now interested users should just look at -test/fixtures/keys/Makefile in the Node source code) - -

-

To create .pfx or .p12, do this: - -

-
openssl pkcs12 -export -in agent5-cert.pem -inkey agent5-key.pem \
-    -certfile ca-cert.pem -out agent5.pfx
-
    -
  • in: certificate
    • -
  • inkey: private key
    • -
  • certfile: all CA certs concatenated in one file like -cat ca1-cert.pem ca2-cert.pem > ca-cert.pem
    • -
-

Client-initiated renegotiation attack mitigation#

- - -

The TLS protocol lets the client renegotiate certain aspects of the TLS session. -Unfortunately, session renegotiation requires a disproportional amount of -server-side resources, which makes it a potential vector for denial-of-service -attacks. - -

-

To mitigate this, renegotiations are limited to three times every 10 minutes. An -error is emitted on the CleartextStream instance when -the threshold is exceeded. The limits are configurable: - -

-
    -

  • tls.CLIENT_RENEG_LIMIT: renegotiation limit, default is 3.

    -
    • -

  • tls.CLIENT_RENEG_WINDOW: renegotiation window in seconds, default is

    -
                           10 minutes.
    -
    • -
-

Don't change the defaults unless you know what you are doing. - -

-

To test your server, connect to it with openssl s_client -connect address:port -and tap R<CR> (that's the letter R followed by a carriage return) a few -times. - - -

-

NPN and SNI#

- - -

NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS -handshake extensions allowing you: - -

-
    -
  • NPN - to use one TLS server for multiple protocols (HTTP, SPDY)
    • -
  • SNI - to use one TLS server for multiple hostnames with different SSL -certificates.
    • -
-

tls.createServer(options, [secureConnectionListener])#

-

Creates a new tls.Server. -The connectionListener argument is automatically set as a listener for the -secureConnection event. -The options object has these possibilities: - -

-
    -

  • pfx: A string or Buffer containing the private key, certificate and -CA certs of the server in PFX or PKCS12 format. (Mutually exclusive with -the key, cert and ca options.)

    -
    • -

  • key: A string or Buffer containing the private key of the server in -PEM format. (Required)

    -
    • -

  • passphrase: A string of passphrase for the private key or pfx.

    -
    • -

  • cert: A string or Buffer containing the certificate key of the server in -PEM format. (Required)

    -
    • -

  • ca: An array of strings or Buffers of trusted certificates. If this is -omitted several well known "root" CAs will be used, like VeriSign. -These are used to authorize connections.

    -
    • -

  • ciphers: A string describing the ciphers to use or exclude. Consult -http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for -details on the format.

    -
    • -

  • requestCert: If true the server will request a certificate from -clients that connect and attempt to verify that certificate. Default: -false.

    -
    • -

  • rejectUnauthorized: If true the server will reject any connection -which is not authorized with the list of supplied CAs. This option only -has an effect if requestCert is true. Default: false.

    -
    • -

  • NPNProtocols: An array or Buffer of possible NPN protocols. (Protocols -should be ordered by their priority).

    -
    • -

  • SNICallback: A function that will be called if client supports SNI TLS -extension. Only one argument will be passed to it: servername. And -SNICallback should return SecureContext instance. -(You can use crypto.createCredentials(...).context to get proper -SecureContext). If SNICallback wasn't provided - default callback with -high-level API will be used (see below).

    -
    • -

  • sessionIdContext: A string containing a opaque identifier for session -resumption. If requestCert is true, the default is MD5 hash value -generated from command-line. Otherwise, the default is not provided.

    -
    • -
-

Here is a simple example echo server: - -

-
var tls = require('tls');
-var fs = require('fs');
-
-var options = {
-  key: fs.readFileSync('server-key.pem'),
-  cert: fs.readFileSync('server-cert.pem'),
-
-  // This is necessary only if using the client certificate authentication.
-  requestCert: true,
-
-  // This is necessary only if the client uses the self-signed certificate.
-  ca: [ fs.readFileSync('client-cert.pem') ]
-};
-
-var server = tls.createServer(options, function(cleartextStream) {
-  console.log('server connected',
-              cleartextStream.authorized ? 'authorized' : 'unauthorized');
-  cleartextStream.write("welcome!\n");
-  cleartextStream.setEncoding('utf8');
-  cleartextStream.pipe(cleartextStream);
-});
-server.listen(8000, function() {
-  console.log('server bound');
-});
-

Or - -

-
var tls = require('tls');
-var fs = require('fs');
-
-var options = {
-  pfx: fs.readFileSync('server.pfx'),
-
-  // This is necessary only if using the client certificate authentication.
-  requestCert: true,
-
-};
-
-var server = tls.createServer(options, function(cleartextStream) {
-  console.log('server connected',
-              cleartextStream.authorized ? 'authorized' : 'unauthorized');
-  cleartextStream.write("welcome!\n");
-  cleartextStream.setEncoding('utf8');
-  cleartextStream.pipe(cleartextStream);
-});
-server.listen(8000, function() {
-  console.log('server bound');
-});
-

You can test this server by connecting to it with openssl s_client: - - -

-
openssl s_client -connect 127.0.0.1:8000
-

tls.connect(port, [host], [options], [secureConnectListener])#

-

Creates a new client connection to the given port and host. (If host -defaults to localhost.) options should be an object which specifies - -

-
    -

  • pfx: A string or Buffer containing the private key, certificate and -CA certs of the server in PFX or PKCS12 format.

    -
    • -

  • key: A string or Buffer containing the private key of the client in -PEM format.

    -
    • -

  • passphrase: A string of passphrase for the private key or pfx.

    -
    • -

  • cert: A string or Buffer containing the certificate key of the client in -PEM format.

    -
    • -

  • ca: An array of strings or Buffers of trusted certificates. If this is -omitted several well known "root" CAs will be used, like VeriSign. -These are used to authorize connections.

    -
    • -

  • NPNProtocols: An array of string or Buffer containing supported NPN -protocols. Buffer should have following format: 0x05hello0x05world, -where first byte is next protocol name's length. (Passing array should -usually be much simpler: ['hello', 'world'].)

    -
    • -

  • servername: Servername for SNI (Server Name Indication) TLS extension.

    -
    • -

  • socket: Establish secure connection on a given socket rather than -creating a new socket. If this option is specified, host and port -are ignored. This is intended FOR INTERNAL USE ONLY. As with all -undocumented APIs in Node, they should not be used.

    -
    • -
-

The secureConnectListener parameter will be added as a listener for the -'secureConnect' event. - -

-

tls.connect() returns a CleartextStream object. - -

-

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

-
var tls = require('tls');
-var fs = require('fs');
-
-var options = {
-  // These are necessary only if using the client certificate authentication
-  key: fs.readFileSync('client-key.pem'),
-  cert: fs.readFileSync('client-cert.pem'),
-
-  // This is necessary only if the server uses the self-signed certificate
-  ca: [ fs.readFileSync('server-cert.pem') ]
-};
-
-var cleartextStream = tls.connect(8000, options, function() {
-  console.log('client connected',
-              cleartextStream.authorized ? 'authorized' : 'unauthorized');
-  process.stdin.pipe(cleartextStream);
-  process.stdin.resume();
-});
-cleartextStream.setEncoding('utf8');
-cleartextStream.on('data', function(data) {
-  console.log(data);
-});
-cleartextStream.on('end', function() {
-  server.close();
-});
-

Or - -

-
var tls = require('tls');
-var fs = require('fs');
-
-var options = {
-  pfx: fs.readFileSync('client.pfx')
-};
-
-var cleartextStream = tls.connect(8000, options, function() {
-  console.log('client connected',
-              cleartextStream.authorized ? 'authorized' : 'unauthorized');
-  process.stdin.pipe(cleartextStream);
-  process.stdin.resume();
-});
-cleartextStream.setEncoding('utf8');
-cleartextStream.on('data', function(data) {
-  console.log(data);
-});
-cleartextStream.on('end', function() {
-  server.close();
-});
-

tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])#

-

Creates a new secure pair object with two streams, one of which reads/writes -encrypted data, and one reads/writes cleartext data. -Generally the encrypted one is piped to/from an incoming encrypted data stream, -and the cleartext one is used as a replacement for the initial encrypted stream. - -

-
    -

  • credentials: A credentials object from crypto.createCredentials( ... )

    -
    • -

  • isServer: A boolean indicating whether this tls connection should be -opened as a server or a client.

    -
    • -

  • requestCert: A boolean indicating whether a server should request a -certificate from a connecting client. Only applies to server connections.

    -
    • -

  • rejectUnauthorized: A boolean indicating whether a server should -automatically reject clients with invalid certificates. Only applies to -servers with requestCert enabled.

    -
    • -
-

tls.createSecurePair() returns a SecurePair object with -cleartext and encrypted stream properties. - -

-

Class: SecurePair#

-

Returned by tls.createSecurePair. - -

-

Event: 'secure'#

-

The event is emitted from the SecurePair once the pair has successfully -established a secure connection. - -

-

Similarly to the checking for the server 'secureConnection' event, -pair.cleartext.authorized should be checked to confirm whether the certificate -used properly authorized. - -

-

Class: tls.Server#

-

This class is a subclass of net.Server and has the same methods on it. -Instead of accepting just raw TCP connections, this accepts encrypted -connections using TLS or SSL. - -

-

Event: 'secureConnection'#

-

function (cleartextStream) {} - -

-

This event is emitted after a new connection has been successfully -handshaked. The argument is a instance of -CleartextStream. It has all the common stream methods -and events. - -

-

cleartextStream.authorized is a boolean value which indicates if the -client has verified by one of the supplied certificate authorities for the -server. If cleartextStream.authorized is false, then -cleartextStream.authorizationError is set to describe how authorization -failed. Implied but worth mentioning: depending on the settings of the TLS -server, you unauthorized connections may be accepted. -cleartextStream.npnProtocol is a string containing selected NPN protocol. -cleartextStream.servername is a string containing servername requested with -SNI. - - -

-

Event: 'clientError'#

-

function (exception) { } - -

-

When a client connection emits an 'error' event before secure connection is -established - it will be forwarded here. - - -

-

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

-

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). - -

-

This function is asynchronous. The last parameter callback will be called -when the server has been bound. - -

-

See net.Server for more information. - - -

-

server.close()#

-

Stops the server from accepting new connections. This function is -asynchronous, the server is finally closed when the server emits a 'close' -event. - -

-

server.address()#

-

Returns the bound address and port of the server as reported by the operating -system. -See net.Server.address() for more information. - -

-

server.addContext(hostname, credentials)#

-

Add secure context that will be used if client request's SNI hostname is -matching passed hostname (wildcards can be used). credentials can contain -key, cert and ca. - -

-

server.maxConnections#

-

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

-

server.connections#

-

The number of concurrent connections on the server. - - -

-

Class: tls.CleartextStream#

-

This is a stream on top of the Encrypted stream that makes it possible to -read/write an encrypted data as a cleartext data. - -

-

This instance implements a duplex Stream interfaces. -It has all the common stream methods and events. - -

-

A ClearTextStream is the clear member of a SecurePair object. - -

-

Event: 'secureConnect'#

-

This event is emitted after a new connection has been successfully handshaked. -The listener will be called no matter if the server's certificate was -authorized or not. It is up to the user to test cleartextStream.authorized -to see if the server certificate was signed by one of the specified CAs. -If cleartextStream.authorized === false then the error can be found in -cleartextStream.authorizationError. Also if NPN was used - you can check -cleartextStream.npnProtocol for negotiated protocol. - -

-

cleartextStream.authorized#

-

A boolean that is true if the peer certificate was signed by one of the -specified CAs, otherwise false - -

-

cleartextStream.authorizationError#

-

The reason why the peer's certificate has not been verified. This property -becomes available only when cleartextStream.authorized === false. - -

-

cleartextStream.getPeerCertificate()#

-

Returns an object representing the peer's certificate. The returned object has -some properties corresponding to the field of the certificate. - -

-

Example: - -

-
{ subject: 
-   { C: 'UK',
-     ST: 'Acknack Ltd',
-     L: 'Rhys Jones',
-     O: 'node.js',
-     OU: 'Test TLS Certificate',
-     CN: 'localhost' },
-  issuer: 
-   { C: 'UK',
-     ST: 'Acknack Ltd',
-     L: 'Rhys Jones',
-     O: 'node.js',
-     OU: 'Test TLS Certificate',
-     CN: 'localhost' },
-  valid_from: 'Nov 11 09:52:22 2009 GMT',
-  valid_to: 'Nov  6 09:52:22 2029 GMT',
-  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF' }
-

If the peer does not provide a certificate, it returns null or an empty -object. - -

-

cleartextStream.address()#

-

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

-

cleartextStream.remoteAddress#

-

The string representation of the remote IP address. For example, -'74.125.127.100' or '2001:4860:a005::68'. - -

-

cleartextStream.remotePort#

-

The numeric representation of the remote port. For example, 443. - - -

-

File System#

-
Stability: 3 - Stable
- - -

File I/O is provided by simple wrappers around standard POSIX functions. To -use this module do require('fs'). All the methods have asynchronous and -synchronous forms. - -

-

The asynchronous form always take a completion callback as its last argument. -The arguments passed to the completion callback depend on the method, but the -first argument is always reserved for an exception. If the operation was -completed successfully, then the first argument will be null or undefined. - -

-

When using the synchronous form any exceptions are immediately thrown. -You can use try/catch to handle exceptions or allow them to bubble up. - -

-

Here is an example of the asynchronous version: - -

-
var fs = require('fs');
-
-fs.unlink('/tmp/hello', function (err) {
-  if (err) throw err;
-  console.log('successfully deleted /tmp/hello');
-});
-

Here is the synchronous version: - -

-
var fs = require('fs');
-
-fs.unlinkSync('/tmp/hello')
-console.log('successfully deleted /tmp/hello');
-

With the asynchronous methods there is no guaranteed ordering. So the -following is prone to error: - -

-
fs.rename('/tmp/hello', '/tmp/world', function (err) {
-  if (err) throw err;
-  console.log('renamed complete');
-});
-fs.stat('/tmp/world', function (err, stats) {
-  if (err) throw err;
-  console.log('stats: ' + JSON.stringify(stats));
-});
-

It could be that fs.stat is executed before fs.rename. -The correct way to do this is to chain the callbacks. - -

-
fs.rename('/tmp/hello', '/tmp/world', function (err) {
-  if (err) throw err;
-  fs.stat('/tmp/world', function (err, stats) {
-    if (err) throw err;
-    console.log('stats: ' + JSON.stringify(stats));
-  });
-});
-

In busy processes, the programmer is strongly encouraged to use the -asynchronous versions of these calls. The synchronous versions will block -the entire process until they complete--halting all connections. - -

-

Relative path to filename can be used, remember however that this path will be relative -to process.cwd(). - -

-

fs.rename(path1, path2, [callback])#

-

Asynchronous rename(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.renameSync(path1, path2)#

-

Synchronous rename(2). - -

-

fs.truncate(fd, len, [callback])#

-

Asynchronous ftruncate(2). No arguments other than a possible exception are -given to the completion callback. - -

-

fs.truncateSync(fd, len)#

-

Synchronous ftruncate(2). - -

-

fs.chown(path, uid, gid, [callback])#

-

Asynchronous chown(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.chownSync(path, uid, gid)#

-

Synchronous chown(2). - -

-

fs.fchown(fd, uid, gid, [callback])#

-

Asynchronous fchown(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.fchownSync(fd, uid, gid)#

-

Synchronous fchown(2). - -

-

fs.lchown(path, uid, gid, [callback])#

-

Asynchronous lchown(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.lchownSync(path, uid, gid)#

-

Synchronous lchown(2). - -

-

fs.chmod(path, mode, [callback])#

-

Asynchronous chmod(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.chmodSync(path, mode)#

-

Synchronous chmod(2). - -

-

fs.fchmod(fd, mode, [callback])#

-

Asynchronous fchmod(2). No arguments other than a possible exception -are given to the completion callback. - -

-

fs.fchmodSync(fd, mode)#

-

Synchronous fchmod(2). - -

-

fs.lchmod(path, mode, [callback])#

-

Asynchronous lchmod(2). No arguments other than a possible exception -are given to the completion callback. - -

-

fs.lchmodSync(path, mode)#

-

Synchronous lchmod(2). - -

-

fs.stat(path, [callback])#

-

Asynchronous stat(2). The callback gets two arguments (err, stats) where -stats is a fs.Stats object. See the fs.Stats -section below for more information. - -

-

fs.lstat(path, [callback])#

-

Asynchronous lstat(2). The callback gets two arguments (err, stats) where -stats is a fs.Stats object. lstat() is identical to stat(), except that if -path is a symbolic link, then the link itself is stat-ed, not the file that it -refers to. - -

-

fs.fstat(fd, [callback])#

-

Asynchronous fstat(2). The callback gets two arguments (err, stats) where -stats is a fs.Stats object. fstat() is identical to stat(), except that -the file to be stat-ed is specified by the file descriptor fd. - -

-

fs.statSync(path)#

-

Synchronous stat(2). Returns an instance of fs.Stats. - -

-

fs.lstatSync(path)#

-

Synchronous lstat(2). Returns an instance of fs.Stats. - -

-

fs.fstatSync(fd)#

-

Synchronous fstat(2). Returns an instance of fs.Stats. - -

-

fs.link(srcpath, dstpath, [callback])#

-

Asynchronous link(2). No arguments other than a possible exception are given to -the completion callback. - -

-

fs.linkSync(srcpath, dstpath)#

-

Synchronous link(2). - -

-

fs.symlink(linkdata, path, [type], [callback])#

-

Asynchronous symlink(2). No arguments other than a possible exception are given -to the completion callback. -type argument can be either 'dir' or 'file' (default is 'file'). It is only -used on Windows (ignored on other platforms). - -

-

fs.symlinkSync(linkdata, path, [type])#

-

Synchronous symlink(2). - -

-

fs.readlink(path, [callback])#

-

Asynchronous readlink(2). The callback gets two arguments (err, -linkString). - -

-

fs.readlinkSync(path)#

-

Synchronous readlink(2). Returns the symbolic link's string value. - -

-

fs.realpath(path, [callback])#

-

Asynchronous realpath(2). The callback gets two arguments (err, -resolvedPath). May use process.cwd to resolve relative paths. - -

-

fs.realpathSync(path)#

-

Synchronous realpath(2). Returns the resolved path. - -

-

fs.unlink(path, [callback])#

-

Asynchronous unlink(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.unlinkSync(path)#

-

Synchronous unlink(2). - -

-

fs.rmdir(path, [callback])#

-

Asynchronous rmdir(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.rmdirSync(path)#

-

Synchronous rmdir(2). - -

-

fs.mkdir(path, [mode], [callback])#

-

Asynchronous mkdir(2). No arguments other than a possible exception are given -to the completion callback. mode defaults to 0777. - -

-

fs.mkdirSync(path, [mode])#

-

Synchronous mkdir(2). - -

-

fs.readdir(path, [callback])#

-

Asynchronous readdir(3). Reads the contents of a directory. -The callback gets two arguments (err, files) where files is an array of -the names of the files in the directory excluding '.' and '..'. - -

-

fs.readdirSync(path)#

-

Synchronous readdir(3). Returns an array of filenames excluding '.' and -'..'. - -

-

fs.close(fd, [callback])#

-

Asynchronous close(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.closeSync(fd)#

-

Synchronous close(2). - -

-

fs.open(path, flags, [mode], [callback])#

-

Asynchronous file open. See open(2). flags can be: - -

-
    -

  • 'r' - Open file for reading. -An exception occurs if the file does not exist.

    -
    • -

  • 'r+' - Open file for reading and writing. -An exception occurs if the file does not exist.

    -
    • -

  • 'w' - Open file for writing. -The file is created (if it does not exist) or truncated (if it exists).

    -
    • -

  • 'w+' - Open file for reading and writing. -The file is created (if it does not exist) or truncated (if it exists).

    -
    • -

  • 'a' - Open file for appending. -The file is created if it does not exist.

    -
    • -

  • 'a+' - Open file for reading and appending. -The file is created if it does not exist.

    -
    • -
-

mode defaults to 0666. The callback gets two arguments (err, fd). - -

-

fs.openSync(path, flags, [mode])#

-

Synchronous open(2). - -

-

fs.utimes(path, atime, mtime, [callback])#

-

fs.utimesSync(path, atime, mtime)#

-

Change file timestamps of the file referenced by the supplied path. - -

-

fs.futimes(fd, atime, mtime, [callback])#

-

fs.futimesSync(fd, atime, mtime)#

-

Change the file timestamps of a file referenced by the supplied file -descriptor. - -

-

fs.fsync(fd, [callback])#

-

Asynchronous fsync(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.fsyncSync(fd)#

-

Synchronous fsync(2). - -

-

fs.write(fd, buffer, offset, length, position, [callback])#

-

Write buffer to the file specified by fd. - -

-

offset and length determine the part of the buffer to be written. - -

-

position refers to the offset from the beginning of the file where this data -should be written. If position is null, the data will be written at the -current position. -See pwrite(2). - -

-

The callback will be given three arguments (err, written, buffer) where written -specifies how many bytes were written from buffer. - -

-

Note that it is unsafe to use fs.write multiple times on the same file -without waiting for the callback. For this scenario, -fs.createWriteStream is strongly recommended. - -

-

fs.writeSync(fd, buffer, offset, length, position)#

-

Synchronous version of buffer-based fs.write(). Returns the number of bytes -written. - -

-

fs.writeSync(fd, str, position, [encoding])#

-

Synchronous version of string-based fs.write(). encoding defaults to -'utf8'. Returns the number of bytes written. - -

-

fs.read(fd, buffer, offset, length, position, [callback])#

-

Read data from the file specified by fd. - -

-

buffer is the buffer that the data will be written to. - -

-

offset is offset within the buffer where writing will start. - -

-

length is an integer specifying the number of bytes to read. - -

-

position is an integer specifying where to begin reading from in the file. -If position is null, data will be read from the current file position. - -

-

The callback is given the three arguments, (err, bytesRead, buffer). - -

-

fs.readSync(fd, buffer, offset, length, position)#

-

Synchronous version of buffer-based fs.read. Returns the number of -bytesRead. - -

-

fs.readSync(fd, length, position, encoding)#

-

Synchronous version of string-based fs.read. Returns the number of -bytesRead. - -

-

fs.readFile(filename, [encoding], [callback])#

-

Asynchronously reads the entire contents of a file. Example: - -

-
fs.readFile('/etc/passwd', function (err, data) {
-  if (err) throw err;
-  console.log(data);
-});
-

The callback is passed two arguments (err, data), where data is the -contents of the file. - -

-

If no encoding is specified, then the raw buffer is returned. - - -

-

fs.readFileSync(filename, [encoding])#

-

Synchronous version of fs.readFile. Returns the contents of the filename. - -

-

If encoding is specified then this function returns a string. Otherwise it -returns a buffer. - - -

-

fs.writeFile(filename, data, [encoding], [callback])#

-

Asynchronously writes data to a file, replacing the file if it already exists. -data can be a string or a buffer. The encoding argument is ignored if -data is a buffer. It defaults to 'utf8'. - -

-

Example: - -

-
fs.writeFile('message.txt', 'Hello Node', function (err) {
-  if (err) throw err;
-  console.log('It\'s saved!');
-});
-

fs.writeFileSync(filename, data, [encoding])#

-

The synchronous version of fs.writeFile. - -

-

fs.watchFile(filename, [options], listener)#

-
Stability: 2 - Unstable.  Use fs.watch instead, if available.
-

Watch for changes on filename. The callback listener will be called each -time the file is accessed. - -

-

The second argument is optional. The options if provided should be an object -containing two members a boolean, persistent, and interval. persistent -indicates whether the process should continue to run as long as files are -being watched. interval indicates how often the target should be polled, -in milliseconds. (On Linux systems with inotify, interval is ignored.) The -default is { persistent: true, interval: 0 }. - -

-

The listener gets two arguments the current stat object and the previous -stat object: - -

-
fs.watchFile('message.text', function (curr, prev) {
-  console.log('the current mtime is: ' + curr.mtime);
-  console.log('the previous mtime was: ' + prev.mtime);
-});
-

These stat objects are instances of fs.Stat. - -

-

If you want to be notified when the file was modified, not just accessed -you need to compare curr.mtime and prev.mtime. - - -

-

fs.unwatchFile(filename)#

-
Stability: 2 - Unstable.  Use fs.watch instead, if available.
-

Stop watching for changes on filename. - -

-

fs.watch(filename, [options], listener)#

-
Stability: 2 - Unstable.  Not available on all platforms.
-

Watch for changes on filename, where filename is either a file or a -directory. The returned object is a fs.FSWatcher. - -

-

The second argument is optional. The options if provided should be an object -containing a boolean member persistent, which indicates whether the process -should continue to run as long as files are being watched. The default is -{ persistent: true }. - -

-

The listener callback gets two arguments (event, filename). event is either -'rename' or 'change', and filename is the name of the file which triggered -the event. - -

-

Caveats#

- - -

The fs.watch API is not 100% consistent across platforms, and is -unavailable in some situations. - -

-

Availability#

- - -

This feature depends on the underlying operating system providing a way -to be notified of filesystem changes. - -

-
    -
  • On Linux systems, this uses inotify.
    • -
  • On BSD systems (including OS X), this uses kqueue.
    • -
  • On SunOS systems (including Solaris and SmartOS), this uses event ports.
    • -
  • On Windows systems, this feature depends on ReadDirectoryChangesW.
    • -
-

If the underlying functionality is not available for some reason, then -fs.watch will not be able to function. You can still use -fs.watchFile, which uses stat polling, but it is slower and less -reliable. - -

-

Filename Argument#

- - -

Providing filename argument in the callback is not supported -on every platform (currently it's only supported on Linux and Windows). Even -on supported platforms filename is not always guaranteed to be provided. -Therefore, don't assume that filename argument is always provided in the -callback, and have some fallback logic if it is null. - -

-
fs.watch('somedir', function (event, filename) {
-  console.log('event is: ' + event);
-  if (filename) {
-    console.log('filename provided: ' + filename);
-  } else {
-    console.log('filename not provided');
-  }
-});
-

Class: fs.Stats#

-

Objects returned from fs.stat(), fs.lstat() and fs.fstat() and their -synchronous counterparts are of this type. - -

-
    -
  • stats.isFile()
    • -
  • stats.isDirectory()
    • -
  • stats.isBlockDevice()
    • -
  • stats.isCharacterDevice()
    • -
  • stats.isSymbolicLink() (only valid with fs.lstat())
    • -
  • stats.isFIFO()
    • -
  • stats.isSocket()
    • -
-

For a regular file util.inspect(stats) would return a string very -similar to this: - -

-
{ dev: 2114,
-  ino: 48064969,
-  mode: 33188,
-  nlink: 1,
-  uid: 85,
-  gid: 100,
-  rdev: 0,
-  size: 527,
-  blksize: 4096,
-  blocks: 8,
-  atime: Mon, 10 Oct 2011 23:24:11 GMT,
-  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
-  ctime: Mon, 10 Oct 2011 23:24:11 GMT }
-

Please note that atime, mtime and ctime are instances -of Date object and to compare the values of -these objects you should use appropriate methods. For most -general uses getTime() will return -the number of milliseconds elapsed since 1 January 1970 -00:00:00 UTC and this integer should be sufficient for -any comparison, however there additional methods which can -be used for displaying fuzzy information. More details can -be found in the MDN JavaScript Reference page. - -

-

fs.createReadStream(path, [options])#

-

Returns a new ReadStream object (See Readable Stream). - -

-

options is an object with the following defaults: - -

-
{ flags: 'r',
-  encoding: null,
-  fd: null,
-  mode: 0666,
-  bufferSize: 64 * 1024
-}
-

options can include start and end values to read a range of bytes from -the file instead of the entire file. Both start and end are inclusive and -start at 0. - -

-

An example to read the last 10 bytes of a file which is 100 bytes long: - -

-
fs.createReadStream('sample.txt', {start: 90, end: 99});
-

Class: fs.ReadStream#

-

ReadStream is a Readable Stream. - -

-

Event: 'open'#

-
    -
  • fd Integer file descriptor used by the ReadStream.
    • -
-

Emitted when the ReadStream's file is opened. - - -

-

fs.createWriteStream(path, [options])#

-

Returns a new WriteStream object (See Writable Stream). - -

-

options is an object with the following defaults: - -

-
{ flags: 'w',
-  encoding: null,
-  mode: 0666 }
-

options may also include a start option to allow writing data at -some position past the beginning of the file. Modifying a file rather -than replacing it may require a flags mode of r+ rather than the -default mode w. - -

-

fs.WriteStream#

-

WriteStream is a Writable Stream. - -

-

Event: 'open'#

-
    -
  • fd Integer file descriptor used by the ReadStream.
    • -
-

Emitted when the WriteStream's file is opened. - -

-

file.bytesWritten#

-

The number of bytes written so far. Does not include data that is still queued -for writing. - -

-

Class: fs.FSWatcher#

-

Objects returned from fs.watch() are of this type. - -

-

watcher.close()#

-

Stop watching for changes on the given fs.FSWatcher. - -

-

Event: 'change'#

-
    -
  • event String The type of fs change
    • -
  • filename String The filename that changed (if relevant/available)
    • -
-

Emitted when something changes in a watched directory or file. -See more details in fs.watch. - -

-

Event: 'error'#

-
    -
  • error Error object
    • -
-

Emitted when an error occurs. - -

-

Path#

-
Stability: 3 - Stable
-

This module contains utilities for handling and transforming file -paths. Almost all these methods perform only string transformations. -The file system is not consulted to check whether paths are valid. - -

-

path.exists and path.existsSync are the exceptions, and should -logically be found in the fs module as they do access the file system. - -

-

Use require('path') to use this module. The following methods are provided: - -

-

path.normalize(p)#

-

Normalize a string path, taking care of '..' and '.' parts. - -

-

When multiple slashes are found, they're replaced by a single one; -when the path contains a trailing slash, it is preserved. -On windows backslashes are used. - -

-

Example: - -

-
path.normalize('/foo/bar//baz/asdf/quux/..')
-// returns
-'/foo/bar/baz/asdf'
-

path.join([path1], [path2], [...])#

-

Join all arguments together and normalize the resulting path. -Non-string arguments are ignored. - -

-

Example: - -

-
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
-// returns
-'/foo/bar/baz/asdf'
-
-path.join('foo', {}, 'bar')
-// returns
-'foo/bar'
-

path.resolve([from ...], to)#

-

Resolves to to an absolute path. - -

-

If to isn't already absolute from arguments are prepended in right to left -order, until an absolute path is found. If after using all from paths still -no absolute path is found, the current working directory is used as well. The -resulting path is normalized, and trailing slashes are removed unless the path -gets resolved to the root directory. Non-string arguments are ignored. - -

-

Another way to think of it is as a sequence of cd commands in a shell. - -

-
path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
-

Is similar to: - -

-
cd foo/bar
-cd /tmp/file/
-cd ..
-cd a/../subfile
-pwd
-

The difference is that the different paths don't need to exist and may also be -files. - -

-

Examples: - -

-
path.resolve('/foo/bar', './baz')
-// returns
-'/foo/bar/baz'
-
-path.resolve('/foo/bar', '/tmp/file/')
-// returns
-'/tmp/file'
-
-path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
-// if currently in /home/myself/node, it returns
-'/home/myself/node/wwwroot/static_files/gif/image.gif'
-

path.relative(from, to)#

-

Solve the relative path from from to to. - -

-

At times we have two absolute paths, and we need to derive the relative -path from one to the other. This is actually the reverse transform of -path.resolve, which means we see that: - -

-
path.resolve(from, path.relative(from, to)) == path.resolve(to)
-

Examples: - -

-
path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb')
-// returns
-'..\\..\\impl\\bbb'
-
-path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
-// returns
-'../../impl/bbb'
-

path.dirname(p)#

-

Return the directory name of a path. Similar to the Unix dirname command. - -

-

Example: - -

-
path.dirname('/foo/bar/baz/asdf/quux')
-// returns
-'/foo/bar/baz/asdf'
-

path.basename(p, [ext])#

-

Return the last portion of a path. Similar to the Unix basename command. - -

-

Example: - -

-
path.basename('/foo/bar/baz/asdf/quux.html')
-// returns
-'quux.html'
-
-path.basename('/foo/bar/baz/asdf/quux.html', '.html')
-// returns
-'quux'
-

path.extname(p)#

-

Return the extension of the path, from the last '.' to end of string -in the last portion of the path. If there is no '.' in the last portion -of the path or the first character of it is '.', then it returns -an empty string. Examples: - -

-
path.extname('index.html')
-// returns
-'.html'
-
-path.extname('index.')
-// returns
-'.'
-
-path.extname('index')
-// returns
-''
-

path.exists(p, [callback])#

-

Test whether or not the given path exists by checking with the file system. -Then call the callback argument with either true or false. Example: - -

-
path.exists('/etc/passwd', function (exists) {
-  util.debug(exists ? "it's there" : "no passwd!");
-});
-

path.existsSync(p)#

-

Synchronous version of path.exists. - -

-

net#

-
Stability: 3 - Stable
-

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'); - -

-

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

-

Creates a new TCP server. The connectionListener argument is -automatically set as a listener for the 'connection' -event. - -

-

options is an object with the following defaults: - -

-
{ allowHalfOpen: false
-}
-

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. - -

-

Here is an example of a echo server which listens for connections -on port 8124: - -

-
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');
-});
-

Test this by using telnet: - -

-
telnet localhost 8124
-

To listen on the socket /tmp/echo.sock the third line from the last would -just be changed to - -

-
server.listen('/tmp/echo.sock', function() { //'listening' listener
-

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

-
nc -U /tmp/echo.sock
-

net.connect(arguments...)#

-

net.createConnection(arguments...)#

-

Construct a new socket object and opens a socket to the given location. When -the socket is established the 'connect' event will be -emitted. - -

-

The arguments for these methods change the type of connection: - -

-
    -
  • net.connect(port, [host], [connectListener])
    • -

  • net.createConnection(port, [host], [connectListener])

    -

    Creates a TCP connection to port on host. If host is omitted, -'localhost' will be assumed.

    -
    • -

  • net.connect(path, [connectListener])

    -
    • -

  • net.createConnection(path, [connectListener])

    -

    Creates unix socket connection to path.

    -
    • -
-

The connectListener parameter will be added as an listener for the -'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 connect on the socket /tmp/echo.sock the second line would just be -changed to - -

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

Class: net.Server#

-

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. When the server has been bound, -'listening' event will be emitted. -the last parameter listeningListener will be added as an listener for the -'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 -would be to wait a second and then try again. This can be done with - -

-
server.on('error', function (e) {
-  if (e.code == 'EADDRINUSE') {
-    console.log('Address in use, retrying...');
-    setTimeout(function () {
-      server.close();
-      server.listen(PORT, HOST);
-    }, 1000);
-  }
-});
-

(Note: All sockets in Node set SO_REUSEADDR already) - - -

-

server.listen(path, [listeningListener])#

-

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

-

This function is asynchronous. When the server has been bound, -'listening' event will be emitted. -the last parameter listeningListener will be added as an listener for the -'listening' event. - -

-

server.close()#

-

Stops the server from accepting new connections. This function is -asynchronous, the server is finally closed when the server emits a 'close' -event. - - -

-

server.address()#

-

Returns the bound address and port of the server as reported by the operating system. -Useful to find which port was assigned when giving getting an OS-assigned address. -Returns an object with two properties, e.g. {"address":"127.0.0.1", "port":2121} - -

-

Example: - -

-
var server = net.createServer(function (socket) {
-  socket.end("goodbye\n");
-});
-
-// grab a random port.
-server.listen(function() {
-  address = server.address();
-  console.log("opened server on %j", address);
-});
-

Don't call server.address() until the 'listening' event has been emitted. - -

-

server.maxConnections#

-

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

-

server.connections#

-

The number of concurrent connections on the server. - - -

-

net.Server is an EventEmitter with the following events: - -

-

Event: 'listening'#

-

Emitted when the server has been bound after calling server.listen. - -

-

Event: 'connection'#

-
    -
  • Socket object The connection object
    • -
-

Emitted when a new connection is made. socket is an instance of -net.Socket. - -

-

Event: 'close'#

-

Emitted when the server closes. - -

-

Event: 'error'#

-
    -
  • Error Object
    • -
-

Emitted when an error occurs. The 'close' event will be called directly -following this event. See example in discussion of server.listen. - -

-

Class: net.Socket#

-

This object is an abstraction of a TCP or UNIX socket. net.Socket -instances implement a duplex Stream interface. They can be created by the -user and used as a client (with connect()) or they can be created by Node -and passed to the user through the 'connection' event of a server. - -

-

new net.Socket([options])#

-

Construct a new socket object. - -

-

options is an object with the following defaults: - -

-
{ fd: null
-  type: null
-  allowHalfOpen: false
-}
-

fd allows you to specify the existing file descriptor of socket. type -specified underlying protocol. It can be 'tcp4', 'tcp6', or 'unix'. -About allowHalfOpen, refer to createServer() and 'end' event. - -

-

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, -localhost will be assumed. If a path is given, the socket will be -opened as a unix socket to that path. - -

-

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 -the exception. - -

-

The connectListener parameter will be added as an listener for the -'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). - -

-

The consequence of this internal buffering is that memory may grow. This -property shows the number of characters currently buffered to be written. -(Number of characters is approximately equal to the number of bytes to be -written, but the buffer may contain strings, and the strings are lazily -encoded, so the exact number of bytes is not known.) - -

-

Users who experience large or growing bufferSize should attempt to -"throttle" the data flows in their program with pause() and resume(). - - -

-

socket.setEncoding([encoding])#

-

Sets the encoding (either 'ascii', 'utf8', or 'base64') for data that is -received. Defaults to null. - -

-

socket.setSecure()#

-

This function has been removed in v0.3. It used to upgrade the connection to -SSL/TLS. See the TLS section for the new API. - - -

-

socket.write(data, [encoding], [callback])#

-

Sends data on the socket. The second parameter specifies the encoding in the -case of a string--it defaults to UTF8 encoding. - -

-

Returns true if the entire data was flushed successfully to the kernel -buffer. Returns false if all or part of the data was queued in user memory. -'drain' will be emitted when the buffer is again free. - -

-

The optional callback parameter will be executed when the data is finally -written out - this may not be immediately. - -

-

socket.end([data], [encoding])#

-

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(). - -

-

socket.destroy()#

-

Ensures that no more I/O activity happens on this socket. Only necessary in -case of errors (parse error or so). - -

-

socket.pause()#

-

Pauses the reading of data. That is, 'data' events will not be emitted. -Useful to throttle back an upload. - -

-

socket.resume()#

-

Resumes reading after a call to pause(). - -

-

socket.setTimeout(timeout, [callback])#

-

Sets the socket to timeout after timeout milliseconds of inactivity on -the socket. By default net.Socket do not have a timeout. - -

-

When an idle timeout is triggered the socket will receive a 'timeout' -event but the connection will not be severed. The user must manually end() -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. - -

-

socket.setNoDelay([noDelay])#

-

Disables the Nagle algorithm. By default TCP connections use the Nagle -algorithm, they buffer data before sending it off. Setting true for -noDelay will immediately fire off data each time socket.write() is called. -noDelay defaults to true. - -

-

socket.setKeepAlive([enable], [initialDelay])#

-

Enable/disable keep-alive functionality, and optionally set the initial -delay before the first keepalive probe is sent on an idle socket. -enable defaults to false. - -

-

Set initialDelay (in milliseconds) to set the delay between the last -data packet received and the first keepalive probe. Setting 0 for -initialDelay will leave the value unchanged from the default -(or previous) setting. Defaults to 0. - -

-

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} - -

-

socket.remoteAddress#

-

The string representation of the remote IP address. For example, -'74.125.127.100' or '2001:4860:a005::68'. - -

-

socket.remotePort#

-

The numeric representation of the remote port. For example, -80 or 21. - -

-

socket.bytesRead#

-

The amount of received bytes. - -

-

socket.bytesWritten#

-

The amount of bytes sent. - - -

-

net.Socket instances are EventEmitters with the following events: - -

-

Event: 'connect'#

-

Emitted when a socket connection is successfully established. -See connect(). - -

-

Event: 'data'#

-
    -
  • Buffer object
    • -
-

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 section for more -information.) - -

-

Note that the data will be lost if there is no listener when a Socket -emits a 'data' event. - -

-

Event: 'end'#

-

Emitted when the other end of the socket sends a FIN packet. - -

-

By default (allowHalfOpen == false) the socket will destroy its file -descriptor once it has written out its pending write queue. However, by -setting allowHalfOpen == true the socket will not automatically end() -its side allowing the user to write arbitrary amounts of data, with the -caveat that the user is required to end() their side now. - - -

-

Event: 'timeout'#

-

Emitted if the socket times out from inactivity. This is only to notify that -the socket has been idle. The user must manually close the connection. - -

-

See also: socket.setTimeout() - - -

-

Event: 'drain'#

-

Emitted when the write buffer becomes empty. Can be used to throttle uploads. - -

-

See also: the return values of socket.write() - -

-

Event: 'error'#

-
    -
  • Error object
    • -
-

Emitted when an error occurs. The 'close' event will be called directly -following this event. - -

-

Event: 'close'#

-
    -
  • had_error Boolean true if the socket had a transmission error
    • -
-

Emitted once the socket is fully closed. The argument had_error is a boolean -which says if the socket was closed due to a transmission error. - -

-

net.isIP(input)#

-

Tests if input is an IP address. Returns 0 for invalid strings, -returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses. - - -

-

net.isIPv4(input)#

-

Returns true if input is a version 4 IP address, otherwise returns false. - - -

-

net.isIPv6(input)#

-

Returns true if input is a version 6 IP address, otherwise returns false. - - -

-

UDP / Datagram Sockets#

-
Stability: 3 - Stable
- - -

Datagram sockets are available through require('dgram'). - -

-

dgram.createSocket(type, [callback])#

-
    -
  • type String. Either 'udp4' or 'udp6'
    • -
  • callback Function. Attached as a listener to message events. -Optional
    • -
  • Returns: Socket object
    • -
-

Creates a datagram Socket of the specified types. Valid types are udp4 -and udp6. - -

-

Takes an optional callback which is added as a listener for message events. - -

-

Call socket.bind if you want to receive datagrams. socket.bind() will bind -to the "all interfaces" address on a random port (it does the right thing for -both udp4 and udp6 sockets). You can then retrieve the address and port -with socket.address().address and socket.address().port. - -

-

Class: Socket#

-

The dgram Socket class encapsulates the datagram functionality. It -should be created via dgram.createSocket(type, [callback]). - -

-

Event: 'message'#

-
    -
  • msg Buffer object. The message
    • -
  • rinfo Object. Remote address information
    • -
-

Emitted when a new datagram is available on a socket. msg is a Buffer and rinfo is -an object with the sender's address information and the number of bytes in the datagram. - -

-

Event: 'listening'#

-

Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets -are created. - -

-

Event: 'close'#

-

Emitted when a socket is closed with close(). No new message events will be emitted -on this socket. - -

-

Event: 'error'#

-
    -
  • exception Error object
    • -
-

Emitted when an error occurs. - -

-

dgram.send(buf, offset, length, port, address, [callback])#

-
    -
  • buf Buffer object. Message to be sent
    • -
  • offset Integer. Offset in the buffer where the message starts.
    • -
  • length Integer. Number of bytes in the message.
    • -
  • port Integer. destination port
    • -
  • address String. destination IP
    • -
  • callback Function. Callback when message is done being delivered. -Optional.
    • -
-

For UDP sockets, the destination port and IP address must be specified. A string -may be supplied for the address parameter, and it will be resolved with DNS. An -optional callback may be specified to detect any DNS errors and when buf may be -re-used. Note that DNS lookups will delay the time that a send takes place, at -least until the next tick. The only way to know for sure that a send has taken place -is to use the callback. - -

-

If the socket has not been previously bound with a call to bind, it's -assigned a random port number and bound to the "all interfaces" address -(0.0.0.0 for udp4 sockets, ::0 for udp6 sockets). - -

-

Example of sending a UDP packet to a random port on localhost; - -

-
var dgram = require('dgram');
-var message = new Buffer("Some bytes");
-var client = dgram.createSocket("udp4");
-client.send(message, 0, message.length, 41234, "localhost", function(err, bytes) {
-  client.close();
-});
-

A Note about UDP datagram size - -

-

The maximum size of an IPv4/v6 datagram depends on the MTU (Maximum Transmission Unit) -and on the Payload Length field size. - -

-
    -

  • The Payload Length field is 16 bits wide, which means that a normal payload -cannot be larger than 64K octets including internet header and data -(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header); -this is generally true for loopback interfaces, but such long datagrams -are impractical for most hosts and networks.

    -
    • -

  • The MTU is the largest size a given link layer technology can support for datagrams. -For any link, IPv4 mandates a minimum MTU of 68 octets, while the recommended MTU -for IPv4 is 576 (typically recommended as the MTU for dial-up type applications), -whether they arrive whole or in fragments.

    -

    For IPv6, the minimum MTU is 1280 octets, however, the mandatory minimum -fragment reassembly buffer size is 1500 octets. -The value of 68 octets is very small, since most current link layer technologies have -a minimum MTU of 1500 (like Ethernet).

    -
    • -
-

Note that it's impossible to know in advance the MTU of each link through which -a packet might travel, and that generally sending a datagram greater than -the (receiver) MTU won't work (the packet gets silently dropped, without -informing the source that the data did not reach its intended recipient). - -

-

dgram.bind(port, [address])#

-
    -
  • port Integer
    • -
  • address String, Optional
    • -
-

For UDP sockets, listen for datagrams on a named port and optional address. If -address is not specified, the OS will try to listen on all addresses. - -

-

Example of a UDP server listening on port 41234: - -

-
var dgram = require("dgram");
-
-var server = dgram.createSocket("udp4");
-
-server.on("message", function (msg, rinfo) {
-  console.log("server got: " + msg + " from " +
-    rinfo.address + ":" + rinfo.port);
-});
-
-server.on("listening", function () {
-  var address = server.address();
-  console.log("server listening " +
-      address.address + ":" + address.port);
-});
-
-server.bind(41234);
-// server listening 0.0.0.0:41234
-

dgram.close()#

-

Close the underlying socket and stop listening for data on it. - -

-

dgram.address()#

-

Returns an object containing the address information for a socket. For UDP sockets, -this object will contain address and port. - -

-

dgram.setBroadcast(flag)#

-
    -
  • flag Boolean
    • -
-

Sets or clears the SO_BROADCAST socket option. When this option is set, UDP packets -may be sent to a local interface's broadcast address. - -

-

dgram.setTTL(ttl)#

-
    -
  • ttl Integer
    • -
-

Sets the IP_TTL socket option. TTL stands for "Time to Live," but in this context it -specifies the number of IP hops that a packet is allowed to go through. Each router or -gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a -router, it will not be forwarded. Changing TTL values is typically done for network -probes or when multicasting. - -

-

The argument to setTTL() is a number of hops between 1 and 255. The default on most -systems is 64. - -

-

dgram.setMulticastTTL(ttl)#

-
    -
  • ttl Integer
    • -
-

Sets the IP_MULTICAST_TTL socket option. TTL stands for "Time to Live," but in this -context it specifies the number of IP hops that a packet is allowed to go through, -specifically for multicast traffic. Each router or gateway that forwards a packet -decrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. - -

-

The argument to setMulticastTTL() is a number of hops between 0 and 255. The default on most -systems is 64. - -

-

dgram.setMulticastLoopback(flag)#

-
    -
  • flag Boolean
    • -
-

Sets or clears the IP_MULTICAST_LOOP socket option. When this option is set, multicast -packets will also be received on the local interface. - -

-

dgram.addMembership(multicastAddress, [multicastInterface])#

-
    -
  • multicastAddress String
    • -
  • multicastInterface String, Optional
    • -
-

Tells the kernel to join a multicast group with IP_ADD_MEMBERSHIP socket option. - -

-

If multicastInterface is not specified, the OS will try to add membership to all valid -interfaces. - -

-

dgram.dropMembership(multicastAddress, [multicastInterface])#

-
    -
  • multicastAddress String
    • -
  • multicastInterface String, Optional
    • -
-

Opposite of addMembership - tells the kernel to leave a multicast group with -IP_DROP_MEMBERSHIP socket option. This is automatically called by the kernel -when the socket is closed or process terminates, so most apps will never need to call -this. - -

-

If multicastInterface is not specified, the OS will try to drop membership to all valid -interfaces. - -

-

DNS#

-
Stability: 3 - Stable
-

Use require('dns') to access this module. All methods in the dns module -use C-Ares except for dns.lookup which uses getaddrinfo(3) in a thread -pool. C-Ares is much faster than getaddrinfo but the system resolver is -more constant with how other programs operate. When a user does -net.connect(80, 'google.com') or http.get({ host: 'google.com' }) the -dns.lookup method is used. Users who need to do a large number of look ups -quickly should use the methods that go through C-Ares. - -

-

Here is an example which resolves 'www.google.com' then reverse -resolves the IP addresses which are returned. - -

-
var dns = require('dns');
-
-dns.resolve4('www.google.com', function (err, addresses) {
-  if (err) throw err;
-
-  console.log('addresses: ' + JSON.stringify(addresses));
-
-  addresses.forEach(function (a) {
-    dns.reverse(a, function (err, domains) {
-      if (err) {
-        console.log('reverse for ' + a + ' failed: ' +
-          err.message);
-      } else {
-        console.log('reverse for ' + a + ': ' +
-          JSON.stringify(domains));
-      }
-    });
-  });
-});
-

dns.lookup(domain, [family], callback)#

-

Resolves a domain (e.g. 'google.com') into the first found A (IPv4) or -AAAA (IPv6) record. -The family can be the integer 4 or 6. Defaults to null that indicates -both Ip v4 and v6 address family. - -

-

The callback has arguments (err, address, family). The address argument -is a string representation of a IP v4 or v6 address. The family argument -is either the integer 4 or 6 and denotes the family of address (not -necessarily the value initially passed to lookup). - - -

-

dns.resolve(domain, [rrtype], callback)#

-

Resolves a domain (e.g. 'google.com') into an array of the record types -specified by rrtype. Valid rrtypes are 'A' (IPV4 addresses, default), -'AAAA' (IPV6 addresses), 'MX' (mail exchange records), 'TXT' (text -records), 'SRV' (SRV records), 'PTR' (used for reverse IP lookups), -'NS' (name server records) and 'CNAME' (canonical name records). - -

-

The callback has arguments (err, addresses). The type of each item -in addresses is determined by the record type, and described in the -documentation for the corresponding lookup methods below. - -

-

On error, err would be an instanceof Error object, where err.errno is -one of the error codes listed below and err.message is a string describing -the error in English. - - -

-

dns.resolve4(domain, callback)#

-

The same as dns.resolve(), but only for IPv4 queries (A records). -addresses is an array of IPv4 addresses (e.g. -['74.125.79.104', '74.125.79.105', '74.125.79.106']). - -

-

dns.resolve6(domain, callback)#

-

The same as dns.resolve4() except for IPv6 queries (an AAAA query). - - -

-

dns.resolveMx(domain, callback)#

-

The same as dns.resolve(), but only for mail exchange queries (MX records). - -

-

addresses is an array of MX records, each with a priority and an exchange -attribute (e.g. [{'priority': 10, 'exchange': 'mx.example.com'},...]). - -

-

dns.resolveTxt(domain, callback)#

-

The same as dns.resolve(), but only for text queries (TXT records). -addresses is an array of the text records available for domain (e.g., -['v=spf1 ip4:0.0.0.0 ~all']). - -

-

dns.resolveSrv(domain, callback)#

-

The same as dns.resolve(), but only for service records (SRV records). -addresses is an array of the SRV records available for domain. Properties -of SRV records are priority, weight, port, and name (e.g., -[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]). - -

-

dns.reverse(ip, callback)#

-

Reverse resolves an ip address to an array of domain names. - -

-

The callback has arguments (err, domains). - -

-

dns.resolveNs(domain, callback)#

-

The same as dns.resolve(), but only for name server records (NS records). -addresses is an array of the name server records available for domain -(e.g., ['ns1.example.com', 'ns2.example.com']). - -

-

dns.resolveCname(domain, callback)#

-

The same as dns.resolve(), but only for canonical name records (CNAME -records). addresses is an array of the canonical name records available for -domain (e.g., ['bar.example.com']). - -

-

If there an an error, err will be non-null and an instanceof the Error -object. - -

-

Each DNS query can return an error code. - -

-
    -
  • dns.TEMPFAIL: timeout, SERVFAIL or similar.
    • -
  • dns.PROTOCOL: got garbled reply.
    • -
  • dns.NXDOMAIN: domain does not exists.
    • -
  • dns.NODATA: domain exists but no data of reqd type.
    • -
  • dns.NOMEM: out of memory while processing.
    • -
  • dns.BADQUERY: the query is malformed.
    • -
-

HTTP#

-
Stability: 3 - Stable
-

To use the HTTP server and client one must require('http'). - -

-

The HTTP interfaces in Node are designed to support many features -of the protocol which have been traditionally difficult to use. -In particular, large, possibly chunk-encoded, messages. The interface is -careful to never buffer entire requests or responses--the -user is able to stream data. - -

-

HTTP message headers are represented by an object like this: - -

-
{ 'content-length': '123',
-  'content-type': 'text/plain',
-  'connection': 'keep-alive',
-  'accept': '*/*' }
-

Keys are lowercased. Values are not modified. - -

-

In order to support the full spectrum of possible HTTP applications, Node's -HTTP API is very low-level. It deals with stream handling and message -parsing only. It parses a message into headers and body but it does not -parse the actual headers or the body. - - -

-

http.createServer([requestListener])#

-

Returns a new web server object. - -

-

The requestListener is a function which is automatically -added to the 'request' event. - -

-

Class: http.Server#

-

This is an EventEmitter with the following events: - -

-

Event: 'request'#

-

function (request, response) { } - -

-

Emitted each time there is a request. Note that there may be multiple requests -per connection (in the case of keep-alive connections). - request is an instance of http.ServerRequest and response is - an instance of http.ServerResponse - -

-

Event: 'connection'#

-

function (socket) { } - -

-

When a new TCP stream is established. socket is an object of type - net.Socket. Usually users will not want to access this event. The - socket can also be accessed at request.connection. - -

-

Event: 'close'#

-

function () { } - -

-

Emitted when the server closes. - -

-

Event: 'checkContinue'#

-

function (request, response) { } - -

-

Emitted each time a request with an http Expect: 100-continue is received. -If this event isn't listened for, the server will automatically respond -with a 100 Continue as appropriate. - -

-

Handling this event involves calling response.writeContinue if the client -should continue to send the request body, or generating an appropriate HTTP -response (e.g., 400 Bad Request) if the client should not continue to send the -request body. - -

-

Note that when this event is emitted and handled, the request event will -not be emitted. - -

-

Event: 'upgrade'#

-

function (request, socket, head) { } - -

-

Emitted each time a client requests a http upgrade. If this event isn't -listened for, then clients requesting an upgrade will have their connections -closed. - -

-
    -
  • request is the arguments for the http request, as it is in the request event.
    • -
  • socket is the network socket between the server and client.
    • -
  • head is an instance of Buffer, the first packet of the upgraded stream, this may be empty.
    • -
-

After this event is emitted, the request's socket will not have a data -event listener, meaning you will need to bind to it in order to handle data -sent to the server on that socket. - -

-

Event: 'clientError'#

-

function (exception) { } - -

-

If a client connection emits an 'error' event - it will forwarded here. - -

-

server.listen(port, [hostname], [callback])#

-

Begin accepting connections on the specified port and hostname. If the -hostname is omitted, the server will accept connections directed to any -IPv4 address (INADDR_ANY). - -

-

To listen to a unix socket, supply a filename instead of port and hostname. - -

-

This function is asynchronous. The last parameter callback will be added as -a listener for the 'listening' event. -See also net.Server.listen(). - - -

-

server.listen(path, [callback])#

-

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

-

This function is asynchronous. The last parameter callback will be added as -a listener for the 'listening' event. -See also net.Server.listen(). - - -

-

server.close()#

-

Stops the server from accepting new connections. -See net.Server.close(). - - -

-

Class: http.ServerRequest#

-

This object is created internally by a HTTP server -- not by -the user -- and passed as the first argument to a 'request' listener. - -

-

The request implements the Readable Stream -interface. This is an EventEmitter with the following events: - -

-

Event: 'data'#

-

function (chunk) { } - -

-

Emitted when a piece of the message body is received. The chunk is a string if -an encoding has been set with request.setEncoding(), otherwise it's a -Buffer. - -

-

Note that the data will be lost if there is no listener when a -ServerRequest emits a 'data' event. - -

-

Event: 'end'#

-

function () { } - -

-

Emitted exactly once for each request. After that, no more 'data' events -will be emitted on the request. - -

-

Event: 'close'#

-

function () { } - -

-

Indicates that the underlaying connection was terminated before -response.end() was called or able to flush. - -

-

Just like 'end', this event occurs only once per request, and no more 'data' -events will fire afterwards. - -

-

Note: 'close' can fire after 'end', but not vice versa. - -

-

request.method#

-

The request method as a string. Read only. Example: -'GET', 'DELETE'. - - -

-

request.url#

-

Request URL string. This contains only the URL that is -present in the actual HTTP request. If the request is: - -

-
GET /status?name=ryan HTTP/1.1\r\n
-Accept: text/plain\r\n
-\r\n
-

Then request.url will be: - -

-
'/status?name=ryan'
-

If you would like to parse the URL into its parts, you can use -require('url').parse(request.url). Example: - -

-
node> require('url').parse('/status?name=ryan')
-{ href: '/status?name=ryan',
-  search: '?name=ryan',
-  query: 'name=ryan',
-  pathname: '/status' }
-

If you would like to extract the params from the query string, -you can use the require('querystring').parse function, or pass -true as the second argument to require('url').parse. Example: - -

-
node> require('url').parse('/status?name=ryan', true)
-{ href: '/status?name=ryan',
-  search: '?name=ryan',
-  query: { name: 'ryan' },
-  pathname: '/status' }
-

request.headers#

-

Read only. - -

-

request.trailers#

-

Read only; HTTP trailers (if present). Only populated after the 'end' event. - -

-

request.httpVersion#

-

The HTTP protocol version as a string. Read only. Examples: -'1.1', '1.0'. -Also request.httpVersionMajor is the first integer and -request.httpVersionMinor is the second. - - -

-

request.setEncoding([encoding])#

-

Set the encoding for the request body. Either 'utf8' or 'binary'. Defaults -to null, which means that the 'data' event will emit a Buffer object.. - - -

-

request.pause()#

-

Pauses request from emitting events. Useful to throttle back an upload. - - -

-

request.resume()#

-

Resumes a paused request. - -

-

request.connection#

-

The net.Socket object associated with the connection. - - -

-

With HTTPS support, use request.connection.verifyPeer() and -request.connection.getPeerCertificate() to obtain the client's -authentication details. - - - -

-

Class: http.ServerResponse#

-

This object is created internally by a HTTP server--not by the user. It is -passed as the second parameter to the 'request' event. - -

-

The response implements the Writable Stream -interface. This is an EventEmitter with the following events: - -

-

Event: 'close'#

-

function () { } - -

-

Indicates that the underlaying connection was terminated before -response.end() was called or able to flush. - -

-

response.writeContinue()#

-

Sends a HTTP/1.1 100 Continue message to the client, indicating that -the request body should be sent. See the checkContinue event on -Server. - -

-

response.writeHead(statusCode, [reasonPhrase], [headers])#

-

Sends a response header to the request. The status code is a 3-digit HTTP -status code, like 404. The last argument, headers, are the response headers. -Optionally one can give a human-readable reasonPhrase as the second -argument. - -

-

Example: - -

-
var body = 'hello world';
-response.writeHead(200, {
-  'Content-Length': body.length,
-  'Content-Type': 'text/plain' });
-

This method must only be called once on a message and it must -be called before response.end() is called. - -

-

If you call response.write() or response.end() before calling this, the -implicit/mutable headers will be calculated and call this function for you. - -

-

Note: that Content-Length is given in bytes not characters. The above example -works because the string 'hello world' contains only single byte characters. -If the body contains higher coded characters then Buffer.byteLength() -should be used to determine the number of bytes in a given encoding. -And Node does not check whether Content-Length and the length of the body -which has been transmitted are equal or not. - -

-

response.statusCode#

-

When using implicit headers (not calling response.writeHead() explicitly), this property -controls the status code that will be send to the client when the headers get -flushed. - -

-

Example: - -

-
response.statusCode = 404;
-

After response header was sent to the client, this property indicates the -status code which was sent out. - -

-

response.setHeader(name, value)#

-

Sets a single header value for implicit headers. If this header already exists -in the to-be-sent headers, its value will be replaced. Use an array of strings -here if you need to send multiple headers with the same name. - -

-

Example: - -

-
response.setHeader("Content-Type", "text/html");
-

or - -

-
response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]);
-

response.getHeader(name)#

-

Reads out a header that's already been queued but not sent to the client. Note -that the name is case insensitive. This can only be called before headers get -implicitly flushed. - -

-

Example: - -

-
var contentType = response.getHeader('content-type');
-

response.removeHeader(name)#

-

Removes a header that's queued for implicit sending. - -

-

Example: - -

-
response.removeHeader("Content-Encoding");
-

response.write(chunk, [encoding])#

-

If this method is called and response.writeHead() has not been called, it will -switch to implicit header mode and flush the implicit headers. - -

-

This sends a chunk of the response body. This method may -be called multiple times to provide successive parts of the body. - -

-

chunk can be a string or a buffer. If chunk is a string, -the second parameter specifies how to encode it into a byte stream. -By default the encoding is 'utf8'. - -

-

Note: This is the raw HTTP body and has nothing to do with -higher-level multi-part body encodings that may be used. - -

-

The first time response.write() is called, it will send the buffered -header information and the first body to the client. The second time -response.write() is called, Node assumes you're going to be streaming -data, and sends that separately. That is, the response is buffered up to the -first chunk of body. - -

-

response.addTrailers(headers)#

-

This method adds HTTP trailing headers (a header but at the end of the -message) to the response. - -

-

Trailers will only be emitted if chunked encoding is used for the -response; if it is not (e.g., if the request was HTTP/1.0), they will -be silently discarded. - -

-

Note that HTTP requires the Trailer header to be sent if you intend to -emit trailers, with a list of the header fields in its value. E.g., - -

-
response.writeHead(200, { 'Content-Type': 'text/plain',
-                          'Trailer': 'Content-MD5' });
-response.write(fileData);
-response.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});
-response.end();
-

response.end([data], [encoding])#

-

This method signals to the server that all of the response headers and body -has been sent; that server should consider this message complete. -The method, response.end(), MUST be called on each -response. - -

-

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

-

http.request(options, callback)#

-

Node maintains several connections per server to make HTTP requests. -This function allows one to transparently issue requests. options align -with url.parse(). - -

-

Options: - -

-
    -
  • host: A domain name or IP address of the server to issue the request to. -Defaults to 'localhost'.
    • -
  • hostname: To support url.parse() hostname is preferred over host
    • -
  • port: Port of remote server. Defaults to 80.
    • -
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • -
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • -
  • path: Request path. Defaults to '/'. Should include query string if any. -E.G. '/index.html?page=12'
    • -
  • headers: An object containing request headers.
    • -
  • auth: Basic authentication i.e. 'user:password' to compute an -Authorization header.
    • -
  • agent: Controls Agent behavior. When an Agent is used -request will default to Connection: keep-alive. Possible values:
      -
    • undefined (default): use global Agent for this host -and port.
      • -
    • Agent object: explicitly use the passed in Agent.
      • -
    • false: opts out of connection pooling with an Agent, defaults request to -Connection: close.
      • -
    -
    • -
-

http.request() returns an instance of the http.ClientRequest -class. The ClientRequest instance is a writable stream. If one needs to -upload a file with a POST request, then write to the ClientRequest object. - -

-

Example: - -

-
var options = {
-  host: 'www.google.com',
-  port: 80,
-  path: '/upload',
-  method: 'POST'
-};
-
-var req = http.request(options, function(res) {
-  console.log('STATUS: ' + res.statusCode);
-  console.log('HEADERS: ' + JSON.stringify(res.headers));
-  res.setEncoding('utf8');
-  res.on('data', function (chunk) {
-    console.log('BODY: ' + chunk);
-  });
-});
-
-req.on('error', function(e) {
-  console.log('problem with request: ' + e.message);
-});
-
-// write data to request body
-req.write('data\n');
-req.write('data\n');
-req.end();
-

Note that in the example req.end() was called. With http.request() one -must always call req.end() to signify that you're done with the request - -even if there is no data being written to the request body. - -

-

If any error is encountered during the request (be that with DNS resolution, -TCP level errors, or actual HTTP parse errors) an 'error' event is emitted -on the returned request object. - -

-

There are a few special headers that should be noted. - -

-
    -

  • Sending a 'Connection: keep-alive' will notify Node that the connection to -the server should be persisted until the next request.

    -
    • -

  • Sending a 'Content-length' header will disable the default chunked encoding.

    -
    • -

  • Sending an 'Expect' header will immediately send the request headers. -Usually, when sending 'Expect: 100-continue', you should both set a timeout -and listen for the continue event. See RFC2616 Section 8.2.3 for more -information.

    -
    • -

  • Sending an Authorization header will override using the auth option -to compute basic authentication.

    -
    • -
-

http.get(options, callback)#

-

Since most requests are GET requests without bodies, Node provides this -convenience method. The only difference between this method and http.request() is -that it sets the method to GET and calls req.end() automatically. - -

-

Example: - -

-
var options = {
-  host: 'www.google.com',
-  port: 80,
-  path: '/index.html'
-};
-
-http.get(options, function(res) {
-  console.log("Got response: " + res.statusCode);
-}).on('error', function(e) {
-  console.log("Got error: " + e.message);
-});
-

Class: http.Agent#

-

In node 0.5.3+ there is a new implementation of the HTTP Agent which is used -for pooling sockets used in HTTP client requests. - -

-

Previously, a single agent instance help the pool for single host+port. The -current implementation now holds sockets for any number of hosts. - -

-

The current HTTP Agent also defaults client requests to using -Connection:keep-alive. If no pending HTTP requests are waiting on a socket -to become free the socket is closed. This means that node's pool has the -benefit of keep-alive when under load but still does not require developers -to manually close the HTTP clients using keep-alive. - -

-

Sockets are removed from the agent's pool when the socket emits either a -"close" event or a special "agentRemove" event. This means that if you intend -to keep one HTTP request open for a long time and don't want it to stay in the -pool you can do something along the lines of: - -

-
http.get(options, function(res) {
-  // Do stuff
-}).on("socket", function (socket) {
-  socket.emit("agentRemove");
-});
-

Alternatively, you could just opt out of pooling entirely using agent:false: - -

-
http.get({host:'localhost', port:80, path:'/', agent:false}, function (res) {
-  // Do stuff
-})
-

agent.maxSockets#

-

By default set to 5. Determines how many concurrent sockets the agent can have -open per host. - -

-

agent.sockets#

-

An object which contains arrays of sockets currently in use by the Agent. Do not -modify. - -

-

agent.requests#

-

An object which contains queues of requests that have not yet been assigned to -sockets. Do not modify. - -

-

http.globalAgent#

-

Global instance of Agent which is used as the default for all http client -requests. - - -

-

Class: http.ClientRequest#

-

This object is created internally and returned from http.request(). It -represents an in-progress request whose header has already been queued. The -header is still mutable using the setHeader(name, value), getHeader(name), -removeHeader(name) API. The actual header will be sent along with the first -data chunk or when closing the connection. - -

-

To get the response, add a listener for 'response' to the request object. -'response' will be emitted from the request object when the response -headers have been received. The 'response' event is executed with one -argument which is an instance of http.ClientResponse. - -

-

During the 'response' event, one can add listeners to the -response object; particularly to listen for the 'data' event. Note that -the 'response' event is called before any part of the response body is received, -so there is no need to worry about racing to catch the first part of the -body. As long as a listener for 'data' is added during the 'response' -event, the entire body will be caught. - - -

-
// Good
-request.on('response', function (response) {
-  response.on('data', function (chunk) {
-    console.log('BODY: ' + chunk);
-  });
-});
-
-// Bad - misses all or part of the body
-request.on('response', function (response) {
-  setTimeout(function () {
-    response.on('data', function (chunk) {
-      console.log('BODY: ' + chunk);
-    });
-  }, 10);
-});
-

Note: Node does not check whether Content-Length and the length of the body -which has been transmitted are equal or not. - -

-

The request implements the Writable Stream -interface. This is an EventEmitter with the following events: - -

-

Event 'response'#

-

function (response) { } - -

-

Emitted when a response is received to this request. This event is emitted only once. The -response argument will be an instance of http.ClientResponse. - -

-

Options: - -

-
    -
  • host: A domain name or IP address of the server to issue the request to.
    • -
  • port: Port of remote server.
    • -
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • -
-

Event: 'socket'#

-

function (socket) { } - -

-

Emitted after a socket is assigned to this request. - -

-

Event: 'upgrade'#

-

function (response, 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. - -

-

A client server pair that show you how to listen for the upgrade event using http.getAgent: - -

-
var http = require('http');
-var net = require('net');
-
-// Create an HTTP server
-var srv = http.createServer(function (req, res) {
-  res.writeHead(200, {'Content-Type': 'text/plain'});
-  res.end('okay');
-});
-srv.on('upgrade', function(req, socket, upgradeHead) {
-  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
-               'Upgrade: WebSocket\r\n' +
-               'Connection: Upgrade\r\n' +
-               '\r\n\r\n');
-
-  socket.ondata = function(data, start, end) {
-    socket.write(data.toString('utf8', start, end), 'utf8'); // echo back
-  };
-});
-
-// now that server is running
-srv.listen(1337, '127.0.0.1', function() {
-
-  // make a request
-  var options = {
-    port: 1337,
-    host: '127.0.0.1',
-    headers: {
-      'Connection': 'Upgrade',
-      'Upgrade': 'websocket'
-    }
-  };
-
-  var req = http.request(options);
-  req.end();
-
-  req.on('upgrade', function(res, socket, upgradeHead) {
-    console.log('got upgraded!');
-    socket.end();
-    process.exit(0);
-  });
-});
-

Event: 'continue'#

-

function () { } - -

-

Emitted when the server sends a '100 Continue' HTTP response, usually because -the request contained 'Expect: 100-continue'. This is an instruction that -the client should send the request body. - -

-

request.write(chunk, [encoding])#

-

Sends a chunk of the body. By calling this method -many times, the user can stream a request body to a -server--in that case it is suggested to use the -['Transfer-Encoding', 'chunked'] header line when -creating the request. - -

-

The chunk argument should be a buffer or a string. - -

-

The encoding argument is optional and only applies when chunk is a string. -Defaults to 'utf8'. - - -

-

request.end([data], [encoding])#

-

Finishes sending the request. If any parts of the body are -unsent, it will flush them to the stream. If the request is -chunked, this will send the terminating '0\r\n\r\n'. - -

-

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

-

request.abort()#

-

Aborts a request. (New since v0.3.8.) - -

-

request.setTimeout(timeout, [callback])#

-

Once a socket is assigned to this request and is connected -socket.setTimeout(timeout, [callback]) -will be called. - -

-

request.setNoDelay([noDelay])#

-

Once a socket is assigned to this request and is connected -socket.setNoDelay(noDelay) -will be called. - -

-

request.setSocketKeepAlive([enable], [initialDelay])#

-

Once a socket is assigned to this request and is connected -socket.setKeepAlive(enable, [initialDelay]) -will be called. - -

-

http.ClientResponse#

-

This object is created when making a request with http.request(). It is -passed to the 'response' event of the request object. - -

-

The response implements the Readable Stream -interface. This is an EventEmitter with the following events: - - -

-

Event: 'data'#

-

function (chunk) { } - -

-

Emitted when a piece of the message body is received. - -

-

Note that the data will be lost if there is no listener when a -ClientResponse emits a 'data' event. - - -

-

Event: 'end'#

-

function () { } - -

-

Emitted exactly once for each message. No arguments. After -emitted no other events will be emitted on the response. - -

-

Event: 'close'#

-

function (err) { } - -

-

Indicates that the underlaying connection was terminated before -end event was emitted. -See http.ServerRequest's 'close' event for more -information. - -

-

response.statusCode#

-

The 3-digit HTTP response status code. E.G. 404. - -

-

response.httpVersion#

-

The HTTP version of the connected-to server. Probably either -'1.1' or '1.0'. -Also response.httpVersionMajor is the first integer and -response.httpVersionMinor is the second. - -

-

response.headers#

-

The response headers object. - -

-

response.trailers#

-

The response trailers object. Only populated after the 'end' event. - -

-

response.setEncoding([encoding])#

-

Set the encoding for the response body. Either 'utf8', 'ascii', or -'base64'. Defaults to null, which means that the 'data' event will emit -a Buffer object. - -

-

response.pause()#

-

Pauses response from emitting events. Useful to throttle back a download. - -

-

response.resume()#

-

Resumes a paused response. - -

-

HTTPS#

-
Stability: 3 - Stable
-

HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a -separate module. - -

-

Class: https.Server#

-

This class is a subclass of tls.Server and emits events same as -http.Server. See http.Server for more information. - -

-

https.createServer(options, [requestListener])#

-

Returns a new HTTPS web server object. The options is similar to -tls.createServer(). The requestListener is a function which is -automatically added to the 'request' event. - -

-

Example: - -

-
// curl -k https://localhost:8000/
-var https = require('https');
-var fs = require('fs');
-
-var options = {
-  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
-  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
-};
-
-https.createServer(options, function (req, res) {
-  res.writeHead(200);
-  res.end("hello world\n");
-}).listen(8000);
-

Or - -

-
var https = require('https');
-var fs = require('fs');
-
-var options = {
-  pfx: fs.readFileSync('server.pfx')
-};
-
-https.createServer(options, function (req, res) {
-  res.writeHead(200);
-  res.end("hello world\n");
-}).listen(8000);
-

https.request(options, callback)#

-

Makes a request to a secure web server. -All options from http.request() are valid. - -

-

Example: - -

-
var https = require('https');
-
-var options = {
-  host: 'encrypted.google.com',
-  port: 443,
-  path: '/',
-  method: 'GET'
-};
-
-var req = https.request(options, function(res) {
-  console.log("statusCode: ", res.statusCode);
-  console.log("headers: ", res.headers);
-
-  res.on('data', function(d) {
-    process.stdout.write(d);
-  });
-});
-req.end();
-
-req.on('error', function(e) {
-  console.error(e);
-});
-

The options argument has the following options - -

-
    -
  • host: IP or domain of host to make request to. Defaults to 'localhost'.
    • -
  • port: port of host to request to. Defaults to 443.
    • -
  • path: Path to request. Default '/'.
    • -

  • method: HTTP request method. Default 'GET'.

    -
    • -

  • host: A domain name or IP address of the server to issue the request to. -Defaults to 'localhost'.

    -
    • -
  • hostname: To support url.parse() hostname is preferred over host
    • -
  • port: Port of remote server. Defaults to 443.
    • -
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • -
  • path: Request path. Defaults to '/'. Should include query string if any. -E.G. '/index.html?page=12'
    • -
  • headers: An object containing request headers.
    • -
  • auth: Basic authentication i.e. 'user:password' to compute an -Authorization header.
    • -
  • agent: Controls Agent behavior. When an Agent is -used request will default to Connection: keep-alive. Possible values:
      -
    • undefined (default): use globalAgent for this -host and port.
      • -
    • Agent object: explicitly use the passed in Agent.
      • -
    • false: opts out of connection pooling with an Agent, defaults request to -Connection: close.
      • -
    -
    • -
-

The following options from tls.connect() can also be -specified. However, a globalAgent silently ignores these. - -

-
    -
  • pfx: Certificate, Private key and CA certificates to use for SSL. Default null.
    • -
  • key: Private key to use for SSL. Default null.
    • -
  • passphrase: A string of passphrase for the private key or pfx. Default null.
    • -
  • cert: Public x509 certificate to use. Default null.
    • -
  • ca: An authority certificate or array of authority certificates to check -the remote host against.
    • -
-

In order to specify these options, use a custom Agent. - -

-

Example: - -

-
var options = {
-  host: 'encrypted.google.com',
-  port: 443,
-  path: '/',
-  method: 'GET',
-  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
-  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
-};
-options.agent = new https.Agent(options);
-
-var req = https.request(options, function(res) {
-  ...
-}
-

Or does not use an Agent. - -

-

Example: - -

-
var options = {
-  host: 'encrypted.google.com',
-  port: 443,
-  path: '/',
-  method: 'GET',
-  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
-  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
-  agent: false
-};
-
-var req = https.request(options, function(res) {
-  ...
-}
-

https.get(options, callback)#

-

Like http.get() but for HTTPS. - -

-

Example: - -

-
var https = require('https');
-
-https.get({ host: 'encrypted.google.com', path: '/' }, function(res) {
-  console.log("statusCode: ", res.statusCode);
-  console.log("headers: ", res.headers);
-
-  res.on('data', function(d) {
-    process.stdout.write(d);
-  });
-
-}).on('error', function(e) {
-  console.error(e);
-});
-

Class: https.Agent#

-

An Agent object for HTTPS similar to http.Agent. -See https.request() for more information. - - -

-

https.globalAgent#

-

Global instance of https.Agent which is used as the default -for all HTTPS client requests. - -

-

URL#

-
Stability: 3 - Stable
-

This module has utilities for URL resolution and parsing. -Call require('url') to use it. - -

-

Parsed URL objects have some or all of the following fields, depending on -whether or not they exist in the URL string. Any parts that are not in the URL -string will not be in the parsed object. Examples are shown for the URL - -

-

'http://user:pass@host.com:8080/p/a/t/h?query=string#hash' - -

-
    -

  • href: The full URL that was originally parsed. Both the protocol and host are lowercased.

    -

    Example: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

    -
    • -

  • protocol: The request protocol, lowercased.

    -

    Example: 'http:'

    -
    • -

  • host: The full lowercased host portion of the URL, including port -information.

    -

    Example: 'host.com:8080'

    -
    • -

  • auth: The authentication information portion of a URL.

    -

    Example: 'user:pass'

    -
    • -

  • hostname: Just the lowercased hostname portion of the host.

    -

    Example: 'host.com'

    -
    • -

  • port: The port number portion of the host.

    -

    Example: '8080'

    -
    • -

  • pathname: The path section of the URL, that comes after the host and -before the query, including the initial slash if present.

    -

    Example: '/p/a/t/h'

    -
    • -

  • search: The 'query string' portion of the URL, including the leading -question mark.

    -

    Example: '?query=string'

    -
    • -

  • path: Concatenation of pathname and search.

    -

    Example: '/p/a/t/h?query=string'

    -
    • -

  • query: Either the 'params' portion of the query string, or a -querystring-parsed object.

    -

    Example: 'query=string' or {'query':'string'}

    -
    • -

  • hash: The 'fragment' portion of the URL including the pound-sign.

    -

    Example: '#hash'

    -
    • -
-

The following methods are provided by the URL module: - -

-

url.parse(urlStr, [parseQueryString], [slashesDenoteHost])#

-

Take a URL string, and return an object. - -

-

Pass true as the second argument to also parse -the query string using the querystring module. -Defaults to false. - -

-

Pass true as the third argument to treat //foo/bar as -{ host: 'foo', pathname: '/bar' } rather than -{ pathname: '//foo/bar' }. Defaults to false. - -

-

url.format(urlObj)#

-

Take a parsed URL object, and return a formatted URL string. - -

-
    -
  • href will be ignored.
    • -
  • protocolis treated the same with or without the trailing : (colon).
      -
    • The protocols http, https, ftp, gopher, file will be -postfixed with :// (colon-slash-slash).
      • -
    • All other protocols mailto, xmpp, aim, sftp, foo, etc will -be postfixed with : (colon)
      • -
    -
    • -
  • auth will be used if present.
    • -
  • hostname will only be used if host is absent.
    • -
  • port will only be used if host is absent.
    • -
  • host will be used in place of auth, hostname, and port
    • -
  • pathname is treated the same with or without the leading / (slash)
    • -
  • search will be used in place of query
    • -
  • query (object; see querystring) will only be used if search is absent.
    • -
  • search is treated the same with or without the leading ? (question mark)
    • -
  • hash is treated the same with or without the leading # (pound sign, anchor)
    • -
-

url.resolve(from, to)#

-

Take a base URL, and a href URL, and resolve them as a browser would for -an anchor tag. - -

-

Query String#

-
Stability: 3 - Stable
- - -

This module provides utilities for dealing with query strings. -It provides the following methods: - -

-

querystring.stringify(obj, [sep], [eq])#

-

Serialize an object to a query string. -Optionally override the default separator ('&') and assignment ('=') -characters. - -

-

Example: - -

-
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })
-// returns
-'foo=bar&baz=qux&baz=quux&corge='
-
-querystring.stringify({foo: 'bar', baz: 'qux'}, ';', ':')
-// returns
-'foo:bar;baz:qux'
-

querystring.parse(str, [sep], [eq])#

-

Deserialize a query string to an object. -Optionally override the default separator ('&') and assignment ('=') -characters. - -

-

Example: - -

-
querystring.parse('foo=bar&baz=qux&baz=quux&corge')
-// returns
-{ foo: 'bar', baz: ['qux', 'quux'], corge: '' }
-

querystring.escape#

-

The escape function used by querystring.stringify, -provided so that it could be overridden if necessary. - -

-

querystring.unescape#

-

The unescape function used by querystring.parse, -provided so that it could be overridden if necessary. - -

-

Readline#

-
Stability: 3 - Stable
-

To use this module, do require('readline'). Readline allows reading of a -stream (such as STDIN) on a line-by-line basis. - -

-

Note that once you've invoked this module, your node program will not -terminate until you've closed the interface, and the STDIN stream. Here's how -to allow your program to gracefully terminate: - -

-
var rl = require('readline');
-
-var i = rl.createInterface(process.stdin, process.stdout, null);
-i.question("What do you think of node.js?", function(answer) {
-  // TODO: Log the answer in a database
-  console.log("Thank you for your valuable feedback.");
-
-  // These two lines together allow the program to terminate. Without
-  // them, it would run forever.
-  i.close();
-  process.stdin.destroy();
-});
-

rl.createInterface(input, output, completer)#

-

Takes two streams and creates a readline interface. The completer function -is used for autocompletion. When given a substring, it returns [[substr1, -substr2, ...], originalsubstring]. - -

-

Also completer can be run in async mode if it accepts two arguments: - -

-

function completer(linePartial, callback) { - callback(null, [['123'], linePartial]); - } - -

-

createInterface is commonly used with process.stdin and -process.stdout in order to accept user input: - -

-
var readline = require('readline'),
-  rl = readline.createInterface(process.stdin, process.stdout);
-

Class: Interface#

-

The class that represents a readline interface with a stdin and stdout -stream. - -

-

rl.setPrompt(prompt, length)#

-

Sets the prompt, for example when you run node on the command line, you see -> , which is node's prompt. - -

-

rl.prompt()#

-

Readies readline for input from the user, putting the current setPrompt -options on a new line, giving the user a new spot to write. - -

-

rl.question(query, callback)#

-

Prepends the prompt with query and invokes callback with the user's -response. Displays the query to the user, and then invokes callback with the -user's response after it has been typed. - -

-

Example usage: - -

-
interface.question('What is your favorite food?', function(answer) {
-  console.log('Oh, so your favorite food is ' + answer);
-});
-

rl.close()#

-

Closes tty. - -

-

rl.pause()#

-

Pauses tty. - -

-

rl.resume()#

-

Resumes tty. - -

-

rl.write()#

-

Writes to tty. - -

-

Event: 'line'#

-

function (line) {} - -

-

Emitted whenever the in stream receives a \n, usually received when the -user hits enter, or return. This is a good hook to listen for user input. - -

-

Example of listening for line: - -

-
rl.on('line', function (cmd) {
-  console.log('You just typed: '+cmd);
-});
-

Event: 'close'#

-

function () {} - -

-

Emitted whenever the in stream receives a ^C or ^D, respectively known -as SIGINT and EOT. This is a good way to know the user is finished using -your program. - -

-

Example of listening for close, and exiting the program afterward: - -

-
rl.on('close', function() {
-  console.log('goodbye!');
-  process.exit(0);
-});
-

Here's an example of how to use all these together to craft a tiny command -line interface: - -

-
var readline = require('readline'),
-  rl = readline.createInterface(process.stdin, process.stdout),
-  prefix = 'OHAI> ';
-
-rl.on('line', function(line) {
-  switch(line.trim()) {
-    case 'hello':
-      console.log('world!');
-      break;
-    default:
-      console.log('Say what? I might have heard `' + line.trim() + '`');
-      break;
-  }
-  rl.setPrompt(prefix, prefix.length);
-  rl.prompt();
-}).on('close', function() {
-  console.log('Have a great day!');
-  process.exit(0);
-});
-console.log(prefix + 'Good to see you. Try typing stuff.');
-rl.setPrompt(prefix, prefix.length);
-rl.prompt();
-

Take a look at this slightly more complicated -example, and -http-console for a real-life use -case. - -

-

REPL#

-

A Read-Eval-Print-Loop (REPL) is available both as a standalone program and easily -includable in other programs. REPL provides a way to interactively run -JavaScript and see the results. It can be used for debugging, testing, or -just trying things out. - -

-

By executing node without any arguments from the command-line you will be -dropped into the REPL. It has simplistic emacs line-editing. - -

-
mjr:~$ node
-Type '.help' for options.
-> a = [ 1, 2, 3];
-[ 1, 2, 3 ]
-> a.forEach(function (v) {
-...   console.log(v);
-...   });
-1
-2
-3
-

For advanced line-editors, start node with the environmental variable NODE_NO_READLINE=1. -This will start the REPL in canonical terminal settings which will allow you to use with rlwrap. - -

-

For example, you could add this to your bashrc file: - -

-
alias node="env NODE_NO_READLINE=1 rlwrap node"
-

repl.start([prompt], [stream], [eval], [useGlobal], [ignoreUndefined])#

-

Starts a REPL with prompt as the prompt and stream for all I/O. prompt -is optional and defaults to > . stream is optional and defaults to -process.stdin. eval is optional too and defaults to async wrapper for -eval(). - -

-

If useGlobal is set to true, then the repl will use the global object, -instead of running scripts in a separate context. Defaults to false. - -

-

If ignoreUndefined is set to true, then the repl will not output return value -of command if it's undefined. Defaults to false. - -

-

You can use your own eval function if it has following signature: - -

-
function eval(cmd, callback) {
-  callback(null, result);
-}
-

Multiple REPLs may be started against the same running instance of node. Each -will share the same global object but will have unique I/O. - -

-

Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket: - -

-
var net = require("net"),
-    repl = require("repl");
-
-connections = 0;
-
-repl.start("node via stdin> ");
-
-net.createServer(function (socket) {
-  connections += 1;
-  repl.start("node via Unix socket> ", socket);
-}).listen("/tmp/node-repl-sock");
-
-net.createServer(function (socket) {
-  connections += 1;
-  repl.start("node via TCP socket> ", socket);
-}).listen(5001);
-

Running this program from the command line will start a REPL on stdin. Other -REPL clients may connect through the Unix socket or TCP socket. telnet is useful -for connecting to TCP sockets, and socat can be used to connect to both Unix and -TCP sockets. - -

-

By starting a REPL from a Unix socket-based server instead of stdin, you can -connect to a long-running node process without restarting it. - - -

-

REPL Features#

- - -

Inside the REPL, Control+D will exit. Multi-line expressions can be input. -Tab completion is supported for both global and local variables. - -

-

The special variable _ (underscore) contains the result of the last expression. - -

-
> [ "a", "b", "c" ]
-[ 'a', 'b', 'c' ]
-> _.length
-3
-> _ += 1
-4
-

The REPL provides access to any variables in the global scope. You can expose -a variable to the REPL explicitly by assigning it to the context object -associated with each REPLServer. For example: - -

-
// repl_test.js
-var repl = require("repl"),
-    msg = "message";
-
-repl.start().context.m = msg;
-

Things in the context object appear as local within the REPL: - -

-
mjr:~$ node repl_test.js
-> m
-'message'
-

There are a few special REPL commands: - -

-
    -
  • .break - While inputting a multi-line expression, sometimes you get lost -or just don't care about completing it. .break will start over.
    • -
  • .clear - Resets the context object to an empty object and clears any -multi-line expression.
    • -
  • .exit - Close the I/O stream, which will cause the REPL to exit.
    • -
  • .help - Show this list of special commands.
    • -
  • .save - Save the current REPL session to a file
    -

    .save ./file/to/save.js

    -
    -
    • -
  • .load - Load a file into the current REPL session.
    -

    .load ./file/to/load.js

    -
    -
    • -
-

The following key combinations in the REPL have these special effects: - -

-
    -
  • <ctrl>C - Similar to the .break keyword. Terminates the current -command. Press twice on a blank line to forcibly exit.
    • -
  • <ctrl>D - Similar to the .exit keyword.
    • -
-

Executing JavaScript#

-
Stability: 3 - Stable
- - -

You can access this module with: - -

-
var vm = require('vm');
-

JavaScript code can be compiled and run immediately or compiled, saved, and run later. - - -

-

vm.runInThisContext(code, [filename])#

-

vm.runInThisContext() compiles code, runs it and returns the result. Running -code does not have access to local scope. filename is optional, it's used only -in stack traces. - -

-

Example of using vm.runInThisContext and eval to run the same code: - -

-
var localVar = 123,
-    usingscript, evaled,
-    vm = require('vm');
-
-usingscript = vm.runInThisContext('localVar = 1;',
-  'myfile.vm');
-console.log('localVar: ' + localVar + ', usingscript: ' +
-  usingscript);
-evaled = eval('localVar = 1;');
-console.log('localVar: ' + localVar + ', evaled: ' +
-  evaled);
-
-// localVar: 123, usingscript: 1
-// localVar: 1, evaled: 1
-

vm.runInThisContext does not have access to the local scope, so localVar is unchanged. -eval does have access to the local scope, so localVar is changed. - -

-

In case of syntax error in code, vm.runInThisContext emits the syntax error to stderr -and throws an exception. - - -

-

vm.runInNewContext(code, [sandbox], [filename])#

-

vm.runInNewContext compiles code, then runs it in sandbox and returns the -result. Running code does not have access to local scope. The object sandbox -will be used as the global object for code. -sandbox and filename are optional, filename is only used in stack traces. - -

-

Example: compile and execute code that increments a global variable and sets a new one. -These globals are contained in the sandbox. - -

-
var util = require('util'),
-    vm = require('vm'),
-    sandbox = {
-      animal: 'cat',
-      count: 2
-    };
-
-vm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');
-console.log(util.inspect(sandbox));
-
-// { animal: 'cat', count: 3, name: 'kitty' }
-

Note that running untrusted code is a tricky business requiring great care. To prevent accidental -global variable leakage, vm.runInNewContext is quite useful, but safely running untrusted code -requires a separate process. - -

-

In case of syntax error in code, vm.runInNewContext emits the syntax error to stderr -and throws an exception. - -

-

vm.runInContext(code, context, [filename])#

-

vm.runInContext compiles code, then runs it in context and returns the -result. A (V8) context comprises a global object, together with a set of -built-in objects and functions. Running code does not have access to local scope -and the global object held within context will be used as the global object -for code. -filename is optional, it's used only in stack traces. - -

-

Example: compile and execute code in a existing context. - -

-
var util = require('util'),
-    vm = require('vm'),
-    initSandbox = {
-      animal: 'cat',
-      count: 2
-    },
-    context = vm.createContext(initSandbox);
-
-vm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');
-console.log(util.inspect(context));
-
-// { animal: 'cat', count: 3, name: 'CATT' }
-

Note that createContext will perform a shallow clone of the supplied sandbox object in order to -initialise the global object of the freshly constructed context. - -

-

Note that running untrusted code is a tricky business requiring great care. To prevent accidental -global variable leakage, vm.runInContext is quite useful, but safely running untrusted code -requires a separate process. - -

-

In case of syntax error in code, vm.runInContext emits the syntax error to stderr -and throws an exception. - -

-

vm.createContext([initSandbox])#

-

vm.createContext creates a new context which is suitable for use as the 2nd argument of a subsequent -call to vm.runInContext. A (V8) context comprises a global object together with a set of -build-in objects and functions. The optional argument initSandbox will be shallow-copied -to seed the initial contents of the global object used by the context. - -

-

vm.createScript(code, [filename])#

-

createScript compiles code but does not run it. Instead, it returns a -vm.Script object representing this compiled code. This script can be run -later many times using methods below. The returned script is not bound to any -global object. It is bound before each run, just for that run. filename is -optional, it's only used in stack traces. - -

-

In case of syntax error in code, createScript prints the syntax error to stderr -and throws an exception. - - -

-

Class: Script#

-

A class for running scripts. Returned by vm.createScript. - -

-

script.runInThisContext()#

-

Similar to vm.runInThisContext but a method of a precompiled Script object. -script.runInThisContext runs the code of script and returns the result. -Running code does not have access to local scope, but does have access to the global object -(v8: in actual context). - -

-

Example of using script.runInThisContext to compile code once and run it multiple times: - -

-
var vm = require('vm');
-
-globalVar = 0;
-
-var script = vm.createScript('globalVar += 1', 'myfile.vm');
-
-for (var i = 0; i < 1000 ; i += 1) {
-  script.runInThisContext();
-}
-
-console.log(globalVar);
-
-// 1000
-

script.runInNewContext([sandbox])#

-

Similar to vm.runInNewContext a method of a precompiled Script object. -script.runInNewContext runs the code of script with sandbox as the global object and returns the result. -Running code does not have access to local scope. sandbox is optional. - -

-

Example: compile code that increments a global variable and sets one, then execute this code multiple times. -These globals are contained in the sandbox. - -

-
var util = require('util'),
-    vm = require('vm'),
-    sandbox = {
-      animal: 'cat',
-      count: 2
-    };
-
-var script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');
-
-for (var i = 0; i < 10 ; i += 1) {
-  script.runInNewContext(sandbox);
-}
-
-console.log(util.inspect(sandbox));
-
-// { animal: 'cat', count: 12, name: 'kitty' }
-

Note that running untrusted code is a tricky business requiring great care. To prevent accidental -global variable leakage, script.runInNewContext is quite useful, but safely running untrusted code -requires a separate process. - -

-

Child Process#

-
Stability: 3 - Stable
-

Node provides a tri-directional popen(3) facility through the -child_process module. - -

-

It is possible to stream data through a child's stdin, stdout, and -stderr in a fully non-blocking way. - -

-

To create a child process use require('child_process').spawn() or -require('child_process').fork(). The semantics of each are slightly -different, and explained below. - -

-

Class: ChildProcess#

-

ChildProcess is an EventEmitter. - -

-

Child processes always have three streams associated with them. child.stdin, -child.stdout, and child.stderr. These may be shared with the stdio -streams of the parent process, or they may be separate stream objects -which can be piped to and from. - -

-

The ChildProcess class is not intended to be used directly. Use the -spawn() or fork() methods to create a Child Process instance. - -

-

Event: 'exit'#

-
    -
  • code Number the exit code, if it exited normally.
    • -
  • signal String the signal passed to kill the child process, if it -was killed by the parent.
    • -
-

This event is emitted after the child process ends. If the process terminated -normally, code is the final exit code of the process, otherwise null. If -the process terminated due to receipt of a signal, signal is the string name -of the signal, otherwise null. - -

-

See waitpid(2). - -

-

child.stdin#

-
    -
  • Stream object
    • -
-

A Writable Stream that represents the child process's stdin. -Closing this stream via end() often causes the child process to terminate. - -

-

If the child stdio streams are shared with the parent, then this will -not be set. - -

-

child.stdout#

-
    -
  • Stream object
    • -
-

A Readable Stream that represents the child process's stdout. - -

-

If the child stdio streams are shared with the parent, then this will -not be set. - -

-

child.stderr#

-
    -
  • Stream object
    • -
-

A Readable Stream that represents the child process's stderr. - -

-

If the child stdio streams are shared with the parent, then this will -not be set. - -

-

child.pid#

-
    -
  • Integer
    • -
-

The PID of the child process. - -

-

Example: - -

-
var spawn = require('child_process').spawn,
-    grep  = spawn('grep', ['ssh']);
-
-console.log('Spawned child pid: ' + grep.pid);
-grep.stdin.end();
-

child.kill([signal])#

-
    -
  • signal String
    • -
-

Send a signal to the child process. If no argument is given, the process will -be sent 'SIGTERM'. See signal(7) for a list of available signals. - -

-
var spawn = require('child_process').spawn,
-    grep  = spawn('grep', ['ssh']);
-
-grep.on('exit', function (code, signal) {
-  console.log('child process terminated due to receipt of signal '+signal);
-});
-
-// send SIGHUP to process
-grep.kill('SIGHUP');
-

Note that while the function is called kill, the signal delivered to the child -process may not actually kill it. kill really just sends a signal to a process. - -

-

See kill(2) - -

-

child.send(message, [sendHandle])#

-
    -
  • message Object
    • -
  • sendHandle Handle object
    • -
-

Send a message (and, optionally, a handle object) to a child process. - -

-

See child_process.fork() for details. - -

-

child_process.spawn(command, [args], [options])#

-
    -
  • command String The command to run
    • -
  • args Array List of string arguments
    • -
  • options Object
      -
    • cwd String Current working directory of the child process
      • -
    • customFds Array Deprecated File descriptors for the child to use -for stdio. (See below)
      • -
    • env Object Environment key-value pairs
      • -
    • setsid Boolean
      • -
    -
    • -
  • return: ChildProcess object
    • -
-

Launches a new process with the given command, with command line arguments in args. -If omitted, args defaults to an empty Array. - -

-

The third argument is used to specify additional options, which defaults to: - -

-
{ cwd: undefined,
-  env: process.env
-}
-

cwd allows you to specify the working directory from which the process is spawned. -Use env to specify environment variables that will be visible to the new process. - -

-

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code: - -

-
var util  = require('util'),
-    spawn = require('child_process').spawn,
-    ls    = spawn('ls', ['-lh', '/usr']);
-
-ls.stdout.on('data', function (data) {
-  console.log('stdout: ' + data);
-});
-
-ls.stderr.on('data', function (data) {
-  console.log('stderr: ' + data);
-});
-
-ls.on('exit', function (code) {
-  console.log('child process exited with code ' + code);
-});
-

Example: A very elaborate way to run 'ps ax | grep ssh' - -

-
var util  = require('util'),
-    spawn = require('child_process').spawn,
-    ps    = spawn('ps', ['ax']),
-    grep  = spawn('grep', ['ssh']);
-
-ps.stdout.on('data', function (data) {
-  grep.stdin.write(data);
-});
-
-ps.stderr.on('data', function (data) {
-  console.log('ps stderr: ' + data);
-});
-
-ps.on('exit', function (code) {
-  if (code !== 0) {
-    console.log('ps process exited with code ' + code);
-  }
-  grep.stdin.end();
-});
-
-grep.stdout.on('data', function (data) {
-  console.log(data);
-});
-
-grep.stderr.on('data', function (data) {
-  console.log('grep stderr: ' + data);
-});
-
-grep.on('exit', function (code) {
-  if (code !== 0) {
-    console.log('grep process exited with code ' + code);
-  }
-});
-

Example of checking for failed exec: - -

-
var spawn = require('child_process').spawn,
-    child = spawn('bad_command');
-
-child.stderr.setEncoding('utf8');
-child.stderr.on('data', function (data) {
-  if (/^execvp\(\)/.test(data)) {
-    console.log('Failed to start child process.');
-  }
-});
-

Note that if spawn receives an empty options object, it will result in -spawning the process with an empty environment rather than using -process.env. This due to backwards compatibility issues with a deprecated -API. - -

-

There is a deprecated option called customFds which allows one to specify -specific file descriptors for the stdio of the child process. This API was -not portable to all platforms and therefore removed. -With customFds it was possible to hook up the new process' [stdin, stdout, -stderr] to existing streams; -1 meant that a new stream should be created. -Use at your own risk. - -

-

There are several internal options. In particular stdinStream, -stdoutStream, stderrStream. They are for INTERNAL USE ONLY. As with all -undocumented APIs in Node, they should not be used. - -

-

See also: child_process.exec() and child_process.fork() - -

-

child_process.exec(command, [options], callback)#

-
    -
  • command String The command to run, with space-separated arguments
    • -
  • options Object
      -
    • cwd String Current working directory of the child process
      • -
    • customFds Array Deprecated File descriptors for the child to use -for stdio. (See below)
      • -
    • env Object Environment key-value pairs
      • -
    • setsid Boolean
      • -
    • encoding String (Default: 'utf8')
      • -
    • timeout Number (Default: 0)
      • -
    • maxBuffer Number (Default: 200*1024)
      • -
    • killSignal String (Default: 'SIGTERM')
      • -
    -
    • -
  • callback Function called with the output when process terminates
      -
    • error Error
      • -
    • stdout Buffer
      • -
    • stderr Buffer
      • -
    -
    • -
  • Return: ChildProcess object
    • -
-

Runs a command in a shell and buffers the output. - -

-
var util = require('util'),
-    exec = require('child_process').exec,
-    child;
-
-child = exec('cat *.js bad_file | wc -l',
-  function (error, stdout, stderr) {
-    console.log('stdout: ' + stdout);
-    console.log('stderr: ' + stderr);
-    if (error !== null) {
-      console.log('exec error: ' + error);
-    }
-});
-

The callback gets the arguments (error, stdout, stderr). On success, error -will be null. On error, error will be an instance of Error and err.code -will be the exit code of the child process, and err.signal will be set to the -signal that terminated the process. - -

-

There is a second optional argument to specify several options. The -default options are - -

-
{ encoding: 'utf8',
-  timeout: 0,
-  maxBuffer: 200*1024,
-  killSignal: 'SIGTERM',
-  cwd: null,
-  env: null }
-

If timeout is greater than 0, then it will kill the child process -if it runs longer than timeout milliseconds. The child process is killed with -killSignal (default: 'SIGTERM'). maxBuffer specifies the largest -amount of data allowed on stdout or stderr - if this value is exceeded then -the child process is killed. - - -

-

child_process.execFile(file, args, options, callback)#

-
    -
  • file String The filename of the program to run
    • -
  • args Array List of string arguments
    • -
  • options Object
      -
    • cwd String Current working directory of the child process
      • -
    • customFds Array Deprecated File descriptors for the child to use -for stdio. (See below)
      • -
    • env Object Environment key-value pairs
      • -
    • setsid Boolean
      • -
    • encoding String (Default: 'utf8')
      • -
    • timeout Number (Default: 0)
      • -
    • maxBuffer Number (Default: 200*1024)
      • -
    • killSignal String (Default: 'SIGTERM')
      • -
    -
    • -
  • callback Function called with the output when process terminates
      -
    • error Error
      • -
    • stdout Buffer
      • -
    • stderr Buffer
      • -
    -
    • -
  • Return: ChildProcess object
    • -
-

This is similar to child_process.exec() except it does not execute a -subshell but rather the specified file directly. This makes it slightly -leaner than child_process.exec. It has the same options. - - -

-

child_process.fork(modulePath, [args], [options])#

-
    -
  • modulePath String The module to run in the child
    • -
  • args Array List of string arguments
    • -
  • options Object
      -
    • cwd String Current working directory of the child process
      • -
    • customFds Array Deprecated File descriptors for the child to use -for stdio. (See below)
      • -
    • env Object Environment key-value pairs
      • -
    • setsid Boolean
      • -
    • encoding String (Default: 'utf8')
      • -
    • timeout Number (Default: 0)
      • -
    -
    • -
  • Return: ChildProcess object
    • -
-

This is a special case of the spawn() functionality for spawning Node -processes. In addition to having all the methods in a normal ChildProcess -instance, the returned object has a communication channel built-in. The -channel is written to with child.send(message, [sendHandle]) and messages -are received by a 'message' event on the child. - -

-

For example: - -

-
var cp = require('child_process');
-
-var n = cp.fork(__dirname + '/sub.js');
-
-n.on('message', function(m) {
-  console.log('PARENT got message:', m);
-});
-
-n.send({ hello: 'world' });
-

And then the child script, 'sub.js' might look like this: - -

-
process.on('message', function(m) {
-  console.log('CHILD got message:', m);
-});
-
-process.send({ foo: 'bar' });
-

In the child the process object will have a send() method, and process -will emit objects each time it receives a message on its channel. - -

-

By default the spawned Node process will have the stdin, stdout, stderr -associated with the parent's. - -

-

These child Nodes are still whole new instances of V8. Assume at least 30ms -startup and 10mb memory for each new Node. That is, you cannot create many -thousands of them. - -

-

The sendHandle option to child.send() is for sending a handle object to -another process. Child will receive the handle as as second argument to the -message event. Here is an example of sending a handle: - -

-
var server = require('net').createServer();
-var child = require('child_process').fork(__dirname + '/child.js');
-// Open up the server object and send the handle.
-server.listen(1337, function() {
-  child.send({ server: true }, server._handle);
-});
-

Here is an example of receiving the server handle and sharing it between -processes: - -

-
process.on('message', function(m, serverHandle) {
-  if (serverHandle) {
-    var server = require('net').createServer();
-    server.listen(serverHandle);
-  }
-});
-

Assert#

-
Stability: 5 - Locked
-

This module is used for writing unit tests for your applications, you can -access it with require('assert'). - -

-

assert.fail(actual, expected, message, operator)#

-

Throws an exception that displays the values for actual and expected separated by the provided operator. - -

-

assert(value, message), assert.ok(value, [message])#

-

Tests if value is a true value, it is equivalent to assert.equal(true, value, message); - -

-

assert.equal(actual, expected, [message])#

-

Tests shallow, coercive equality with the equal comparison operator ( == ). - -

-

assert.notEqual(actual, expected, [message])#

-

Tests shallow, coercive non-equality with the not equal comparison operator ( != ). - -

-

assert.deepEqual(actual, expected, [message])#

-

Tests for deep equality. - -

-

assert.notDeepEqual(actual, expected, [message])#

-

Tests for any deep inequality. - -

-

assert.strictEqual(actual, expected, [message])#

-

Tests strict equality, as determined by the strict equality operator ( === ) - -

-

assert.notStrictEqual(actual, expected, [message])#

-

Tests strict non-equality, as determined by the strict not equal operator ( !== ) - -

-

assert.throws(block, [error], [message])#

-

Expects block to throw an error. error can be constructor, regexp or -validation function. - -

-

Validate instanceof using constructor: - -

-
assert.throws(
-  function() {
-    throw new Error("Wrong value");
-  },
-  Error
-);
-

Validate error message using RegExp: - -

-
assert.throws(
-  function() {
-    throw new Error("Wrong value");
-  },
-  /value/
-);
-

Custom error validation: - -

-
assert.throws(
-  function() {
-    throw new Error("Wrong value");
-  },
-  function(err) {
-    if ( (err instanceof Error) && /value/.test(err) ) {
-      return true;
-    }
-  },
-  "unexpected error"
-);
-

assert.doesNotThrow(block, [error], [message])#

-

Expects block not to throw an error, see assert.throws for details. - -

-

assert.ifError(value)#

-

Tests if value is not a false value, throws if it is a true value. Useful when -testing the first argument, error in callbacks. - -

-

TTY#

-
Stability: 3 - Stable
-

Use require('tty') to access this module. - -

-

Example: - -

-
var tty = require('tty');
-process.stdin.resume();
-tty.setRawMode(true);
-process.stdin.on('keypress', function(char, key) {
-  if (key && key.ctrl && key.name == 'c') {
-    console.log('graceful exit');
-    process.exit()
-  }
-});
-

tty.isatty(fd)#

-

Returns true or false depending on if the fd is associated with a -terminal. - - -

-

tty.setRawMode(mode)#

-

mode should be true or false. This sets the properties of the current -process's stdin fd to act either as a raw device or default. - -

-

Zlib#

-
Stability: 3 - Stable
-

You can access this module with: - -

-
var zlib = require('zlib');
-

This provides bindings to Gzip/Gunzip, Deflate/Inflate, and -DeflateRaw/InflateRaw classes. Each class takes the same options, and -is a readable/writable Stream. - -

-

Examples#

-

Compressing or decompressing a file can be done by piping an -fs.ReadStream into a zlib stream, then into an fs.WriteStream. - -

-
var gzip = zlib.createGzip();
-var fs = require('fs');
-var inp = fs.createReadStream('input.txt');
-var out = fs.createWriteStream('input.txt.gz');
-
-inp.pipe(gzip).pipe(out);
-

Compressing or decompressing data in one step can be done by using -the convenience methods. - -

-
var input = '.................................';
-zlib.deflate(input, function(err, buffer) {
-  if (!err) {
-    console.log(buffer.toString('base64'));
-  }
-});
-
-var buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');
-zlib.unzip(buffer, function(err, buffer) {
-  if (!err) {
-    console.log(buffer.toString());
-  }
-});
-

To use this module in an HTTP client or server, use the -accept-encoding -on requests, and the -content-encoding -header on responses. - -

-

Note: these examples are drastically simplified to show -the basic concept. Zlib encoding can be expensive, and the results -ought to be cached. See Memory Usage Tuning -below for more information on the speed/memory/compression -tradeoffs involved in zlib usage. - -

-
// client request example
-var zlib = require('zlib');
-var http = require('http');
-var fs = require('fs');
-var request = http.get({ host: 'izs.me',
-                         path: '/',
-                         port: 80,
-                         headers: { 'accept-encoding': 'gzip,deflate' } });
-request.on('response', function(response) {
-  var output = fs.createWriteStream('izs.me_index.html');
-
-  switch (response.headers['content-encoding']) {
-    // or, just use zlib.createUnzip() to handle both cases
-    case 'gzip':
-      response.pipe(zlib.createGunzip()).pipe(output);
-      break;
-    case 'deflate':
-      response.pipe(zlib.createInflate()).pipe(output);
-      break;
-    default:
-      response.pipe(output);
-      break;
-  }
-});
-
-// server example
-// Running a gzip operation on every request is quite expensive.
-// It would be much more efficient to cache the compressed buffer.
-var zlib = require('zlib');
-var http = require('http');
-var fs = require('fs');
-http.createServer(function(request, response) {
-  var raw = fs.createReadStream('index.html');
-  var acceptEncoding = request.headers['accept-encoding'];
-  if (!acceptEncoding) {
-    acceptEncoding = '';
-  }
-
-  // Note: this is not a conformant accept-encoding parser.
-  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
-  if (acceptEncoding.match(/\bdeflate\b/)) {
-    response.writeHead(200, { 'content-encoding': 'deflate' });
-    raw.pipe(zlib.createDeflate()).pipe(response);
-  } else if (acceptEncoding.match(/\bgzip\b/)) {
-    response.writeHead(200, { 'content-encoding': 'gzip' });
-    raw.pipe(zlib.createGzip()).pipe(response);
-  } else {
-    response.writeHead(200, {});
-    raw.pipe(response);
-  }
-}).listen(1337);
-

Constants#

- - -

All of the constants defined in zlib.h are also defined on -require('zlib'). They are described in more detail in the zlib -documentation. See http://zlib.net/manual.html#Constants -for more details. - -

-

zlib.createGzip([options])#

-

Returns a new Gzip object with an options. - -

-

zlib.createGunzip([options])#

-

Returns a new Gunzip object with an options. - -

-

zlib.createDeflate([options])#

-

Returns a new Deflate object with an options. - -

-

zlib.createInflate([options])#

-

Returns a new Inflate object with an options. - -

-

zlib.createDeflateRaw([options])#

-

Returns a new DeflateRaw object with an options. - -

-

zlib.createInflateRaw([options])#

-

Returns a new InflateRaw object with an options. - -

-

zlib.createUnzip([options])#

-

Returns a new Unzip object with an options. - - -

-

Class: zlib.Gzip#

-

Compress data using gzip. - -

-

Class: zlib.Gunzip#

-

Decompress a gzip stream. - -

-

Class: zlib.Deflate#

-

Compress data using deflate. - -

-

Class: zlib.Inflate#

-

Decompress a deflate stream. - -

-

Class: zlib.DeflateRaw#

-

Compress data using deflate, and do not append a zlib header. - -

-

Class: zlib.InflateRaw#

-

Decompress a raw deflate stream. - -

-

Class: zlib.Unzip#

-

Decompress either a Gzip- or Deflate-compressed stream by auto-detecting -the header. - -

-

Convenience Methods#

- - -

All of these take a string or buffer as the first argument, and call the -supplied callback with callback(error, result). The -compression/decompression engine is created using the default settings -in all convenience methods. To supply different options, use the -zlib classes directly. - -

-

zlib.deflate(buf, callback)#

-

Compress a string with Deflate. - -

-

zlib.deflateRaw(buf, callback)#

-

Compress a string with DeflateRaw. - -

-

zlib.gzip(buf, callback)#

-

Compress a string with Gzip. - -

-

zlib.gunzip(buf, callback)#

-

Decompress a raw Buffer with Gunzip. - -

-

zlib.inflate(buf, callback)#

-

Decompress a raw Buffer with Inflate. - -

-

zlib.inflateRaw(buf, callback)#

-

Decompress a raw Buffer with InflateRaw. - -

-

zlib.unzip(buf, callback)#

-

Decompress a raw Buffer with Unzip. - -

-

Options#

- - -

Each class takes an options object. All options are optional. (The -convenience methods use the default settings for all options.) - -

-

Note that some options are only -relevant when compressing, and are ignored by the decompression classes. - -

-
    -
  • chunkSize (default: 16*1024)
    • -
  • windowBits
    • -
  • level (compression only)
    • -
  • memLevel (compression only)
    • -
  • strategy (compression only)
    • -
-

See the description of deflateInit2 and inflateInit2 at -

-

http://zlib.net/manual.html#Advanced for more information on these. - -

-

Memory Usage Tuning#

- - -

From zlib/zconf.h, modified to node's usage: - -

-

The memory requirements for deflate are (in bytes): - -

-
(1 << (windowBits+2)) +  (1 << (memLevel+9))
-

that is: 128K for windowBits=15 + 128K for memLevel = 8 -(default values) plus a few kilobytes for small objects. - -

-

For example, if you want to reduce -the default memory requirements from 256K to 128K, set the options to: - -

-
{ windowBits: 14, memLevel: 7 }
-

Of course this will generally degrade compression (there's no free lunch). - -

-

The memory requirements for inflate are (in bytes) - -

-
1 << windowBits
-

that is, 32K for windowBits=15 (default value) plus a few kilobytes -for small objects. - -

-

This is in addition to a single internal output slab buffer of size -chunkSize, which defaults to 16K. - -

-

The speed of zlib compression is affected most dramatically by the -level setting. A higher level will result in better compression, but -will take longer to complete. A lower level will result in less -compression, but will be much faster. - -

-

In general, greater memory usage options will mean that node has to make -fewer calls to zlib, since it'll be able to process more data in a -single write operation. So, this is another factor that affects the -speed, at the cost of memory usage. - -

-

os#

-
Stability: 4 - API Frozen
-

Provides a few basic operating-system related utility functions. - -

-

Use require('os') to access this module. - -

-

os.hostname()#

-

Returns the hostname of the operating system. - -

-

os.type()#

-

Returns the operating system name. - -

-

os.platform()#

-

Returns the operating system platform. - -

-

os.arch()#

-

Returns the operating system CPU architecture. - -

-

os.release()#

-

Returns the operating system release. - -

-

os.uptime()#

-

Returns the system uptime in seconds. - -

-

os.loadavg()#

-

Returns an array containing the 1, 5, and 15 minute load averages. - -

-

os.totalmem()#

-

Returns the total amount of system memory in bytes. - -

-

os.freemem()#

-

Returns the amount of free system memory in bytes. - -

-

os.cpus()#

-

Returns an array of objects containing information about each CPU/core installed: model, speed (in MHz), and times (an object containing the number of CPU ticks spent in: user, nice, sys, idle, and irq). - -

-

Example inspection of os.cpus: - -

-
[ { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 252020,
-       nice: 0,
-       sys: 30340,
-       idle: 1070356870,
-       irq: 0 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 306960,
-       nice: 0,
-       sys: 26980,
-       idle: 1071569080,
-       irq: 0 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 248450,
-       nice: 0,
-       sys: 21750,
-       idle: 1070919370,
-       irq: 0 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 256880,
-       nice: 0,
-       sys: 19430,
-       idle: 1070905480,
-       irq: 20 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 511580,
-       nice: 20,
-       sys: 40900,
-       idle: 1070842510,
-       irq: 0 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 291660,
-       nice: 0,
-       sys: 34360,
-       idle: 1070888000,
-       irq: 10 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 308260,
-       nice: 0,
-       sys: 55410,
-       idle: 1071129970,
-       irq: 880 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 266450,
-       nice: 1480,
-       sys: 34920,
-       idle: 1072572010,
-       irq: 30 } } ]
-

os.networkInterfaces()#

-

Get a list of network interfaces: - -

-
{ lo0: 
-   [ { address: '::1', family: 'IPv6', internal: true },
-     { address: 'fe80::1', family: 'IPv6', internal: true },
-     { address: '127.0.0.1', family: 'IPv4', internal: true } ],
-  en1: 
-   [ { address: 'fe80::cabc:c8ff:feef:f996', family: 'IPv6',
-       internal: false },
-     { address: '10.0.1.123', family: 'IPv4', internal: false } ],
-  vmnet1: [ { address: '10.99.99.254', family: 'IPv4', internal: false } ],
-  vmnet8: [ { address: '10.88.88.1', family: 'IPv4', internal: false } ],
-  ppp0: [ { address: '10.2.0.231', family: 'IPv4', internal: false } ] }
-

Debugger#

-
Stability: 3 - Stable
- - -

V8 comes with an extensive debugger which is accessible out-of-process via a -simple TCP protocol. -Node has a built-in client for this debugger. To use this, start Node with the -debug argument; a prompt will appear: - -

-
% node debug myscript.js
-< debugger listening on port 5858
-connecting... ok
-break in /home/indutny/Code/git/indutny/myscript.js:1
-  1 x = 5;
-  2 setTimeout(function () {
-  3   debugger;
-debug>
-

Node's debugger client doesn't support the full range of commands, but -simple step and inspection is possible. By putting the statement debugger; -into the source code of your script, you will enable a breakpoint. - -

-

For example, suppose myscript.js looked like this: - -

-
// myscript.js
-x = 5;
-setTimeout(function () {
-  debugger;
-  console.log("world");
-}, 1000);
-console.log("hello");
-

Then once the debugger is run, it will break on line 4. - -

-
% node debug myscript.js
-< debugger listening on port 5858
-connecting... ok
-break in /home/indutny/Code/git/indutny/myscript.js:1
-  1 x = 5;
-  2 setTimeout(function () {
-  3   debugger;
-debug> cont
-< hello
-break in /home/indutny/Code/git/indutny/myscript.js:3
-  1 x = 5;
-  2 setTimeout(function () {
-  3   debugger;
-  4   console.log("world");
-  5 }, 1000);
-debug> next
-break in /home/indutny/Code/git/indutny/myscript.js:4
-  2 setTimeout(function () {
-  3   debugger;
-  4   console.log("world");
-  5 }, 1000);
-  6 console.log("hello");
-debug> repl
-Press Ctrl + C to leave debug repl
-> x
-5
-> 2+2
-4
-debug> next
-< world
-break in /home/indutny/Code/git/indutny/myscript.js:5
-  3   debugger;
-  4   console.log("world");
-  5 }, 1000);
-  6 console.log("hello");
-  7
-debug> quit
-%
-

The repl command allows you to evaluate code remotely. The next command -steps over to the next line. There are a few other commands available and more -to come. Type help to see others. - -

-

Watchers#

-

You can watch expression and variable values while debugging your code. -On every breakpoint each expression from the watchers list will be evaluated -in the current context and displayed just before the breakpoint's source code -listing. - -

-

To start watching an expression, type watch("my_expression"). watchers -prints the active watchers. To remove a watcher, type -unwatch("my_expression"). - -

-

Commands reference#

-

Stepping#

-
    -
  • cont, c - Continue execution
    • -
  • next, n - Step next
    • -
  • step, s - Step in
    • -
  • out, o - Step out
    • -
-

Breakpoints#

-
    -
  • setBreakpoint(), sb() - Set breakpoint on current line
    • -
  • setBreakpoint('fn()'), sb(...) - Set breakpoint on a first statement in -functions body
    • -
  • setBreakpoint('script.js', 1), sb(...) - Set breakpoint on first line of -script.js
    • -
  • clearBreakpoint, cb(...) - Clear breakpoint
    • -
-

Info#

-
    -
  • backtrace, bt - Print backtrace of current execution frame
    • -
  • list(5) - List scripts source code with 5 line context (5 lines before and -after)
    • -
  • watch(expr) - Add expression to watch list
    • -
  • unwatch(expr) - Remove expression from watch list
    • -
  • watchers - List all watchers and their values (automatically listed on each -breakpoint)
    • -
  • repl - Open debugger's repl for evaluation in debugging script's context
    • -
-

Execution control#

-
    -
  • run - Run script (automatically runs on debugger's start)
    • -
  • restart - Restart script
    • -
  • kill - Kill script
    • -
-

Various#

-
    -
  • scripts - List all loaded scripts
    • -
  • version - Display v8's version
    • -
-

Advanced Usage#

-

The V8 debugger can be enabled and accessed either by starting Node with -the --debug command-line flag or by signaling an existing Node process -with SIGUSR1. - -

-

Cluster#

-
Stability: 1 Experimental - Drastic changes in future versions
-

A single instance of Node runs in a single thread. To take advantage of -multi-core systems the user will sometimes want to launch a cluster of Node -processes to handle the load. - -

-

The cluster module allows you to easily create a network of processes that -all share server ports. - -

-
var cluster = require('cluster');
-var http = require('http');
-var numCPUs = require('os').cpus().length;
-
-if (cluster.isMaster) {
-  // Fork workers.
-  for (var i = 0; i < numCPUs; i++) {
-    cluster.fork();
-  }
-
-  cluster.on('death', function(worker) {
-    console.log('worker ' + worker.pid + ' died');
-  });
-} else {
-  // Worker processes have a http server.
-  http.Server(function(req, res) {
-    res.writeHead(200);
-    res.end("hello world\n");
-  }).listen(8000);
-}
-

Running node will now share port 8000 between the workers: - -

-
% node server.js
-Worker 2438 online
-Worker 2437 online
-

The difference between cluster.fork() and child_process.fork() is simply -that cluster allows TCP servers to be shared between workers. cluster.fork -is implemented on top of child_process.fork. The message passing API that -is available with child_process.fork is available with cluster as well. -As an example, here is a cluster which keeps count of the number of requests -in the master process via message passing: - -

-
var cluster = require('cluster');
-var http = require('http');
-var numReqs = 0;
-
-if (cluster.isMaster) {
-  // Fork workers.
-  for (var i = 0; i < 2; i++) {
-    var worker = cluster.fork();
-
-    worker.on('message', function(msg) {
-      if (msg.cmd && msg.cmd == 'notifyRequest') {
-        numReqs++;
-      }
-    });
-  }
-
-  setInterval(function() {
-    console.log("numReqs =", numReqs);
-  }, 1000);
-} else {
-  // Worker processes have a http server.
-  http.Server(function(req, res) {
-    res.writeHead(200);
-    res.end("hello world\n");
-    // Send message to master process
-    process.send({ cmd: 'notifyRequest' });
-  }).listen(8000);
-}
-

cluster.fork()#

-

Spawn a new worker process. This can only be called from the master process. - -

-

cluster.isMaster#

-

cluster.isWorker#

-

Boolean flags to determine if the current process is a master or a worker -process in a cluster. A process isMaster if process.env.NODE_WORKER_ID -is undefined. - -

-

Event: 'death'#

-

When any of the workers die the cluster module will emit the 'death' event. -This can be used to restart the worker by calling fork() again. - -

-
cluster.on('death', function(worker) {
-  console.log('worker ' + worker.pid + ' died. restart...');
-  cluster.fork();
-});
-

Different techniques can be used to restart the worker depending on the -application. - -

-

Appendix 1 - Third Party Modules#

-

There are many third party modules for Node. At the time of writing, August -2010, the master repository of modules is -the wiki page. - -

-

This appendix is intended as a SMALL guide to new-comers to help them -quickly find what are considered to be quality modules. It is not intended -to be a complete list. There may be better more complete modules found -elsewhere. - -

- -

Patches to this list are welcome. - -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/all.json +++ /dev/null @@ -1,9973 +0,0 @@ -{ - "source": "doc/api/all.markdown", - "miscs": [ - { - "textRaw": "About this Documentation", - "name": "About this Documentation", - "type": "misc", - "desc": "

The goal of this documentation is to comprehensively explain the Node.js\nAPI, both from a reference as well as a conceptual point of view. Each\nsection describes a built-in module or high-level concept.\n\n

\n

Where appropriate, property types, method arguments, and the arguments\nprovided to event handlers are detailed in a list underneath the topic\nheading.\n\n

\n

Every .html document has a corresponding .json document presenting\nthe same information in a structured manner. This feature is\nexperimental, and added for the benefit of IDEs and other utilities that\nwish to do programmatic things with the documentation.\n\n

\n

Every .html and .json file is generated based on the corresponding\n.markdown file in the doc/api/ folder in node's source tree. The\ndocumentation is generated using the tools/doc/generate.js program.\nThe HTML template is located at doc/template.html.\n\n

\n", - "miscs": [ - { - "textRaw": "Stability Index", - "name": "Stability Index", - "type": "misc", - "desc": "

Throughout the documentation, you will see indications of a section's\nstability. The Node.js API is still somewhat changing, and as it\nmatures, certain parts are more reliable than others. Some are so\nproven, and so relied upon, that they are unlikely to ever change at\nall. Others are brand new and experimental, or known to be hazardous\nand in the process of being redesigned.\n\n

\n

The notices look like this:\n\n

\n
Stability: 1 Experimental
\n

The stability indices are as follows:\n\n

\n
    \n
  • 0 - Deprecated This feature is known to be problematic, and changes are\nplanned. Do not rely on it. Use of the feature may cause warnings. Backwards\ncompatibility should not be expected.
    • \n
\n
    \n
  • 1 - Experimental This feature was introduced recently, and may change\nor be removed in future versions. Please try it out and provide feedback.\nIf it addresses a use-case that is important to you, tell the node core team.
    • \n
\n
    \n
  • 2 - Unstable The API is in the process of settling, but has not yet had\nsufficient real-world testing to be considered stable. Backwards-compatibility\nwill be maintained if reasonable.
    • \n
\n
    \n
  • 3 - Stable The API has proven satisfactory, but cleanup in the underlying\ncode may cause minor changes. Backwards-compatibility is guaranteed.
    • \n
\n
    \n
  • 4 - API Frozen This API has been tested extensively in production and is\nunlikely to ever have to change.
    • \n
\n
    \n
  • 5 - Locked Unless serious bugs are found, this code will not ever\nchange. Please do not suggest changes in this area; they will be refused.
    • \n
\n" - }, - { - "textRaw": "JSON Output", - "name": "json_output", - "stability": 1, - "stabilityText": "Experimental", - "desc": "

Every HTML file in the markdown has a corresponding JSON file with the\nsame data.\n\n

\n

This feature is new as of node v0.6.12. It is experimental.\n\n

\n", - "type": "misc", - "displayName": "JSON Output" - } - ] - }, - { - "textRaw": "Synopsis", - "name": "Synopsis", - "type": "misc", - "desc": "

An example of a web server written with Node which responds with 'Hello\nWorld':\n\n

\n
var http = require('http');\n\nhttp.createServer(function (request, response) {\n  response.writeHead(200, {'Content-Type': 'text/plain'});\n  response.end('Hello World\\n');\n}).listen(8124);\n\nconsole.log('Server running at http://127.0.0.1:8124/');
\n

To run the server, put the code into a file called example.js and execute\nit with the node program\n\n

\n
> node example.js\nServer running at http://127.0.0.1:8124/
\n

All of the examples in the documentation can be run similarly.\n\n

\n" - }, - { - "textRaw": "Global Objects", - "name": "Global Objects", - "type": "misc", - "desc": "

These objects are available in all modules. Some of these objects aren't\nactually in the global scope but in the module scope - this will be noted.\n\n

\n", - "globals": [ - { - "textRaw": "global", - "name": "global", - "type": "global", - "desc": "

In browsers, the top-level scope is the global scope. That means that in\nbrowsers if you're in the global scope var something will define a global\nvariable. In Node this is different. The top-level scope is not the global\nscope; var something inside a Node module will be local to that module.\n\n

\n" - }, - { - "textRaw": "process", - "name": "process", - "type": "global", - "desc": "

The process object. See the process object section.\n\n

\n" - }, - { - "textRaw": "console", - "name": "console", - "type": "global", - "desc": "

Used to print to stdout and stderr. See the stdio section.\n\n

\n" - }, - { - "textRaw": "Buffer", - "name": "Buffer", - "type": "global", - "desc": "

Used to handle binary data. See the buffer section.\n\n

\n" - }, - { - "textRaw": "clearInterval(t)", - "type": "global", - "name": "clearInterval", - "desc": "

The timer functions are global variables. See the timers section.\n\n

\n" - }, - { - "textRaw": "console", - "name": "console", - "stability": 4, - "stabilityText": "API Frozen", - "type": "global", - "desc": "

For printing to stdout and stderr. Similar to the console object functions\nprovided by most web browsers, here the output is sent to stdout or stderr.\n\n\n

\n", - "methods": [ - { - "textRaw": "console.log()", - "type": "method", - "name": "log", - "desc": "

Prints to stdout with newline. This function can take multiple arguments in a\nprintf()-like way. Example:\n\n

\n
console.log('count: %d', count);
\n

If formatting elements are not found in the first string then util.inspect\nis used on each argument.\nSee util.format() for more information.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.info()", - "type": "method", - "name": "info", - "desc": "

Same as console.log.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.warn()", - "type": "method", - "name": "warn", - "desc": "

Same as console.log but prints to stderr.\n\n

\n", - "signatures": [ - { - "params": [] - }, - { - "params": [] - } - ] - }, - { - "textRaw": "console.error()", - "type": "method", - "name": "error", - "desc": "

Same as console.log but prints to stderr.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.dir(obj)", - "type": "method", - "name": "dir", - "desc": "

Uses util.inspect on obj and prints resulting string to stderr.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "obj" - } - ] - } - ] - }, - { - "textRaw": "console.time(label)", - "type": "method", - "name": "time", - "desc": "

Mark a time.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "label" - } - ] - } - ] - }, - { - "textRaw": "console.timeEnd(label)", - "type": "method", - "name": "timeEnd", - "desc": "

Finish timer, record output. Example\n\n

\n
console.time('100-elements');\nfor (var i = 0; i < 100; i++) {\n  ;\n}\nconsole.timeEnd('100-elements');
\n", - "signatures": [ - { - "params": [ - { - "name": "label" - } - ] - } - ] - }, - { - "textRaw": "console.trace()", - "type": "method", - "name": "trace", - "desc": "

Print a stack trace to stderr of the current position.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.assert()", - "type": "method", - "name": "assert", - "desc": "

Same as assert.ok().\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - }, - { - "textRaw": "process", - "name": "process", - "type": "global", - "desc": "

The process object is a global object and can be accessed from anywhere.\nIt is an instance of EventEmitter.\n\n\n

\n", - "events": [ - { - "textRaw": "Event: 'exit'", - "type": "event", - "name": "exit", - "desc": "

Emitted when the process is about to exit. This is a good hook to perform\nconstant time checks of the module's state (like for unit tests). The main\nevent loop will no longer be run after the 'exit' callback finishes, so\ntimers may not be scheduled.\n\n

\n

Example of listening for exit:\n\n

\n
process.on('exit', function () {\n  process.nextTick(function () {\n   console.log('This will not run');\n  });\n  console.log('About to exit.');\n});
\n", - "params": [] - }, - { - "textRaw": "Event: 'uncaughtException'", - "type": "event", - "name": "uncaughtException", - "desc": "

Emitted when an exception bubbles all the way back to the event loop. If a\nlistener is added for this exception, the default action (which is to print\na stack trace and exit) will not occur.\n\n

\n

Example of listening for uncaughtException:\n\n

\n
process.on('uncaughtException', function (err) {\n  console.log('Caught exception: ' + err);\n});\n\nsetTimeout(function () {\n  console.log('This will still run.');\n}, 500);\n\n// Intentionally cause an exception, but don't catch it.\nnonexistentFunc();\nconsole.log('This will not run.');
\n

Note that uncaughtException is a very crude mechanism for exception\nhandling. Using try / catch in your program will give you more control over\nyour program's flow. Especially for server programs that are designed to\nstay running forever, uncaughtException can be a useful safety mechanism.\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Signal Events", - "name": "SIGINT, SIGUSR1, etc.", - "type": "event", - "desc": "

Emitted when the processes receives a signal. See sigaction(2) for a list of\nstandard POSIX signal names such as SIGINT, SIGUSR1, etc.\n\n

\n

Example of listening for SIGINT:\n\n

\n
// Start reading from stdin so we don't exit.\nprocess.stdin.resume();\n\nprocess.on('SIGINT', function () {\n  console.log('Got SIGINT.  Press Control-D to exit.');\n});
\n

An easy way to send the SIGINT signal is with Control-C in most terminal\nprograms.\n\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "process.stdout", - "name": "stdout", - "desc": "

A Writable Stream to stdout.\n\n

\n

Example: the definition of console.log\n\n

\n
console.log = function (d) {\n  process.stdout.write(d + '\\n');\n};
\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" - }, - { - "textRaw": "process.stderr", - "name": "stderr", - "desc": "

A writable stream to stderr.\n\n

\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" - }, - { - "textRaw": "process.stdin", - "name": "stdin", - "desc": "

A Readable Stream for stdin. The stdin stream is paused by default, so one\nmust call process.stdin.resume() to read from it.\n\n

\n

Example of opening standard input and listening for both events:\n\n

\n
process.stdin.resume();\nprocess.stdin.setEncoding('utf8');\n\nprocess.stdin.on('data', function (chunk) {\n  process.stdout.write('data: ' + chunk);\n});\n\nprocess.stdin.on('end', function () {\n  process.stdout.write('end');\n});
\n" - }, - { - "textRaw": "process.argv", - "name": "argv", - "desc": "

An array containing the command line arguments. The first element will be\n'node', the second element will be the name of the JavaScript file. The\nnext elements will be any additional command line arguments.\n\n

\n
// print process.argv\nprocess.argv.forEach(function (val, index, array) {\n  console.log(index + ': ' + val);\n});
\n

This will generate:\n\n

\n
$ node process-2.js one two=three four\n0: node\n1: /Users/mjr/work/node/process-2.js\n2: one\n3: two=three\n4: four
\n" - }, - { - "textRaw": "process.execPath", - "name": "execPath", - "desc": "

This is the absolute pathname of the executable that started the process.\n\n

\n

Example:\n\n

\n
/usr/local/bin/node
\n" - }, - { - "textRaw": "process.env", - "name": "env", - "desc": "

An object containing the user environment. See environ(7).\n\n\n

\n" - }, - { - "textRaw": "process.version", - "name": "version", - "desc": "

A compiled-in property that exposes NODE_VERSION.\n\n

\n
console.log('Version: ' + process.version);
\n" - }, - { - "textRaw": "process.versions", - "name": "versions", - "desc": "

A property exposing version strings of node and its dependencies.\n\n

\n
console.log(process.versions);
\n

Will output:\n\n

\n
{ node: '0.4.12',\n  v8: '3.1.8.26',\n  ares: '1.7.4',\n  ev: '4.4',\n  openssl: '1.0.0e-fips' }
\n" - }, - { - "textRaw": "process.installPrefix", - "name": "installPrefix", - "desc": "

A compiled-in property that exposes NODE_PREFIX.\n\n

\n
console.log('Prefix: ' + process.installPrefix);
\n" - }, - { - "textRaw": "process.pid", - "name": "pid", - "desc": "

The PID of the process.\n\n

\n
console.log('This process is pid ' + process.pid);
\n" - }, - { - "textRaw": "process.title", - "name": "title", - "desc": "

Getter/setter to set what is displayed in 'ps'.\n\n\n

\n" - }, - { - "textRaw": "process.arch", - "name": "arch", - "desc": "

What processor architecture you're running on: 'arm', 'ia32', or 'x64'.\n\n

\n
console.log('This processor architecture is ' + process.arch);
\n" - }, - { - "textRaw": "process.platform", - "name": "platform", - "desc": "

What platform you're running on. 'linux2', 'darwin', etc.\n\n

\n
console.log('This platform is ' + process.platform);
\n" - } - ], - "methods": [ - { - "textRaw": "process.chdir(directory)", - "type": "method", - "name": "chdir", - "desc": "

Changes the current working directory of the process or throws an exception if that fails.\n\n

\n
console.log('Starting directory: ' + process.cwd());\ntry {\n  process.chdir('/tmp');\n  console.log('New directory: ' + process.cwd());\n}\ncatch (err) {\n  console.log('chdir: ' + err);\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "directory" - } - ] - } - ] - }, - { - "textRaw": "process.cwd()", - "type": "method", - "name": "cwd", - "desc": "

Returns the current working directory of the process.\n\n

\n
console.log('Current directory: ' + process.cwd());
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.exit([code])", - "type": "method", - "name": "exit", - "desc": "

Ends the process with the specified code. If omitted, exit uses the\n'success' code 0.\n\n

\n

To exit with a 'failure' code:\n\n

\n
process.exit(1);
\n

The shell that executed node should see the exit code as 1.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "process.getgid()", - "type": "method", - "name": "getgid", - "desc": "

Gets the group identity of the process. (See getgid(2).)\nThis is the numerical group id, not the group name.\n\n

\n
console.log('Current gid: ' + process.getgid());
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.setgid(id)", - "type": "method", - "name": "setgid", - "desc": "

Sets the group identity of the process. (See setgid(2).) This accepts either\na numerical ID or a groupname string. If a groupname is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current gid: ' + process.getgid());\ntry {\n  process.setgid(501);\n  console.log('New gid: ' + process.getgid());\n}\ncatch (err) {\n  console.log('Failed to set gid: ' + err);\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "id" - } - ] - } - ] - }, - { - "textRaw": "process.getuid()", - "type": "method", - "name": "getuid", - "desc": "

Gets the user identity of the process. (See getuid(2).)\nThis is the numerical userid, not the username.\n\n

\n
console.log('Current uid: ' + process.getuid());
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.setuid(id)", - "type": "method", - "name": "setuid", - "desc": "

Sets the user identity of the process. (See setuid(2).) This accepts either\na numerical ID or a username string. If a username is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current uid: ' + process.getuid());\ntry {\n  process.setuid(501);\n  console.log('New uid: ' + process.getuid());\n}\ncatch (err) {\n  console.log('Failed to set uid: ' + err);\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "id" - } - ] - } - ] - }, - { - "textRaw": "process.kill(pid, [signal])", - "type": "method", - "name": "kill", - "desc": "

Send a signal to a process. pid is the process id and signal is the\nstring describing the signal to send. Signal names are strings like\n'SIGINT' or 'SIGUSR1'. If omitted, the signal will be 'SIGTERM'.\nSee kill(2) for more information.\n\n

\n

Note that just because the name of this function is process.kill, it is\nreally just a signal sender, like the kill system call. The signal sent\nmay do something other than kill the target process.\n\n

\n

Example of sending a signal to yourself:\n\n

\n
process.on('SIGHUP', function () {\n  console.log('Got SIGHUP signal.');\n});\n\nsetTimeout(function () {\n  console.log('Exiting.');\n  process.exit(0);\n}, 100);\n\nprocess.kill(process.pid, 'SIGHUP');
\n", - "signatures": [ - { - "params": [ - { - "name": "pid" - }, - { - "name": "signal", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "process.memoryUsage()", - "type": "method", - "name": "memoryUsage", - "desc": "

Returns an object describing the memory usage of the Node process\nmeasured in bytes.\n\n

\n
var util = require('util');\n\nconsole.log(util.inspect(process.memoryUsage()));
\n

This will generate:\n\n

\n
{ rss: 4935680,\n  heapTotal: 1826816,\n  heapUsed: 650472 }
\n

heapTotal and heapUsed refer to V8's memory usage.\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.nextTick(callback)", - "type": "method", - "name": "nextTick", - "desc": "

On the next loop around the event loop call this callback.\nThis is not a simple alias to setTimeout(fn, 0), it's much more\nefficient.\n\n

\n
process.nextTick(function () {\n  console.log('nextTick callback');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "process.umask([mask])", - "type": "method", - "name": "umask", - "desc": "

Sets or reads the process's file mode creation mask. Child processes inherit\nthe mask from the parent process. Returns the old mask if mask argument is\ngiven, otherwise returns the current mask.\n\n

\n
var oldmask, newmask = 0644;\n\noldmask = process.umask(newmask);\nconsole.log('Changed umask from: ' + oldmask.toString(8) +\n            ' to ' + newmask.toString(8));
\n", - "signatures": [ - { - "params": [ - { - "name": "mask", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "process.uptime()", - "type": "method", - "name": "uptime", - "desc": "

Number of seconds Node has been running.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - } - ], - "vars": [ - { - "textRaw": "require()", - "type": "var", - "name": "require", - "desc": "

To require modules. See the Modules section.\nrequire isn't actually a global but rather local to each module.\n\n\n

\n", - "methods": [ - { - "textRaw": "require.resolve()", - "type": "method", - "name": "resolve", - "desc": "

Use the internal require() machinery to look up the location of a module,\nbut rather than loading the module, just return the resolved filename.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "properties": [ - { - "textRaw": "`cache` {Object} ", - "name": "cache", - "desc": "

Modules are cached in this object when they are required. By deleting a key\nvalue from this object, the next require will reload the module.\n\n

\n" - } - ] - }, - { - "textRaw": "__filename", - "name": "__filename", - "type": "var", - "desc": "

The filename of the code being executed. This is the resolved absolute path\nof this code file. For a main program this is not necessarily the same\nfilename used in the command line. The value inside a module is the path\nto that module file.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__filename);\n// /Users/mjr/example.js
\n

__filename isn't actually a global but rather local to each module.\n\n

\n" - }, - { - "textRaw": "__dirname", - "name": "__dirname", - "type": "var", - "desc": "

The name of the directory that the currently executing script resides in.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__dirname);\n// /Users/mjr
\n

__dirname isn't actually a global but rather local to each module.\n\n\n

\n" - }, - { - "textRaw": "module", - "name": "module", - "type": "var", - "desc": "

A reference to the current module. In particular\nmodule.exports is the same as the exports object. See src/node.js\nfor more information.\nmodule isn't actually a global but rather local to each module.\n\n\n

\n" - }, - { - "textRaw": "exports", - "name": "exports", - "type": "var", - "desc": "

An object which is shared between all instances of the current module and\nmade accessible through require().\nexports is the same as the module.exports object. See src/node.js\nfor more information.\nexports isn't actually a global but rather local to each module.\n\n

\n

See the module system documentation for more\ninformation.\n\n

\n

See the module section for more information.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "setInterval(cb, ms)", - "type": "method", - "name": "setInterval", - "desc": "

The timer functions are global variables. See the timers section.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "cb" - }, - { - "name": "ms" - } - ] - } - ] - } - ] - }, - { - "textRaw": "Debugger", - "name": "Debugger", - "stability": 3, - "stabilityText": "Stable", - "type": "misc", - "desc": "

V8 comes with an extensive debugger which is accessible out-of-process via a\nsimple TCP protocol.\nNode has a built-in client for this debugger. To use this, start Node with the\ndebug argument; a prompt will appear:\n\n

\n
% node debug myscript.js\n< debugger listening on port 5858\nconnecting... ok\nbreak in /home/indutny/Code/git/indutny/myscript.js:1\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\ndebug>
\n

Node's debugger client doesn't support the full range of commands, but\nsimple step and inspection is possible. By putting the statement debugger;\ninto the source code of your script, you will enable a breakpoint.\n\n

\n

For example, suppose myscript.js looked like this:\n\n

\n
// myscript.js\nx = 5;\nsetTimeout(function () {\n  debugger;\n  console.log("world");\n}, 1000);\nconsole.log("hello");
\n

Then once the debugger is run, it will break on line 4.\n\n

\n
% node debug myscript.js\n< debugger listening on port 5858\nconnecting... ok\nbreak in /home/indutny/Code/git/indutny/myscript.js:1\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\ndebug> cont\n< hello\nbreak in /home/indutny/Code/git/indutny/myscript.js:3\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\ndebug> next\nbreak in /home/indutny/Code/git/indutny/myscript.js:4\n  2 setTimeout(function () {\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\n  6 console.log("hello");\ndebug> repl\nPress Ctrl + C to leave debug repl\n> x\n5\n> 2+2\n4\ndebug> next\n< world\nbreak in /home/indutny/Code/git/indutny/myscript.js:5\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\n  6 console.log("hello");\n  7\ndebug> quit\n%
\n

The repl command allows you to evaluate code remotely. The next command\nsteps over to the next line. There are a few other commands available and more\nto come. Type help to see others.\n\n

\n", - "miscs": [ - { - "textRaw": "Watchers", - "name": "watchers", - "desc": "

You can watch expression and variable values while debugging your code.\nOn every breakpoint each expression from the watchers list will be evaluated\nin the current context and displayed just before the breakpoint's source code\nlisting.\n\n

\n

To start watching an expression, type watch("my_expression"). watchers\nprints the active watchers. To remove a watcher, type\nunwatch("my_expression").\n\n

\n", - "type": "misc", - "displayName": "Watchers" - }, - { - "textRaw": "Commands reference", - "name": "commands_reference", - "modules": [ - { - "textRaw": "Execution control", - "name": "Execution control", - "type": "module", - "displayName": "Various" - }, - { - "textRaw": "Various", - "name": "various", - "type": "module", - "displayName": "Various" - } - ], - "type": "misc", - "displayName": "Commands reference" - }, - { - "textRaw": "Advanced Usage", - "name": "advanced_usage", - "desc": "

The V8 debugger can be enabled and accessed either by starting Node with\nthe --debug command-line flag or by signaling an existing Node process\nwith SIGUSR1.\n\n

\n", - "type": "misc", - "displayName": "Advanced Usage" - } - ] - } - ], - "globals": [ - { - "textRaw": "global", - "name": "global", - "type": "global", - "desc": "

In browsers, the top-level scope is the global scope. That means that in\nbrowsers if you're in the global scope var something will define a global\nvariable. In Node this is different. The top-level scope is not the global\nscope; var something inside a Node module will be local to that module.\n\n

\n" - }, - { - "textRaw": "process", - "name": "process", - "type": "global", - "desc": "

The process object. See the process object section.\n\n

\n" - }, - { - "textRaw": "console", - "name": "console", - "type": "global", - "desc": "

Used to print to stdout and stderr. See the stdio section.\n\n

\n" - }, - { - "textRaw": "Buffer", - "name": "Buffer", - "type": "global", - "desc": "

Used to handle binary data. See the buffer section.\n\n

\n" - }, - { - "textRaw": "clearInterval(t)", - "type": "global", - "name": "clearInterval", - "desc": "

The timer functions are global variables. See the timers section.\n\n

\n" - }, - { - "textRaw": "console", - "name": "console", - "stability": 4, - "stabilityText": "API Frozen", - "type": "global", - "desc": "

For printing to stdout and stderr. Similar to the console object functions\nprovided by most web browsers, here the output is sent to stdout or stderr.\n\n\n

\n", - "methods": [ - { - "textRaw": "console.log()", - "type": "method", - "name": "log", - "desc": "

Prints to stdout with newline. This function can take multiple arguments in a\nprintf()-like way. Example:\n\n

\n
console.log('count: %d', count);
\n

If formatting elements are not found in the first string then util.inspect\nis used on each argument.\nSee util.format() for more information.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.info()", - "type": "method", - "name": "info", - "desc": "

Same as console.log.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.warn()", - "type": "method", - "name": "warn", - "desc": "

Same as console.log but prints to stderr.\n\n

\n", - "signatures": [ - { - "params": [] - }, - { - "params": [] - } - ] - }, - { - "textRaw": "console.error()", - "type": "method", - "name": "error", - "desc": "

Same as console.log but prints to stderr.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.dir(obj)", - "type": "method", - "name": "dir", - "desc": "

Uses util.inspect on obj and prints resulting string to stderr.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "obj" - } - ] - } - ] - }, - { - "textRaw": "console.time(label)", - "type": "method", - "name": "time", - "desc": "

Mark a time.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "label" - } - ] - } - ] - }, - { - "textRaw": "console.timeEnd(label)", - "type": "method", - "name": "timeEnd", - "desc": "

Finish timer, record output. Example\n\n

\n
console.time('100-elements');\nfor (var i = 0; i < 100; i++) {\n  ;\n}\nconsole.timeEnd('100-elements');
\n", - "signatures": [ - { - "params": [ - { - "name": "label" - } - ] - } - ] - }, - { - "textRaw": "console.trace()", - "type": "method", - "name": "trace", - "desc": "

Print a stack trace to stderr of the current position.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.assert()", - "type": "method", - "name": "assert", - "desc": "

Same as assert.ok().\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - }, - { - "textRaw": "process", - "name": "process", - "type": "global", - "desc": "

The process object is a global object and can be accessed from anywhere.\nIt is an instance of EventEmitter.\n\n\n

\n", - "events": [ - { - "textRaw": "Event: 'exit'", - "type": "event", - "name": "exit", - "desc": "

Emitted when the process is about to exit. This is a good hook to perform\nconstant time checks of the module's state (like for unit tests). The main\nevent loop will no longer be run after the 'exit' callback finishes, so\ntimers may not be scheduled.\n\n

\n

Example of listening for exit:\n\n

\n
process.on('exit', function () {\n  process.nextTick(function () {\n   console.log('This will not run');\n  });\n  console.log('About to exit.');\n});
\n", - "params": [] - }, - { - "textRaw": "Event: 'uncaughtException'", - "type": "event", - "name": "uncaughtException", - "desc": "

Emitted when an exception bubbles all the way back to the event loop. If a\nlistener is added for this exception, the default action (which is to print\na stack trace and exit) will not occur.\n\n

\n

Example of listening for uncaughtException:\n\n

\n
process.on('uncaughtException', function (err) {\n  console.log('Caught exception: ' + err);\n});\n\nsetTimeout(function () {\n  console.log('This will still run.');\n}, 500);\n\n// Intentionally cause an exception, but don't catch it.\nnonexistentFunc();\nconsole.log('This will not run.');
\n

Note that uncaughtException is a very crude mechanism for exception\nhandling. Using try / catch in your program will give you more control over\nyour program's flow. Especially for server programs that are designed to\nstay running forever, uncaughtException can be a useful safety mechanism.\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Signal Events", - "name": "SIGINT, SIGUSR1, etc.", - "type": "event", - "desc": "

Emitted when the processes receives a signal. See sigaction(2) for a list of\nstandard POSIX signal names such as SIGINT, SIGUSR1, etc.\n\n

\n

Example of listening for SIGINT:\n\n

\n
// Start reading from stdin so we don't exit.\nprocess.stdin.resume();\n\nprocess.on('SIGINT', function () {\n  console.log('Got SIGINT.  Press Control-D to exit.');\n});
\n

An easy way to send the SIGINT signal is with Control-C in most terminal\nprograms.\n\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "process.stdout", - "name": "stdout", - "desc": "

A Writable Stream to stdout.\n\n

\n

Example: the definition of console.log\n\n

\n
console.log = function (d) {\n  process.stdout.write(d + '\\n');\n};
\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" - }, - { - "textRaw": "process.stderr", - "name": "stderr", - "desc": "

A writable stream to stderr.\n\n

\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" - }, - { - "textRaw": "process.stdin", - "name": "stdin", - "desc": "

A Readable Stream for stdin. The stdin stream is paused by default, so one\nmust call process.stdin.resume() to read from it.\n\n

\n

Example of opening standard input and listening for both events:\n\n

\n
process.stdin.resume();\nprocess.stdin.setEncoding('utf8');\n\nprocess.stdin.on('data', function (chunk) {\n  process.stdout.write('data: ' + chunk);\n});\n\nprocess.stdin.on('end', function () {\n  process.stdout.write('end');\n});
\n" - }, - { - "textRaw": "process.argv", - "name": "argv", - "desc": "

An array containing the command line arguments. The first element will be\n'node', the second element will be the name of the JavaScript file. The\nnext elements will be any additional command line arguments.\n\n

\n
// print process.argv\nprocess.argv.forEach(function (val, index, array) {\n  console.log(index + ': ' + val);\n});
\n

This will generate:\n\n

\n
$ node process-2.js one two=three four\n0: node\n1: /Users/mjr/work/node/process-2.js\n2: one\n3: two=three\n4: four
\n" - }, - { - "textRaw": "process.execPath", - "name": "execPath", - "desc": "

This is the absolute pathname of the executable that started the process.\n\n

\n

Example:\n\n

\n
/usr/local/bin/node
\n" - }, - { - "textRaw": "process.env", - "name": "env", - "desc": "

An object containing the user environment. See environ(7).\n\n\n

\n" - }, - { - "textRaw": "process.version", - "name": "version", - "desc": "

A compiled-in property that exposes NODE_VERSION.\n\n

\n
console.log('Version: ' + process.version);
\n" - }, - { - "textRaw": "process.versions", - "name": "versions", - "desc": "

A property exposing version strings of node and its dependencies.\n\n

\n
console.log(process.versions);
\n

Will output:\n\n

\n
{ node: '0.4.12',\n  v8: '3.1.8.26',\n  ares: '1.7.4',\n  ev: '4.4',\n  openssl: '1.0.0e-fips' }
\n" - }, - { - "textRaw": "process.installPrefix", - "name": "installPrefix", - "desc": "

A compiled-in property that exposes NODE_PREFIX.\n\n

\n
console.log('Prefix: ' + process.installPrefix);
\n" - }, - { - "textRaw": "process.pid", - "name": "pid", - "desc": "

The PID of the process.\n\n

\n
console.log('This process is pid ' + process.pid);
\n" - }, - { - "textRaw": "process.title", - "name": "title", - "desc": "

Getter/setter to set what is displayed in 'ps'.\n\n\n

\n" - }, - { - "textRaw": "process.arch", - "name": "arch", - "desc": "

What processor architecture you're running on: 'arm', 'ia32', or 'x64'.\n\n

\n
console.log('This processor architecture is ' + process.arch);
\n" - }, - { - "textRaw": "process.platform", - "name": "platform", - "desc": "

What platform you're running on. 'linux2', 'darwin', etc.\n\n

\n
console.log('This platform is ' + process.platform);
\n" - } - ], - "methods": [ - { - "textRaw": "process.chdir(directory)", - "type": "method", - "name": "chdir", - "desc": "

Changes the current working directory of the process or throws an exception if that fails.\n\n

\n
console.log('Starting directory: ' + process.cwd());\ntry {\n  process.chdir('/tmp');\n  console.log('New directory: ' + process.cwd());\n}\ncatch (err) {\n  console.log('chdir: ' + err);\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "directory" - } - ] - } - ] - }, - { - "textRaw": "process.cwd()", - "type": "method", - "name": "cwd", - "desc": "

Returns the current working directory of the process.\n\n

\n
console.log('Current directory: ' + process.cwd());
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.exit([code])", - "type": "method", - "name": "exit", - "desc": "

Ends the process with the specified code. If omitted, exit uses the\n'success' code 0.\n\n

\n

To exit with a 'failure' code:\n\n

\n
process.exit(1);
\n

The shell that executed node should see the exit code as 1.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "process.getgid()", - "type": "method", - "name": "getgid", - "desc": "

Gets the group identity of the process. (See getgid(2).)\nThis is the numerical group id, not the group name.\n\n

\n
console.log('Current gid: ' + process.getgid());
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.setgid(id)", - "type": "method", - "name": "setgid", - "desc": "

Sets the group identity of the process. (See setgid(2).) This accepts either\na numerical ID or a groupname string. If a groupname is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current gid: ' + process.getgid());\ntry {\n  process.setgid(501);\n  console.log('New gid: ' + process.getgid());\n}\ncatch (err) {\n  console.log('Failed to set gid: ' + err);\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "id" - } - ] - } - ] - }, - { - "textRaw": "process.getuid()", - "type": "method", - "name": "getuid", - "desc": "

Gets the user identity of the process. (See getuid(2).)\nThis is the numerical userid, not the username.\n\n

\n
console.log('Current uid: ' + process.getuid());
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.setuid(id)", - "type": "method", - "name": "setuid", - "desc": "

Sets the user identity of the process. (See setuid(2).) This accepts either\na numerical ID or a username string. If a username is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current uid: ' + process.getuid());\ntry {\n  process.setuid(501);\n  console.log('New uid: ' + process.getuid());\n}\ncatch (err) {\n  console.log('Failed to set uid: ' + err);\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "id" - } - ] - } - ] - }, - { - "textRaw": "process.kill(pid, [signal])", - "type": "method", - "name": "kill", - "desc": "

Send a signal to a process. pid is the process id and signal is the\nstring describing the signal to send. Signal names are strings like\n'SIGINT' or 'SIGUSR1'. If omitted, the signal will be 'SIGTERM'.\nSee kill(2) for more information.\n\n

\n

Note that just because the name of this function is process.kill, it is\nreally just a signal sender, like the kill system call. The signal sent\nmay do something other than kill the target process.\n\n

\n

Example of sending a signal to yourself:\n\n

\n
process.on('SIGHUP', function () {\n  console.log('Got SIGHUP signal.');\n});\n\nsetTimeout(function () {\n  console.log('Exiting.');\n  process.exit(0);\n}, 100);\n\nprocess.kill(process.pid, 'SIGHUP');
\n", - "signatures": [ - { - "params": [ - { - "name": "pid" - }, - { - "name": "signal", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "process.memoryUsage()", - "type": "method", - "name": "memoryUsage", - "desc": "

Returns an object describing the memory usage of the Node process\nmeasured in bytes.\n\n

\n
var util = require('util');\n\nconsole.log(util.inspect(process.memoryUsage()));
\n

This will generate:\n\n

\n
{ rss: 4935680,\n  heapTotal: 1826816,\n  heapUsed: 650472 }
\n

heapTotal and heapUsed refer to V8's memory usage.\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.nextTick(callback)", - "type": "method", - "name": "nextTick", - "desc": "

On the next loop around the event loop call this callback.\nThis is not a simple alias to setTimeout(fn, 0), it's much more\nefficient.\n\n

\n
process.nextTick(function () {\n  console.log('nextTick callback');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "process.umask([mask])", - "type": "method", - "name": "umask", - "desc": "

Sets or reads the process's file mode creation mask. Child processes inherit\nthe mask from the parent process. Returns the old mask if mask argument is\ngiven, otherwise returns the current mask.\n\n

\n
var oldmask, newmask = 0644;\n\noldmask = process.umask(newmask);\nconsole.log('Changed umask from: ' + oldmask.toString(8) +\n            ' to ' + newmask.toString(8));
\n", - "signatures": [ - { - "params": [ - { - "name": "mask", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "process.uptime()", - "type": "method", - "name": "uptime", - "desc": "

Number of seconds Node has been running.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - } - ], - "vars": [ - { - "textRaw": "require()", - "type": "var", - "name": "require", - "desc": "

To require modules. See the Modules section.\nrequire isn't actually a global but rather local to each module.\n\n\n

\n", - "methods": [ - { - "textRaw": "require.resolve()", - "type": "method", - "name": "resolve", - "desc": "

Use the internal require() machinery to look up the location of a module,\nbut rather than loading the module, just return the resolved filename.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "properties": [ - { - "textRaw": "`cache` {Object} ", - "name": "cache", - "desc": "

Modules are cached in this object when they are required. By deleting a key\nvalue from this object, the next require will reload the module.\n\n

\n" - } - ] - }, - { - "textRaw": "__filename", - "name": "__filename", - "type": "var", - "desc": "

The filename of the code being executed. This is the resolved absolute path\nof this code file. For a main program this is not necessarily the same\nfilename used in the command line. The value inside a module is the path\nto that module file.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__filename);\n// /Users/mjr/example.js
\n

__filename isn't actually a global but rather local to each module.\n\n

\n" - }, - { - "textRaw": "__dirname", - "name": "__dirname", - "type": "var", - "desc": "

The name of the directory that the currently executing script resides in.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__dirname);\n// /Users/mjr
\n

__dirname isn't actually a global but rather local to each module.\n\n\n

\n" - }, - { - "textRaw": "module", - "name": "module", - "type": "var", - "desc": "

A reference to the current module. In particular\nmodule.exports is the same as the exports object. See src/node.js\nfor more information.\nmodule isn't actually a global but rather local to each module.\n\n\n

\n" - }, - { - "textRaw": "exports", - "name": "exports", - "type": "var", - "desc": "

An object which is shared between all instances of the current module and\nmade accessible through require().\nexports is the same as the module.exports object. See src/node.js\nfor more information.\nexports isn't actually a global but rather local to each module.\n\n

\n

See the module system documentation for more\ninformation.\n\n

\n

See the module section for more information.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "setInterval(cb, ms)", - "type": "method", - "name": "setInterval", - "desc": "

The timer functions are global variables. See the timers section.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "cb" - }, - { - "name": "ms" - } - ] - } - ] - } - ], - "modules": [ - { - "textRaw": "Timers", - "name": "timers", - "stability": 5, - "stabilityText": "Locked", - "desc": "

All of the timer functions are globals. You do not need to require()\nthis module in order to use them.\n\n

\n", - "methods": [ - { - "textRaw": "setTimeout(callback, delay, [arg], [...])", - "type": "method", - "name": "setTimeout", - "desc": "

To schedule execution of a one-time callback after delay milliseconds. Returns a\ntimeoutId for possible use with clearTimeout(). Optionally you can\nalso pass arguments to the callback.\n\n

\n

It is important to note that your callback will probably not be called in exactly\ndelay milliseconds - Node.js makes no guarantees about the exact timing of when\nthe callback will fire, nor of the ordering things will fire in. The callback will\nbe called as close as possible to the time specified.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "callback" - }, - { - "name": "delay" - }, - { - "name": "arg", - "optional": true - }, - { - "name": "...", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "clearTimeout(timeoutId)", - "type": "method", - "name": "clearTimeout", - "desc": "

Prevents a timeout from triggering.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "timeoutId" - } - ] - } - ] - }, - { - "textRaw": "setInterval(callback, delay, [arg], [...])", - "type": "method", - "name": "setInterval", - "desc": "

To schedule the repeated execution of callback every delay milliseconds.\nReturns a intervalId for possible use with clearInterval(). Optionally\nyou can also pass arguments to the callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "callback" - }, - { - "name": "delay" - }, - { - "name": "arg", - "optional": true - }, - { - "name": "...", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "clearInterval(intervalId)", - "type": "method", - "name": "clearInterval", - "desc": "

Stops a interval from triggering.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "intervalId" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "Timers" - }, - { - "textRaw": "Modules", - "name": "module", - "stability": 5, - "stabilityText": "Locked", - "desc": "

Node has a simple module loading system. In Node, files and modules are in\none-to-one correspondence. As an example, foo.js loads the module\ncircle.js in the same directory.\n\n

\n

The contents of foo.js:\n\n

\n
var circle = require('./circle.js');\nconsole.log( 'The area of a circle of radius 4 is '\n           + circle.area(4));
\n

The contents of circle.js:\n\n

\n
var PI = Math.PI;\n\nexports.area = function (r) {\n  return PI * r * r;\n};\n\nexports.circumference = function (r) {\n  return 2 * PI * r;\n};
\n

The module circle.js has exported the functions area() and\ncircumference(). To export an object, add to the special exports\nobject.\n\n

\n

Variables\nlocal to the module will be private. In this example the variable PI is\nprivate to circle.js.\n\n

\n

The module system is implemented in the require("module") module.\n\n

\n", - "miscs": [ - { - "textRaw": "Cycles", - "name": "Cycles", - "type": "misc", - "desc": "

When there are circular require() calls, a module might not be\ndone being executed when it is returned.\n\n

\n

Consider this situation:\n\n

\n

a.js:\n\n

\n
console.log('a starting');\nexports.done = false;\nvar b = require('./b.js');\nconsole.log('in a, b.done = %j', b.done);\nexports.done = true;\nconsole.log('a done');
\n

b.js:\n\n

\n
console.log('b starting');\nexports.done = false;\nvar a = require('./a.js');\nconsole.log('in b, a.done = %j', a.done);\nexports.done = true;\nconsole.log('b done');
\n

main.js:\n\n

\n
console.log('main starting');\nvar a = require('./a.js');\nvar b = require('./b.js');\nconsole.log('in main, a.done=%j, b.done=%j', a.done, b.done);
\n

When main.js loads a.js, then a.js in turn loads b.js. At that\npoint, b.js tries to load a.js. In order to prevent an infinite\nloop an unfinished copy of the a.js exports object is returned to the\nb.js module. b.js then finishes loading, and its exports object is\nprovided to the a.js module.\n\n

\n

By the time main.js has loaded both modules, they're both finished.\nThe output of this program would thus be:\n\n

\n
$ node main.js\nmain starting\na starting\nb starting\nin b, a.done = false\nb done\nin a, b.done = true\na done\nin main, a.done=true, b.done=true
\n

If you have cyclic module dependencies in your program, make sure to\nplan accordingly.\n\n

\n" - }, - { - "textRaw": "Core Modules", - "name": "Core Modules", - "type": "misc", - "desc": "

Node has several modules compiled into the binary. These modules are\ndescribed in greater detail elsewhere in this documentation.\n\n

\n

The core modules are defined in node's source in the lib/ folder.\n\n

\n

Core modules are always preferentially loaded if their identifier is\npassed to require(). For instance, require('http') will always\nreturn the built in HTTP module, even if there is a file by that name.\n\n

\n" - }, - { - "textRaw": "File Modules", - "name": "File Modules", - "type": "misc", - "desc": "

If the exact filename is not found, then node will attempt to load the\nrequired filename with the added extension of .js, .json, and then .node.\n\n

\n

.js files are interpreted as JavaScript text files, and .json files are\nparsed as JSON text files. .node files are interpreted as compiled addon\nmodules loaded with dlopen.\n\n

\n

A module prefixed with '/' is an absolute path to the file. For\nexample, require('/home/marco/foo.js') will load the file at\n/home/marco/foo.js.\n\n

\n

A module prefixed with './' is relative to the file calling require().\nThat is, circle.js must be in the same directory as foo.js for\nrequire('./circle') to find it.\n\n

\n

Without a leading '/' or './' to indicate a file, the module is either a\n"core module" or is loaded from a node_modules folder.\n\n

\n" - }, - { - "textRaw": "Loading from `node_modules` Folders", - "name": "Loading from `node_modules` Folders", - "type": "misc", - "desc": "

If the module identifier passed to require() is not a native module,\nand does not begin with '/', '../', or './', then node starts at the\nparent directory of the current module, and adds /node_modules, and\nattempts to load the module from that location.\n\n

\n

If it is not found there, then it moves to the parent directory, and so\non, until the root of the tree is reached.\n\n

\n

For example, if the file at '/home/ry/projects/foo.js' called\nrequire('bar.js'), then node would look in the following locations, in\nthis order:\n\n

\n
    \n
  • /home/ry/projects/node_modules/bar.js
    • \n
  • /home/ry/node_modules/bar.js
    • \n
  • /home/node_modules/bar.js
    • \n
  • /node_modules/bar.js
    • \n
\n

This allows programs to localize their dependencies, so that they do not\nclash.\n\n

\n" - }, - { - "textRaw": "Folders as Modules", - "name": "Folders as Modules", - "type": "misc", - "desc": "

It is convenient to organize programs and libraries into self-contained\ndirectories, and then provide a single entry point to that library.\nThere are three ways in which a folder may be passed to require() as\nan argument.\n\n

\n

The first is to create a package.json file in the root of the folder,\nwhich specifies a main module. An example package.json file might\nlook like this:\n\n

\n
{ "name" : "some-library",\n  "main" : "./lib/some-library.js" }
\n

If this was in a folder at ./some-library, then\nrequire('./some-library') would attempt to load\n./some-library/lib/some-library.js.\n\n

\n

This is the extent of Node's awareness of package.json files.\n\n

\n

If there is no package.json file present in the directory, then node\nwill attempt to load an index.js or index.node file out of that\ndirectory. For example, if there was no package.json file in the above\nexample, then require('./some-library') would attempt to load:\n\n

\n
    \n
  • ./some-library/index.js
    • \n
  • ./some-library/index.node
    • \n
\n" - }, - { - "textRaw": "Caching", - "name": "Caching", - "type": "misc", - "desc": "

Modules are cached after the first time they are loaded. This means\n(among other things) that every call to require('foo') will get\nexactly the same object returned, if it would resolve to the same file.\n\n

\n

Multiple calls to require('foo') may not cause the module code to be\nexecuted multiple times. This is an important feature. With it,\n"partially done" objects can be returned, thus allowing transitive\ndependencies to be loaded even when they would cause cycles.\n\n

\n

If you want to have a module execute code multiple times, then export a\nfunction, and call that function.\n\n

\n", - "miscs": [ - { - "textRaw": "Module Caching Caveats", - "name": "Module Caching Caveats", - "type": "misc", - "desc": "

Modules are cached based on their resolved filename. Since modules may\nresolve to a different filename based on the location of the calling\nmodule (loading from node_modules folders), it is not a guarantee\nthat require('foo') will always return the exact same object, if it\nwould resolve to different files.\n\n

\n" - } - ] - }, - { - "textRaw": "All Together...", - "name": "All Together...", - "type": "misc", - "desc": "

To get the exact filename that will be loaded when require() is called, use\nthe require.resolve() function.\n\n

\n

Putting together all of the above, here is the high-level algorithm\nin pseudocode of what require.resolve does:\n\n

\n
require(X) from module at path Y\n1. If X is a core module,\n   a. return the core module\n   b. STOP\n2. If X begins with './' or '/' or '../'\n   a. LOAD_AS_FILE(Y + X)\n   b. LOAD_AS_DIRECTORY(Y + X)\n3. LOAD_NODE_MODULES(X, dirname(Y))\n4. THROW "not found"\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as JavaScript text.  STOP\n2. If X.js is a file, load X.js as JavaScript text.  STOP\n3. If X.node is a file, load X.node as binary addon.  STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n   a. Parse X/package.json, and look for "main" field.\n   b. let M = X + (json main field)\n   c. LOAD_AS_FILE(M)\n2. If X/index.js is a file, load X/index.js as JavaScript text.  STOP\n3. If X/index.node is a file, load X/index.node as binary addon.  STOP\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS=NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n   a. LOAD_AS_FILE(DIR/X)\n   b. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let ROOT = index of first instance of "node_modules" in PARTS, or 0\n3. let I = count of PARTS - 1\n4. let DIRS = []\n5. while I > ROOT,\n   a. if PARTS[I] = "node_modules" CONTINUE\n   c. DIR = path join(PARTS[0 .. I] + "node_modules")\n   b. DIRS = DIRS + DIR\n   c. let I = I - 1\n6. return DIRS
\n" - }, - { - "textRaw": "Loading from the global folders", - "name": "Loading from the global folders", - "type": "misc", - "desc": "

If the NODE_PATH environment variable is set to a colon-delimited list\nof absolute paths, then node will search those paths for modules if they\nare not found elsewhere. (Note: On Windows, NODE_PATH is delimited by\nsemicolons instead of colons.)\n\n

\n

Additionally, node will search in the following locations:\n\n

\n
    \n
  • 1: $HOME/.node_modules
    • \n
  • 2: $HOME/.node_libraries
    • \n
  • 3: $PREFIX/lib/node
    • \n
\n

Where $HOME is the user's home directory, and $PREFIX is node's\nconfigured installPrefix.\n\n

\n

These are mostly for historic reasons. You are highly encouraged to\nplace your dependencies locally in node_modules folders. They will be\nloaded faster, and more reliably.\n\n

\n" - }, - { - "textRaw": "Accessing the main module", - "name": "Accessing the main module", - "type": "misc", - "desc": "

When a file is run directly from Node, require.main is set to its\nmodule. That means that you can determine whether a file has been run\ndirectly by testing\n\n

\n
require.main === module
\n

For a file foo.js, this will be true if run via node foo.js, but\nfalse if run by require('./foo').\n\n

\n

Because module provides a filename property (normally equivalent to\n__filename), the entry point of the current application can be obtained\nby checking require.main.filename.\n\n

\n" - }, - { - "textRaw": "Addenda: Package Manager Tips", - "name": "Addenda: Package Manager Tips", - "type": "misc", - "desc": "

The semantics of Node's require() function were designed to be general\nenough to support a number of sane directory structures. Package manager\nprograms such as dpkg, rpm, and npm will hopefully find it possible to\nbuild native packages from Node modules without modification.\n\n

\n

Below we give a suggested directory structure that could work:\n\n

\n

Let's say that we wanted to have the folder at\n/usr/lib/node/<some-package>/<some-version> hold the contents of a\nspecific version of a package.\n\n

\n

Packages can depend on one another. In order to install package foo, you\nmay have to install a specific version of package bar. The bar package\nmay itself have dependencies, and in some cases, these dependencies may even\ncollide or form cycles.\n\n

\n

Since Node looks up the realpath of any modules it loads (that is,\nresolves symlinks), and then looks for their dependencies in the\nnode_modules folders as described above, this situation is very simple to\nresolve with the following architecture:\n\n

\n
    \n
  • /usr/lib/node/foo/1.2.3/ - Contents of the foo package, version 1.2.3.
    • \n
  • /usr/lib/node/bar/4.3.2/ - Contents of the bar package that foo\ndepends on.
    • \n
  • /usr/lib/node/foo/1.2.3/node_modules/bar - Symbolic link to\n/usr/lib/node/bar/4.3.2/.
    • \n
  • /usr/lib/node/bar/4.3.2/node_modules/* - Symbolic links to the packages\nthat bar depends on.
    • \n
\n

Thus, even if a cycle is encountered, or if there are dependency\nconflicts, every module will be able to get a version of its dependency\nthat it can use.\n\n

\n

When the code in the foo package does require('bar'), it will get the\nversion that is symlinked into /usr/lib/node/foo/1.2.3/node_modules/bar.\nThen, when the code in the bar package calls require('quux'), it'll get\nthe version that is symlinked into\n/usr/lib/node/bar/4.3.2/node_modules/quux.\n\n

\n

Furthermore, to make the module lookup process even more optimal, rather\nthan putting packages directly in /usr/lib/node, we could put them in\n/usr/lib/node_modules/<name>/<version>. Then node will not bother\nlooking for missing dependencies in /usr/node_modules or /node_modules.\n\n

\n

In order to make modules available to the node REPL, it might be useful to\nalso add the /usr/lib/node_modules folder to the $NODE_PATH environment\nvariable. Since the module lookups using node_modules folders are all\nrelative, and based on the real path of the files making the calls to\nrequire(), the packages themselves can be anywhere.\n\n

\n" - } - ], - "vars": [ - { - "textRaw": "The `module` Object", - "name": "module", - "type": "var", - "desc": "

In each module, the module free variable is a reference to the object\nrepresenting the current module. In particular\nmodule.exports is the same as the exports object.\nmodule isn't actually a global but rather local to each module.\n\n

\n", - "properties": [ - { - "textRaw": "`exports` {Object} ", - "name": "exports", - "desc": "

The exports object is created by the Module system. Sometimes this is not\nacceptable, many want their module to be an instance of some class. To do this\nassign the desired export object to module.exports. For example suppose we\nwere making a module called a.js\n\n

\n
var EventEmitter = require('events').EventEmitter;\n\nmodule.exports = new EventEmitter();\n\n// Do some work, and after some time emit\n// the 'ready' event from the module itself.\nsetTimeout(function() {\n  module.exports.emit('ready');\n}, 1000);
\n

Then in another file we could do\n\n

\n
var a = require('./a');\na.on('ready', function() {\n  console.log('module a is ready');\n});
\n

Note that assignment to module.exports must be done immediately. It cannot be\ndone in any callbacks. This does not work:\n\n

\n

x.js:\n\n

\n
setTimeout(function() {\n  module.exports = { a: "hello" };\n}, 0);
\n

y.js:\n\n

\n
var x = require('./x');\nconsole.log(x.a);
\n" - }, - { - "textRaw": "`id` {String} ", - "name": "id", - "desc": "

The identifier for the module. Typically this is the fully resolved\nfilename.\n\n\n

\n" - }, - { - "textRaw": "`filename` {String} ", - "name": "filename", - "desc": "

The fully resolved filename to the module.\n\n\n

\n" - }, - { - "textRaw": "`loaded` {Boolean} ", - "name": "loaded", - "desc": "

Whether or not the module is done loading, or is in the process of\nloading.\n\n\n

\n" - }, - { - "textRaw": "`parent` {Module Object} ", - "name": "parent", - "desc": "

The module that required this one.\n\n\n

\n" - }, - { - "textRaw": "`children` {Array} ", - "name": "children", - "desc": "

The module objects required by this one.\n\n\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "module.require(id)", - "type": "method", - "name": "require", - "signatures": [ - { - "return": { - "textRaw": "Return: {Object} `exports` from the resolved module ", - "name": "return", - "type": "Object", - "desc": "`exports` from the resolved module" - }, - "params": [ - { - "textRaw": "`id` {String} ", - "name": "id", - "type": "String" - } - ] - }, - { - "params": [ - { - "name": "id" - } - ] - } - ], - "desc": "

The module.require method provides a way to load a module as if\nrequire() was called from the original module.\n\n

\n

Note that in order to do this, you must get a reference to the module\nobject. Since require() returns the exports, and the module is\ntypically only available within a specific module's code, it must be\nexplicitly exported in order to be used.\n\n\n

\n" - } - ] - } - ], - "type": "module", - "displayName": "module" - }, - { - "textRaw": "Addons", - "name": "addons", - "desc": "

Addons are dynamically linked shared objects. They can provide glue to C and\nC++ libraries. The API (at the moment) is rather complex, involving\nknowledge of several libraries:\n\n

\n
    \n

  • V8 JavaScript, a C++ library. Used for interfacing with JavaScript:\ncreating objects, calling functions, etc. Documented mostly in the\nv8.h header file (deps/v8/include/v8.h in the Node source tree),\nwhich is also available online.

    \n
    • \n

  • libuv, C event loop library. Anytime one\nneeds to wait for a file descriptor to become readable, wait for a timer, or\nwait for a signal to received one will need to interface with libuv. That is,\nif you perform any I/O, libuv will need to be used.

    \n
    • \n

  • Internal Node libraries. Most importantly is the node::ObjectWrap\nclass which you will likely want to derive from.

    \n
    • \n

  • Others. Look in deps/ for what else is available.

    \n
    • \n
\n

Node statically compiles all its dependencies into the executable. When\ncompiling your module, you don't need to worry about linking to any of these\nlibraries.\n\n\n

\n", - "modules": [ - { - "textRaw": "Hello world", - "name": "hello_world", - "desc": "

To get started let's make a small Addon which is the C++ equivalent of\nthe following Javascript code:\n\n

\n
exports.hello = function() { return 'world'; };
\n

First we create a file hello.cc:\n\n

\n
#include <node.h>\n#include <v8.h>\n\nusing namespace v8;\n\nHandle<Value> Method(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(String::New("world"));\n}\n\nvoid init(Handle<Object> target) {\n  target->Set(String::NewSymbol("hello"),\n      FunctionTemplate::New(Method)->GetFunction());\n}\nNODE_MODULE(hello, init)
\n

Note that all Node addons must export an initialization function:\n\n

\n
void Initialize (Handle<Object> target);\nNODE_MODULE(module_name, Initialize)
\n

There is no semi-colon after NODE_MODULE as it's not a function (see node.h).\n\n

\n

The module_name needs to match the filename of the final binary (minus the\n.node suffix).\n\n

\n

The source code needs to be built into hello.node, the binary Addon. To\ndo this we create a file called wscript which is python code and looks\nlike this:\n\n

\n
srcdir = '.'\nblddir = 'build'\nVERSION = '0.0.1'\n\ndef set_options(opt):\n  opt.tool_options('compiler_cxx')\n\ndef configure(conf):\n  conf.check_tool('compiler_cxx')\n  conf.check_tool('node_addon')\n\ndef build(bld):\n  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')\n  obj.target = 'hello'\n  obj.source = 'hello.cc'
\n

Running node-waf configure build will create a file\nbuild/default/hello.node which is our Addon.\n\n

\n

node-waf is just WAF, the python-based build system. node-waf is\nprovided for the ease of users.\n\n

\n

You can now use the binary addon in a Node project hello.js by pointing require to\nthe recently built module:\n\n

\n
var addon = require('./build/Release/hello');\n\nconsole.log(addon.hello()); // 'world'
\n

Please see patterns below for further information or\n

\n

https://github.com/pietern/hiredis-node for an example in production.\n\n\n

\n", - "type": "module", - "displayName": "Hello world" - }, - { - "textRaw": "Addon patterns", - "name": "addon_patterns", - "desc": "

Below are some addon patterns to help you get started. Consult the online\nv8 reference for help with the various v8\ncalls, and v8's Embedder's Guide\nfor an explanation of several concepts used such as handles, scopes,\nfunction templates, etc.\n\n

\n

To compile these examples, create the wscript file below and run\nnode-waf configure build:\n\n

\n
srcdir = '.'\nblddir = 'build'\nVERSION = '0.0.1'\n\ndef set_options(opt):\n  opt.tool_options('compiler_cxx')\n\ndef configure(conf):\n  conf.check_tool('compiler_cxx')\n  conf.check_tool('node_addon')\n\ndef build(bld):\n  obj = bld.new_task_gen('cxx', 'shlib', 'node_addon')\n  obj.target = 'addon'\n  obj.source = ['addon.cc']
\n

In cases where there is more than one .cc file, simply add the file name to the\nobj.source array, e.g.:\n\n

\n
obj.source = ['addon.cc', 'myexample.cc']
\n", - "modules": [ - { - "textRaw": "Function arguments", - "name": "function_arguments", - "desc": "

The following pattern illustrates how to read arguments from JavaScript\nfunction calls and return a result. This is the main and only needed source\naddon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> Add(const Arguments& args) {\n  HandleScope scope;\n\n  if (args.Length() < 2) {\n    ThrowException(Exception::TypeError(String::New("Wrong number of arguments")));\n    return scope.Close(Undefined());\n  }\n\n  if (!args[0]->IsNumber() || !args[1]->IsNumber()) {\n    ThrowException(Exception::TypeError(String::New("Wrong arguments")));\n    return scope.Close(Undefined());\n  }\n\n  Local<Number> num = Number::New(args[0]->NumberValue() +\n      args[1]->NumberValue());\n  return scope.Close(num);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("add"),\n      FunctionTemplate::New(Add)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

You can test it with the following JavaScript snippet:\n\n

\n
var addon = require('./build/Release/addon');\n\nconsole.log( 'This should be eight:', addon.add(3,5) );
\n", - "type": "module", - "displayName": "Function arguments" - }, - { - "textRaw": "Callbacks", - "name": "callbacks", - "desc": "

You can pass JavaScript functions to a C++ function and execute them from\nthere. Here's addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> RunCallback(const Arguments& args) {\n  HandleScope scope;\n\n  Local<Function> cb = Local<Function>::Cast(args[0]);\n  const unsigned argc = 1;\n  Local<Value> argv[argc] = { Local<Value>::New(String::New("hello world")) };\n  cb->Call(Context::GetCurrent()->Global(), argc, argv);\n\n  return scope.Close(Undefined());\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("runCallback"),\n      FunctionTemplate::New(RunCallback)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test it run the following JavaScript snippet:\n\n

\n
var addon = require('./build/Release/addon');\n\naddon.runCallback(function(msg){\n  console.log(msg); // 'hello world'\n});
\n", - "type": "module", - "displayName": "Callbacks" - }, - { - "textRaw": "Object factory", - "name": "object_factory", - "desc": "

You can create and return new objects from within a C++ function with this\naddon.cc pattern, which returns an object with property msg that echoes\nthe string passed to createObject():\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n\n  Local<Object> obj = Object::New();\n  obj->Set(String::NewSymbol("msg"), args[0]->ToString());\n\n  return scope.Close(obj);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test it in JavaScript:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj1 = addon.createObject('hello');\nvar obj2 = addon.createObject('world');\nconsole.log(obj1.msg+' '+obj2.msg); // 'hello world'
\n", - "type": "module", - "displayName": "Object factory" - }, - { - "textRaw": "Function factory", - "name": "function_factory", - "desc": "

This pattern illustrates how to create and return a JavaScript function that\nwraps a C++ function:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n\nusing namespace v8;\n\nHandle<Value> MyFunction(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(String::New("hello world"));\n}\n\nHandle<Value> CreateFunction(const Arguments& args) {\n  HandleScope scope;\n\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(MyFunction);\n  Local<Function> fn = tpl->GetFunction();\n  fn->SetName(String::NewSymbol("theFunction")); // omit this to make it anonymous\n\n  return scope.Close(fn);\n}\n\nvoid Init(Handle<Object> target) {\n  target->Set(String::NewSymbol("createFunction"),\n      FunctionTemplate::New(CreateFunction)->GetFunction());\n}\n\nNODE_MODULE(addon, Init)
\n

To test:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar fn = addon.createFunction();\nconsole.log(fn()); // 'hello world'
\n", - "type": "module", - "displayName": "Function factory" - }, - { - "textRaw": "Wrapping C++ objects", - "name": "wrapping_c++_objects", - "desc": "

Here we will create a wrapper for a C++ object/class MyObject that can be\ninstantiated in JavaScript through the new operator. First prepare the main\nmodule addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init(target);\n}\n\nNODE_MODULE(addon, InitAll)
\n

Then in myobject.h make your wrapper inherit from node::ObjectWrap:\n\n

\n
#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init(v8::Handle<v8::Object> target);\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);\n  double counter_;\n};\n\n#endif
\n

And in myobject.cc implement the various methods that you want to expose.\nHere we expose the method plusOne by adding it to the constructor's\nprototype:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nvoid MyObject::Init(Handle<Object> target) {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n  // Prototype\n  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),\n      FunctionTemplate::New(PlusOne)->GetFunction());\n\n  Persistent<Function> constructor = Persistent<Function>::New(tpl->GetFunction());\n  target->Set(String::NewSymbol("MyObject"), constructor);\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::PlusOne(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n  obj->counter_ += 1;\n\n  return scope.Close(Number::New(obj->counter_));\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj = new addon.MyObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13
\n", - "type": "module", - "displayName": "Wrapping C++ objects" - }, - { - "textRaw": "Factory of wrapped objects", - "name": "factory_of_wrapped_objects", - "desc": "

This is useful when you want to be able to create native objects without\nexplicitly instantiating them with the new operator in JavaScript, e.g.\n\n

\n
var obj = addon.createObject();\n// instead of:\n// var obj = new addon.Object();
\n

Let's register our createObject method in addon.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(MyObject::NewInstance(args));\n}\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init();\n\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n}\n\nNODE_MODULE(addon, InitAll)
\n

In myobject.h we now introduce the static method NewInstance that takes\ncare of instantiating the object (i.e. it does the job of new in JavaScript):\n\n

\n
#define BUILDING_NODE_EXTENSION\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init();\n  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Persistent<v8::Function> constructor;\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  static v8::Handle<v8::Value> PlusOne(const v8::Arguments& args);\n  double counter_;\n};\n\n#endif
\n

The implementation is similar to the above in myobject.cc:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nPersistent<Function> MyObject::constructor;\n\nvoid MyObject::Init() {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n  // Prototype\n  tpl->PrototypeTemplate()->Set(String::NewSymbol("plusOne"),\n      FunctionTemplate::New(PlusOne)->GetFunction());\n\n  constructor = Persistent<Function>::New(tpl->GetFunction());\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->counter_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::NewInstance(const Arguments& args) {\n  HandleScope scope;\n\n  const unsigned argc = 1;\n  Handle<Value> argv[argc] = { args[0] };\n  Local<Object> instance = constructor->NewInstance(argc, argv);\n\n  return scope.Close(instance);\n}\n\nHandle<Value> MyObject::PlusOne(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n  obj->counter_ += 1;\n\n  return scope.Close(Number::New(obj->counter_));\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj = addon.createObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13\n\nvar obj2 = addon.createObject(20);\nconsole.log( obj2.plusOne() ); // 21\nconsole.log( obj2.plusOne() ); // 22\nconsole.log( obj2.plusOne() ); // 23
\n", - "type": "module", - "displayName": "Factory of wrapped objects" - }, - { - "textRaw": "Passing wrapped objects around", - "name": "passing_wrapped_objects_around", - "desc": "

In addition to wrapping and returning C++ objects, you can pass them around\nby unwrapping them with Node's node::ObjectWrap::Unwrap helper function.\nIn the following addon.cc we introduce a function add() that can take on two\nMyObject objects:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nHandle<Value> CreateObject(const Arguments& args) {\n  HandleScope scope;\n  return scope.Close(MyObject::NewInstance(args));\n}\n\nHandle<Value> Add(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(\n      args[0]->ToObject());\n  MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(\n      args[1]->ToObject());\n\n  double sum = obj1->Val() + obj2->Val();\n  return scope.Close(Number::New(sum));\n}\n\nvoid InitAll(Handle<Object> target) {\n  MyObject::Init();\n\n  target->Set(String::NewSymbol("createObject"),\n      FunctionTemplate::New(CreateObject)->GetFunction());\n\n  target->Set(String::NewSymbol("add"),\n      FunctionTemplate::New(Add)->GetFunction());\n}\n\nNODE_MODULE(addon, InitAll)
\n

To make things interesting we introduce a public method in myobject.h so we\ncan probe private values after unwrapping the object:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init();\n  static v8::Handle<v8::Value> NewInstance(const v8::Arguments& args);\n  double Val() const { return val_; }\n\n private:\n  MyObject();\n  ~MyObject();\n\n  static v8::Persistent<v8::Function> constructor;\n  static v8::Handle<v8::Value> New(const v8::Arguments& args);\n  double val_;\n};\n\n#endif
\n

The implementation of myobject.cc is similar as before:\n\n

\n
#define BUILDING_NODE_EXTENSION\n#include <node.h>\n#include "myobject.h"\n\nusing namespace v8;\n\nMyObject::MyObject() {};\nMyObject::~MyObject() {};\n\nPersistent<Function> MyObject::constructor;\n\nvoid MyObject::Init() {\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(New);\n  tpl->SetClassName(String::NewSymbol("MyObject"));\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n\n  constructor = Persistent<Function>::New(tpl->GetFunction());\n}\n\nHandle<Value> MyObject::New(const Arguments& args) {\n  HandleScope scope;\n\n  MyObject* obj = new MyObject();\n  obj->val_ = args[0]->IsUndefined() ? 0 : args[0]->NumberValue();\n  obj->Wrap(args.This());\n\n  return args.This();\n}\n\nHandle<Value> MyObject::NewInstance(const Arguments& args) {\n  HandleScope scope;\n\n  const unsigned argc = 1;\n  Handle<Value> argv[argc] = { args[0] };\n  Local<Object> instance = constructor->NewInstance(argc, argv);\n\n  return scope.Close(instance);\n}
\n

Test it with:\n\n

\n
var addon = require('./build/Release/addon');\n\nvar obj1 = addon.createObject(10);\nvar obj2 = addon.createObject(20);\nvar result = addon.add(obj1, obj2);\n\nconsole.log(result); // 30
\n", - "type": "module", - "displayName": "Passing wrapped objects around" - } - ], - "type": "module", - "displayName": "Addon patterns" - } - ], - "type": "module", - "displayName": "Addons" - }, - { - "textRaw": "util", - "name": "util", - "stability": 5, - "stabilityText": "Locked", - "desc": "

These functions are in the module 'util'. Use require('util') to access\nthem.\n\n\n

\n", - "methods": [ - { - "textRaw": "util.format()", - "type": "method", - "name": "format", - "desc": "

Returns a formatted string using the first argument as a printf-like format.\n\n

\n

The first argument is a string that contains zero or more placeholders.\nEach placeholder is replaced with the converted value from its corresponding\nargument. Supported placeholders are:\n\n

\n
    \n
  • %s - String.
    • \n
  • %d - Number (both integer and float).
    • \n
  • %j - JSON.
    • \n
  • %% - single percent sign ('%'). This does not consume an argument.
    • \n
\n

If the placeholder does not have a corresponding argument, the placeholder is\nnot replaced.\n\n

\n
util.format('%s:%s', 'foo'); // 'foo:%s'
\n

If there are more arguments than placeholders, the extra arguments are\nconverted to strings with util.inspect() and these strings are concatenated,\ndelimited by a space.\n\n

\n
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
\n

If the first argument is not a format string then util.format() returns\na string that is the concatenation of all its arguments separated by spaces.\nEach argument is converted to a string with util.inspect().\n\n

\n
util.format(1, 2, 3); // '1 2 3'
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "util.debug(string)", - "type": "method", - "name": "debug", - "desc": "

A synchronous output function. Will block the process and\noutput string immediately to stderr.\n\n

\n
require('util').debug('message on stderr');
\n", - "signatures": [ - { - "params": [ - { - "name": "string" - } - ] - } - ] - }, - { - "textRaw": "util.log(string)", - "type": "method", - "name": "log", - "desc": "

Output with timestamp on stdout.\n\n

\n
require('util').log('Timestamped message.');
\n", - "signatures": [ - { - "params": [ - { - "name": "string" - } - ] - } - ] - }, - { - "textRaw": "util.inspect(object, [showHidden], [depth], [colors])", - "type": "method", - "name": "inspect", - "desc": "

Return a string representation of object, which is useful for debugging.\n\n

\n

If showHidden is true, then the object's non-enumerable properties will be\nshown too. Defaults to false.\n\n

\n

If depth is provided, it tells inspect how many times to recurse while\nformatting the object. This is useful for inspecting large complicated objects.\n\n

\n

The default is to only recurse twice. To make it recurse indefinitely, pass\nin null for depth.\n\n

\n

If colors is true, the output will be styled with ANSI color codes.\nDefaults to false.\n\n

\n

Example of inspecting all properties of the util object:\n\n

\n
var util = require('util');\n\nconsole.log(util.inspect(util, true, null));
\n", - "signatures": [ - { - "params": [ - { - "name": "object" - }, - { - "name": "showHidden", - "optional": true - }, - { - "name": "depth", - "optional": true - }, - { - "name": "colors", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "util.isArray(object)", - "type": "method", - "name": "isArray", - "desc": "

Returns true if the given "object" is an Array. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isArray([])\n  // true\nutil.isArray(new Array)\n  // true\nutil.isArray({})\n  // false
\n", - "signatures": [ - { - "params": [ - { - "name": "object" - } - ] - } - ] - }, - { - "textRaw": "util.isRegExp(object)", - "type": "method", - "name": "isRegExp", - "desc": "

Returns true if the given "object" is a RegExp. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isRegExp(/some regexp/)\n  // true\nutil.isRegExp(new RegExp('another regexp'))\n  // true\nutil.isRegExp({})\n  // false
\n", - "signatures": [ - { - "params": [ - { - "name": "object" - } - ] - } - ] - }, - { - "textRaw": "util.isDate(object)", - "type": "method", - "name": "isDate", - "desc": "

Returns true if the given "object" is a Date. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isDate(new Date())\n  // true\nutil.isDate(Date())\n  // false (without 'new' returns a String)\nutil.isDate({})\n  // false
\n", - "signatures": [ - { - "params": [ - { - "name": "object" - } - ] - } - ] - }, - { - "textRaw": "util.isError(object)", - "type": "method", - "name": "isError", - "desc": "

Returns true if the given "object" is an Error. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isError(new Error())\n  // true\nutil.isError(new TypeError())\n  // true\nutil.isError({ name: 'Error', message: 'an error occurred' })\n  // false
\n", - "signatures": [ - { - "params": [ - { - "name": "object" - } - ] - } - ] - }, - { - "textRaw": "util.pump(readableStream, writableStream, [callback])", - "type": "method", - "name": "pump", - "desc": "

Experimental\n\n

\n

Read the data from readableStream and send it to the writableStream.\nWhen writableStream.write(data) returns false readableStream will be\npaused until the drain event occurs on the writableStream. callback gets\nan error as its only argument and is called when writableStream is closed or\nwhen an error occurs.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "readableStream" - }, - { - "name": "writableStream" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "util.inherits(constructor, superConstructor)", - "type": "method", - "name": "inherits", - "desc": "

Inherit the prototype methods from one\nconstructor\ninto another. The prototype of constructor will be set to a new\nobject created from superConstructor.\n\n

\n

As an additional convenience, superConstructor will be accessible\nthrough the constructor.super_ property.\n\n

\n
var util = require("util");\nvar events = require("events");\n\nfunction MyStream() {\n    events.EventEmitter.call(this);\n}\n\nutil.inherits(MyStream, events.EventEmitter);\n\nMyStream.prototype.write = function(data) {\n    this.emit("data", data);\n}\n\nvar stream = new MyStream();\n\nconsole.log(stream instanceof events.EventEmitter); // true\nconsole.log(MyStream.super_ === events.EventEmitter); // true\n\nstream.on("data", function(data) {\n    console.log('Received data: "' + data + '"');\n})\nstream.write("It works!"); // Received data: "It works!"
\n", - "signatures": [ - { - "params": [ - { - "name": "constructor" - }, - { - "name": "superConstructor" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "util" - }, - { - "textRaw": "Events", - "name": "Events", - "stability": 4, - "stabilityText": "API Frozen", - "type": "module", - "desc": "

Many objects in Node emit events: a net.Server emits an event each time\na peer connects to it, a fs.readStream emits an event when the file is\nopened. All objects which emit events are instances of events.EventEmitter.\nYou can access this module by doing: require("events");\n\n

\n

Typically, event names are represented by a camel-cased string, however,\nthere aren't any strict restrictions on that, as any string will be accepted.\n\n

\n

Functions can then be attached to objects, to be executed when an event\nis emitted. These functions are called listeners.\n\n\n

\n", - "classes": [ - { - "textRaw": "Class: events.EventEmitter", - "type": "class", - "name": "events.EventEmitter", - "desc": "

To access the EventEmitter class, require('events').EventEmitter.\n\n

\n

When an EventEmitter instance experiences an error, the typical action is\nto emit an 'error' event. Error events are treated as a special case in node.\nIf there is no listener for it, then the default action is to print a stack\ntrace and exit the program.\n\n

\n

All EventEmitters emit the event 'newListener' when new listeners are\nadded.\n\n

\n", - "methods": [ - { - "textRaw": "emitter.addListener(event, listener)", - "type": "method", - "name": "addListener", - "desc": "

Adds a listener to the end of the listeners array for the specified event.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "event" - }, - { - "name": "listener" - } - ] - }, - { - "params": [ - { - "name": "event" - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "emitter.on(event, listener)", - "type": "method", - "name": "on", - "desc": "

Adds a listener to the end of the listeners array for the specified event.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "event" - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "emitter.once(event, listener)", - "type": "method", - "name": "once", - "desc": "

Adds a one time listener for the event. This listener is\ninvoked only the next time the event is fired, after which\nit is removed.\n\n

\n
server.once('connection', function (stream) {\n  console.log('Ah, we have our first user!');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "event" - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "emitter.removeListener(event, listener)", - "type": "method", - "name": "removeListener", - "desc": "

Remove a listener from the listener array for the specified event.\nCaution: changes array indices in the listener array behind the listener.\n\n

\n
var callback = function(stream) {\n  console.log('someone connected!');\n};\nserver.on('connection', callback);\n// ...\nserver.removeListener('connection', callback);
\n", - "signatures": [ - { - "params": [ - { - "name": "event" - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "emitter.removeAllListeners([event])", - "type": "method", - "name": "removeAllListeners", - "desc": "

Removes all listeners, or those of the specified event.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "event", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "emitter.setMaxListeners(n)", - "type": "method", - "name": "setMaxListeners", - "desc": "

By default EventEmitters will print a warning if more than 10 listeners are\nadded for a particular event. This is a useful default which helps finding memory leaks.\nObviously not all Emitters should be limited to 10. This function allows\nthat to be increased. Set to zero for unlimited.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "n" - } - ] - } - ] - }, - { - "textRaw": "emitter.listeners(event)", - "type": "method", - "name": "listeners", - "desc": "

Returns an array of listeners for the specified event. This array can be\nmanipulated, e.g. to remove listeners.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});\nconsole.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
\n", - "signatures": [ - { - "params": [ - { - "name": "event" - } - ] - } - ] - }, - { - "textRaw": "emitter.emit(event, [arg1], [arg2], [...])", - "type": "method", - "name": "emit", - "desc": "

Execute each of the listeners in order with the supplied arguments.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "event" - }, - { - "name": "arg1", - "optional": true - }, - { - "name": "arg2", - "optional": true - }, - { - "name": "...", - "optional": true - } - ] - } - ] - } - ], - "events": [ - { - "textRaw": "Event: 'newListener'", - "type": "event", - "name": "newListener", - "params": [], - "desc": "

This event is emitted any time someone adds a new listener.\n\n

\n" - } - ] - } - ] - }, - { - "textRaw": "Buffer", - "name": "buffer", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Pure Javascript is Unicode friendly but not nice to binary data. When\ndealing with TCP streams or the file system, it's necessary to handle octet\nstreams. Node has several strategies for manipulating, creating, and\nconsuming octet streams.\n\n

\n

Raw data is stored in instances of the Buffer class. A Buffer is similar\nto an array of integers but corresponds to a raw memory allocation outside\nthe V8 heap. A Buffer cannot be resized.\n\n

\n

The Buffer class is a global, making it very rare that one would need\nto ever require('buffer').\n\n

\n

Converting between Buffers and JavaScript string objects requires an explicit\nencoding method. Here are the different string encodings.\n\n

\n
    \n

  • 'ascii' - for 7 bit ASCII data only. This encoding method is very fast, and\nwill strip the high bit if set.\nNote that this encoding converts a null character ('\\0' or '\\u0000') into\n0x20 (character code of a space). If you want to convert a null character\ninto 0x00, you should use 'utf8'.

    \n
    • \n

  • 'utf8' - Multi byte encoded Unicode characters. Many web pages and other document formats use UTF-8.

    \n
    • \n

  • 'ucs2' - 2-bytes, little endian encoded Unicode characters. It can encode\nonly BMP(Basic Multilingual Plane, U+0000 - U+FFFF).

    \n
    • \n

  • 'base64' - Base64 string encoding.

    \n
    • \n

  • 'binary' - A way of encoding raw binary data into strings by using only\nthe first 8 bits of each character. This encoding method is deprecated and\nshould be avoided in favor of Buffer objects where possible. This encoding\nwill be removed in future versions of Node.

    \n
    • \n

  • 'hex' - Encode each byte as two hexidecimal characters.

    \n
    • \n
\n", - "classes": [ - { - "textRaw": "Class: Buffer", - "type": "class", - "name": "Buffer", - "desc": "

The Buffer class is a global type for dealing with binary data directly.\nIt can be constructed in a variety of ways.\n\n

\n", - "methods": [ - { - "textRaw": "buf.write(string, [offset], [length], [encoding])", - "type": "method", - "name": "write", - "signatures": [ - { - "params": [ - { - "textRaw": "`string` String - data to be written to buffer ", - "name": "string", - "desc": "String - data to be written to buffer" - }, - { - "textRaw": "`offset` Number, Optional, Default: 0 ", - "name": "offset", - "desc": "Number, Optional, Default: 0", - "optional": true - }, - { - "textRaw": "`length` Number, Optional, Default: `buffer.length - offset` ", - "name": "length", - "desc": "Number, Optional, Default: `buffer.length - offset`", - "optional": true - }, - { - "textRaw": "`encoding` String, Optional, Default: 'utf8' ", - "name": "encoding", - "desc": "String, Optional, Default: 'utf8'", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "string" - }, - { - "name": "offset", - "optional": true - }, - { - "name": "length", - "optional": true - }, - { - "name": "encoding", - "optional": true - } - ] - } - ], - "desc": "

Writes string to the buffer at offset using the given encoding.\noffset defaults to 0, encoding defaults to 'utf8'. length is\nthe number of bytes to write. Returns number of octets written. If buffer did\nnot contain enough space to fit the entire string, it will write a partial\namount of the string. length defaults to buffer.length - offset.\nThe method will not write partial characters.\n\n

\n
buf = new Buffer(256);\nlen = buf.write('\\u00bd + \\u00bc = \\u00be', 0);\nconsole.log(len + " bytes: " + buf.toString('utf8', 0, len));
\n

The number of characters written (which may be different than the number of\nbytes written) is set in Buffer._charsWritten and will be overwritten the\nnext time buf.write() is called.\n\n\n

\n" - }, - { - "textRaw": "buf.toString([encoding], [start], [end])", - "type": "method", - "name": "toString", - "signatures": [ - { - "params": [ - { - "textRaw": "`encoding` String, Optional, Default: 'utf8' ", - "name": "encoding", - "desc": "String, Optional, Default: 'utf8'", - "optional": true - }, - { - "textRaw": "`start` Number, Optional, Default: 0 ", - "name": "start", - "desc": "Number, Optional, Default: 0", - "optional": true - }, - { - "textRaw": "`end` Number, Optional, Default: `buffer.length` ", - "name": "end", - "desc": "Number, Optional, Default: `buffer.length`", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "encoding", - "optional": true - }, - { - "name": "start", - "optional": true - }, - { - "name": "end", - "optional": true - } - ] - } - ], - "desc": "

Decodes and returns a string from buffer data encoded with encoding\n(defaults to 'utf8') beginning at start (defaults to 0) and ending at\nend (defaults to buffer.length).\n\n

\n

See buffer.write() example, above.\n\n\n

\n" - }, - { - "textRaw": "buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])", - "type": "method", - "name": "copy", - "signatures": [ - { - "params": [ - { - "textRaw": "`targetBuffer` Buffer object - Buffer to copy into ", - "name": "targetBuffer", - "desc": "Buffer object - Buffer to copy into" - }, - { - "textRaw": "`targetStart` Number, Optional, Default: 0 ", - "name": "targetStart", - "desc": "Number, Optional, Default: 0", - "optional": true - }, - { - "textRaw": "`sourceStart` Number, Optional, Default: 0 ", - "name": "sourceStart", - "desc": "Number, Optional, Default: 0", - "optional": true - }, - { - "textRaw": "`sourceEnd` Number, Optional, Default: `buffer.length` ", - "name": "sourceEnd", - "desc": "Number, Optional, Default: `buffer.length`", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "targetBuffer" - }, - { - "name": "targetStart", - "optional": true - }, - { - "name": "sourceStart", - "optional": true - }, - { - "name": "sourceEnd", - "optional": true - } - ] - } - ], - "desc": "

Does copy between buffers. The source and target regions can be overlapped.\ntargetStart and sourceStart default to 0.\nsourceEnd defaults to buffer.length.\n\n

\n

Example: build two Buffers, then copy buf1 from byte 16 through byte 19\ninto buf2, starting at the 8th byte in buf2.\n\n

\n
buf1 = new Buffer(26);\nbuf2 = new Buffer(26);\n\nfor (var i = 0 ; i < 26 ; i++) {\n  buf1[i] = i + 97; // 97 is ASCII a\n  buf2[i] = 33; // ASCII !\n}\n\nbuf1.copy(buf2, 8, 16, 20);\nconsole.log(buf2.toString('ascii', 0, 25));\n\n// !!!!!!!!qrst!!!!!!!!!!!!!
\n" - }, - { - "textRaw": "buf.slice([start], [end])", - "type": "method", - "name": "slice", - "signatures": [ - { - "params": [ - { - "textRaw": "`start` Number, Optional, Default: 0 ", - "name": "start", - "desc": "Number, Optional, Default: 0", - "optional": true - }, - { - "textRaw": "`end` Number, Optional, Default: `buffer.length` ", - "name": "end", - "desc": "Number, Optional, Default: `buffer.length`", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "start", - "optional": true - }, - { - "name": "end", - "optional": true - } - ] - } - ], - "desc": "

Returns a new buffer which references the same memory as the old, but offset\nand cropped by the start (defaults to 0) and end (defaults to\nbuffer.length) indexes.\n\n

\n

Modifying the new buffer slice will modify memory in the original buffer!\n\n

\n

Example: build a Buffer with the ASCII alphabet, take a slice, then modify one\nbyte from the original Buffer.\n\n

\n
var buf1 = new Buffer(26);\n\nfor (var i = 0 ; i < 26 ; i++) {\n  buf1[i] = i + 97; // 97 is ASCII a\n}\n\nvar buf2 = buf1.slice(0, 3);\nconsole.log(buf2.toString('ascii', 0, buf2.length));\nbuf1[0] = 33;\nconsole.log(buf2.toString('ascii', 0, buf2.length));\n\n// abc\n// !bc
\n" - }, - { - "textRaw": "buf.readUInt8(offset, [noAssert])", - "type": "method", - "name": "readUInt8", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads an unsigned 8 bit integer from the buffer at the specified offset.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nfor (ii = 0; ii < buf.length; ii++) {\n  console.log(buf.readUInt8(ii));\n}\n\n// 0x3\n// 0x4\n// 0x23\n// 0x42
\n" - }, - { - "textRaw": "buf.readUInt16LE(offset, [noAssert])", - "type": "method", - "name": "readUInt16LE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads an unsigned 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt16BE(0));\nconsole.log(buf.readUInt16LE(0));\nconsole.log(buf.readUInt16BE(1));\nconsole.log(buf.readUInt16LE(1));\nconsole.log(buf.readUInt16BE(2));\nconsole.log(buf.readUInt16LE(2));\n\n// 0x0304\n// 0x0403\n// 0x0423\n// 0x2304\n// 0x2342\n// 0x4223
\n" - }, - { - "textRaw": "buf.readUInt16BE(offset, [noAssert])", - "type": "method", - "name": "readUInt16BE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads an unsigned 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt16BE(0));\nconsole.log(buf.readUInt16LE(0));\nconsole.log(buf.readUInt16BE(1));\nconsole.log(buf.readUInt16LE(1));\nconsole.log(buf.readUInt16BE(2));\nconsole.log(buf.readUInt16LE(2));\n\n// 0x0304\n// 0x0403\n// 0x0423\n// 0x2304\n// 0x2342\n// 0x4223
\n" - }, - { - "textRaw": "buf.readUInt32LE(offset, [noAssert])", - "type": "method", - "name": "readUInt32LE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads an unsigned 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt32BE(0));\nconsole.log(buf.readUInt32LE(0));\n\n// 0x03042342\n// 0x42230403
\n" - }, - { - "textRaw": "buf.readUInt32BE(offset, [noAssert])", - "type": "method", - "name": "readUInt32BE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads an unsigned 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt32BE(0));\nconsole.log(buf.readUInt32LE(0));\n\n// 0x03042342\n// 0x42230403
\n" - }, - { - "textRaw": "buf.readInt8(offset, [noAssert])", - "type": "method", - "name": "readInt8", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a signed 8 bit integer from the buffer at the specified offset.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt8, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" - }, - { - "textRaw": "buf.readInt16LE(offset, [noAssert])", - "type": "method", - "name": "readInt16LE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a signed 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt16*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" - }, - { - "textRaw": "buf.readInt16BE(offset, [noAssert])", - "type": "method", - "name": "readInt16BE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a signed 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt16*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" - }, - { - "textRaw": "buf.readInt32LE(offset, [noAssert])", - "type": "method", - "name": "readInt32LE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a signed 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt32*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" - }, - { - "textRaw": "buf.readInt32BE(offset, [noAssert])", - "type": "method", - "name": "readInt32BE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a signed 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt32*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" - }, - { - "textRaw": "buf.readFloatLE(offset, [noAssert])", - "type": "method", - "name": "readFloatLE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a 32 bit float from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x00;\nbuf[1] = 0x00;\nbuf[2] = 0x80;\nbuf[3] = 0x3f;\n\nconsole.log(buf.readFloatLE(0));\n\n// 0x01
\n" - }, - { - "textRaw": "buf.readFloatBE(offset, [noAssert])", - "type": "method", - "name": "readFloatBE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a 32 bit float from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x00;\nbuf[1] = 0x00;\nbuf[2] = 0x80;\nbuf[3] = 0x3f;\n\nconsole.log(buf.readFloatLE(0));\n\n// 0x01
\n" - }, - { - "textRaw": "buf.readDoubleLE(offset, [noAssert])", - "type": "method", - "name": "readDoubleLE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a 64 bit double from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\n\nbuf[0] = 0x55;\nbuf[1] = 0x55;\nbuf[2] = 0x55;\nbuf[3] = 0x55;\nbuf[4] = 0x55;\nbuf[5] = 0x55;\nbuf[6] = 0xd5;\nbuf[7] = 0x3f;\n\nconsole.log(buf.readDoubleLE(0));\n\n// 0.3333333333333333
\n" - }, - { - "textRaw": "buf.readDoubleBE(offset, [noAssert])", - "type": "method", - "name": "readDoubleBE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a 64 bit double from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\n\nbuf[0] = 0x55;\nbuf[1] = 0x55;\nbuf[2] = 0x55;\nbuf[3] = 0x55;\nbuf[4] = 0x55;\nbuf[5] = 0x55;\nbuf[6] = 0xd5;\nbuf[7] = 0x3f;\n\nconsole.log(buf.readDoubleLE(0));\n\n// 0.3333333333333333
\n" - }, - { - "textRaw": "buf.writeUInt8(value, offset, [noAssert])", - "type": "method", - "name": "writeUInt8", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset. Note, value must be a\nvalid unsigned 8 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt8(0x3, 0);\nbuf.writeUInt8(0x4, 1);\nbuf.writeUInt8(0x23, 2);\nbuf.writeUInt8(0x42, 3);\n\nconsole.log(buf);\n\n// <Buffer 03 04 23 42>
\n" - }, - { - "textRaw": "buf.writeUInt16LE(value, offset, [noAssert])", - "type": "method", - "name": "writeUInt16LE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt16BE(0xdead, 0);\nbuf.writeUInt16BE(0xbeef, 2);\n\nconsole.log(buf);\n\nbuf.writeUInt16LE(0xdead, 0);\nbuf.writeUInt16LE(0xbeef, 2);\n\nconsole.log(buf);\n\n// <Buffer de ad be ef>\n// <Buffer ad de ef be>
\n" - }, - { - "textRaw": "buf.writeUInt16BE(value, offset, [noAssert])", - "type": "method", - "name": "writeUInt16BE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt16BE(0xdead, 0);\nbuf.writeUInt16BE(0xbeef, 2);\n\nconsole.log(buf);\n\nbuf.writeUInt16LE(0xdead, 0);\nbuf.writeUInt16LE(0xbeef, 2);\n\nconsole.log(buf);\n\n// <Buffer de ad be ef>\n// <Buffer ad de ef be>
\n" - }, - { - "textRaw": "buf.writeUInt32LE(value, offset, [noAssert])", - "type": "method", - "name": "writeUInt32LE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt32BE(0xfeedface, 0);\n\nconsole.log(buf);\n\nbuf.writeUInt32LE(0xfeedface, 0);\n\nconsole.log(buf);\n\n// <Buffer fe ed fa ce>\n// <Buffer ce fa ed fe>
\n" - }, - { - "textRaw": "buf.writeUInt32BE(value, offset, [noAssert])", - "type": "method", - "name": "writeUInt32BE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt32BE(0xfeedface, 0);\n\nconsole.log(buf);\n\nbuf.writeUInt32LE(0xfeedface, 0);\n\nconsole.log(buf);\n\n// <Buffer fe ed fa ce>\n// <Buffer ce fa ed fe>
\n" - }, - { - "textRaw": "buf.writeInt8(value, offset, [noAssert])", - "type": "method", - "name": "writeInt8", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset. Note, value must be a\nvalid signed 8 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt8, except value is written out as a two's complement\nsigned integer into buffer.\n\n

\n" - }, - { - "textRaw": "buf.writeInt16LE(value, offset, [noAssert])", - "type": "method", - "name": "writeInt16LE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt16*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" - }, - { - "textRaw": "buf.writeInt16BE(value, offset, [noAssert])", - "type": "method", - "name": "writeInt16BE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt16*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" - }, - { - "textRaw": "buf.writeInt32LE(value, offset, [noAssert])", - "type": "method", - "name": "writeInt32LE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt32*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" - }, - { - "textRaw": "buf.writeInt32BE(value, offset, [noAssert])", - "type": "method", - "name": "writeInt32BE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt32*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" - }, - { - "textRaw": "buf.writeFloatLE(value, offset, [noAssert])", - "type": "method", - "name": "writeFloatLE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 32 bit float.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeFloatBE(0xcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeFloatLE(0xcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 4f 4a fe bb>\n// <Buffer bb fe 4a 4f>
\n" - }, - { - "textRaw": "buf.writeFloatBE(value, offset, [noAssert])", - "type": "method", - "name": "writeFloatBE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 32 bit float.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeFloatBE(0xcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeFloatLE(0xcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 4f 4a fe bb>\n// <Buffer bb fe 4a 4f>
\n" - }, - { - "textRaw": "buf.writeDoubleLE(value, offset, [noAssert])", - "type": "method", - "name": "writeDoubleLE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 64 bit double.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\nbuf.writeDoubleBE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeDoubleLE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 43 eb d5 b7 dd f9 5f d7>\n// <Buffer d7 5f f9 dd b7 d5 eb 43>
\n" - }, - { - "textRaw": "buf.writeDoubleBE(value, offset, [noAssert])", - "type": "method", - "name": "writeDoubleBE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 64 bit double.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\nbuf.writeDoubleBE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeDoubleLE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 43 eb d5 b7 dd f9 5f d7>\n// <Buffer d7 5f f9 dd b7 d5 eb 43>
\n" - }, - { - "textRaw": "buf.fill(value, [offset], [end])", - "type": "method", - "name": "fill", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` ", - "name": "value" - }, - { - "textRaw": "`offset` Number, Optional ", - "name": "offset", - "optional": true, - "desc": "Number" - }, - { - "textRaw": "`end` Number, Optional ", - "name": "end", - "optional": true, - "desc": "Number" - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset", - "optional": true - }, - { - "name": "end", - "optional": true - } - ] - } - ], - "desc": "

Fills the buffer with the specified value. If the offset (defaults to 0)\nand end (defaults to buffer.length) are not given it will fill the entire\nbuffer.\n\n

\n
var b = new Buffer(50);\nb.fill("h");
\n" - } - ], - "properties": [ - { - "textRaw": "buf[index]", - "name": "[index]", - "desc": "

Get and set the octet at index. The values refer to individual bytes,\nso the legal range is between 0x00 and 0xFF hex or 0 and 255.\n\n

\n

Example: copy an ASCII string into a buffer, one byte at a time:\n\n

\n
str = "node.js";\nbuf = new Buffer(str.length);\n\nfor (var i = 0; i < str.length ; i++) {\n  buf[i] = str.charCodeAt(i);\n}\n\nconsole.log(buf);\n\n// node.js
\n" - }, - { - "textRaw": "`length` Number ", - "name": "length", - "desc": "

The size of the buffer in bytes. Note that this is not necessarily the size\nof the contents. length refers to the amount of memory allocated for the\nbuffer object. It does not change when the contents of the buffer are changed.\n\n

\n
buf = new Buffer(1234);\n\nconsole.log(buf.length);\nbuf.write("some string", "ascii", 0);\nconsole.log(buf.length);\n\n// 1234\n// 1234
\n", - "shortDesc": "Number" - } - ], - "classMethods": [ - { - "textRaw": "Class Method: Buffer.isBuffer(obj)", - "type": "classMethod", - "name": "isBuffer", - "signatures": [ - { - "return": { - "textRaw": "Return: Boolean ", - "name": "return", - "desc": "Boolean" - }, - "params": [ - { - "textRaw": "`obj` Object ", - "name": "obj", - "desc": "Object" - } - ] - }, - { - "params": [ - { - "name": "obj" - } - ] - } - ], - "desc": "

Tests if obj is a Buffer.\n\n

\n" - }, - { - "textRaw": "Class Method: Buffer.byteLength(string, [encoding])", - "type": "classMethod", - "name": "byteLength", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`string` String ", - "name": "string", - "desc": "String" - }, - { - "textRaw": "`encoding` String, Optional, Default: 'utf8' ", - "name": "encoding", - "desc": "String, Optional, Default: 'utf8'", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "string" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ], - "desc": "

Gives the actual byte length of a string. encoding defaults to 'utf8'.\nThis is not the same as String.prototype.length since that returns the\nnumber of characters in a string.\n\n

\n

Example:\n\n

\n
str = '\\u00bd + \\u00bc = \\u00be';\n\nconsole.log(str + ": " + str.length + " characters, " +\n  Buffer.byteLength(str, 'utf8') + " bytes");\n\n// ½ + ¼ = ¾: 9 characters, 12 bytes
\n" - } - ], - "signatures": [ - { - "params": [ - { - "textRaw": "`size` Number ", - "name": "size", - "desc": "Number" - } - ], - "desc": "

Allocates a new buffer of size octets.\n\n

\n" - }, - { - "params": [ - { - "name": "size" - } - ], - "desc": "

Allocates a new buffer of size octets.\n\n

\n" - }, - { - "params": [ - { - "textRaw": "`array` Array ", - "name": "array", - "desc": "Array" - } - ], - "desc": "

Allocates a new buffer using an array of octets.\n\n

\n" - }, - { - "params": [ - { - "name": "array" - } - ], - "desc": "

Allocates a new buffer using an array of octets.\n\n

\n" - }, - { - "params": [ - { - "textRaw": "`str` String - string to encode. ", - "name": "str", - "desc": "String - string to encode." - }, - { - "textRaw": "`encoding` String - encoding to use, Optional. ", - "name": "encoding", - "desc": "String - encoding to use, Optional.", - "optional": true - } - ], - "desc": "

Allocates a new buffer containing the given str.\nencoding defaults to 'utf8'.\n\n

\n" - }, - { - "params": [ - { - "name": "str" - }, - { - "name": "encoding", - "optional": true - } - ], - "desc": "

Allocates a new buffer containing the given str.\nencoding defaults to 'utf8'.\n\n

\n" - } - ] - }, - { - "textRaw": "Class: SlowBuffer", - "type": "class", - "name": "SlowBuffer", - "desc": "

This class is primarily for internal use. JavaScript programs should\nuse Buffer instead of using SlowBuffer.\n\n

\n

In order to avoid the overhead of allocating many C++ Buffer objects for\nsmall blocks of memory in the lifetime of a server, Node allocates memory\nin 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it\nwill be backed by a parent SlowBuffer object. If it is larger than this,\nthen Node will allocate a SlowBuffer slab for it directly.\n\n

\n" - } - ], - "properties": [ - { - "textRaw": "`INSPECT_MAX_BYTES` Number, Default: 50 ", - "name": "INSPECT_MAX_BYTES", - "desc": "

How many bytes will be returned when buffer.inspect() is called. This can\nbe overridden by user modules.\n\n

\n

Note that this is a property on the buffer module returned by\nrequire('buffer'), not on the Buffer global, or a buffer instance.\n\n

\n", - "shortDesc": "Number, Default: 50" - } - ], - "type": "module", - "displayName": "Buffer" - }, - { - "textRaw": "Stream", - "name": "stream", - "stability": 2, - "stabilityText": "Unstable", - "desc": "

A stream is an abstract interface implemented by various objects in Node.\nFor example a request to an HTTP server is a stream, as is stdout. Streams\nare readable, writable, or both. All streams are instances of EventEmitter.\n\n

\n

You can load up the Stream base class by doing require('stream').\n\n

\n", - "classes": [ - { - "textRaw": "Readable Stream", - "name": "Readable Stream", - "type": "class", - "desc": "

A Readable Stream has the following methods, members, and events.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'data'", - "type": "event", - "name": "data", - "desc": "

function (data) { }\n\n

\n

The 'data' event emits either a Buffer (by default) or a string if\nsetEncoding() was used.\n\n

\n

Note that the data will be lost if there is no listener when a\nReadable Stream emits a 'data' event.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'end'", - "type": "event", - "name": "end", - "desc": "

function () { }\n\n

\n

Emitted when the stream has received an EOF (FIN in TCP terminology).\nIndicates that no more 'data' events will happen. If the stream is also\nwritable, it may be possible to continue writing.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "desc": "

function (exception) { }\n\n

\n

Emitted if there was an error receiving data.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () { }\n\n

\n

Emitted when the underlying file descriptor has been closed. Not all streams\nwill emit this. (For example, an incoming HTTP request will not emit\n'close'.)\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "stream.readable", - "name": "readable", - "desc": "

A boolean that is true by default, but turns false after an 'error'\noccurred, the stream came to an 'end', or destroy() was called.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "stream.setEncoding(encoding)", - "type": "method", - "name": "setEncoding", - "desc": "

Makes the data event emit a string instead of a Buffer. encoding can be\n'utf8', 'ascii', or 'base64'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding" - } - ] - } - ] - }, - { - "textRaw": "stream.pause()", - "type": "method", - "name": "pause", - "desc": "

Pauses the incoming 'data' events.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "stream.resume()", - "type": "method", - "name": "resume", - "desc": "

Resumes the incoming 'data' events after a pause().\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "stream.destroy()", - "type": "method", - "name": "destroy", - "desc": "

Closes the underlying file descriptor. Stream will not emit any more events.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "stream.pipe(destination, [options])", - "type": "method", - "name": "pipe", - "desc": "

This is a Stream.prototype method available on all Streams.\n\n

\n

Connects this read stream to destination WriteStream. Incoming\ndata on this stream gets written to destination. The destination and source\nstreams are kept in sync by pausing and resuming as necessary.\n\n

\n

This function returns the destination stream.\n\n

\n

Emulating the Unix cat command:\n\n

\n
process.stdin.resume();\nprocess.stdin.pipe(process.stdout);
\n

By default end() is called on the destination when the source stream emits\nend, so that destination is no longer writable. Pass { end: false } as\noptions to keep the destination stream open.\n\n

\n

This keeps process.stdout open so that "Goodbye" can be written at the end.\n\n

\n
process.stdin.resume();\n\nprocess.stdin.pipe(process.stdout, { end: false });\n\nprocess.stdin.on("end", function() {\n  process.stdout.write("Goodbye\\n");\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "destination" - }, - { - "name": "options", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Writable Stream", - "name": "Writable Stream", - "type": "class", - "desc": "

A Writable Stream has the following methods, members, and events.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'drain'", - "type": "event", - "name": "drain", - "desc": "

function () { }\n\n

\n

After a write() method returned false, this event is emitted to\nindicate that it is safe to write again.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "desc": "

function (exception) { }\n\n

\n

Emitted on error with the exception exception.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () { }\n\n

\n

Emitted when the underlying file descriptor has been closed.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'pipe'", - "type": "event", - "name": "pipe", - "desc": "

function (src) { }\n\n

\n

Emitted when the stream is passed to a readable stream's pipe method.\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "stream.writable", - "name": "writable", - "desc": "

A boolean that is true by default, but turns false after an 'error'\noccurred or end() / destroy() was called.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "stream.write(string, [encoding], [fd])", - "type": "method", - "name": "write", - "desc": "

Writes string with the given encoding to the stream. Returns true if\nthe string has been flushed to the kernel buffer. Returns false to\nindicate that the kernel buffer is full, and the data will be sent out in\nthe future. The 'drain' event will indicate when the kernel buffer is\nempty again. The encoding defaults to 'utf8'.\n\n

\n

If the optional fd parameter is specified, it is interpreted as an integral\nfile descriptor to be sent over the stream. This is only supported for UNIX\nstreams, and is silently ignored otherwise. When writing a file descriptor in\nthis manner, closing the descriptor before the stream drains risks sending an\ninvalid (closed) FD.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "string" - }, - { - "name": "encoding", - "optional": true - }, - { - "name": "fd", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "stream.write(buffer)", - "type": "method", - "name": "write", - "desc": "

Same as the above except with a raw buffer.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buffer" - } - ] - } - ] - }, - { - "textRaw": "stream.end()", - "type": "method", - "name": "end", - "desc": "

Terminates the stream with EOF or FIN.\nThis call will allow queued write data to be sent before closing the stream.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "stream.end(string, encoding)", - "type": "method", - "name": "end", - "desc": "

Sends string with the given encoding and terminates the stream with EOF\nor FIN. This is useful to reduce the number of packets sent.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "string" - }, - { - "name": "encoding" - } - ] - } - ] - }, - { - "textRaw": "stream.end(buffer)", - "type": "method", - "name": "end", - "desc": "

Same as above but with a buffer.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buffer" - } - ] - } - ] - }, - { - "textRaw": "stream.destroy()", - "type": "method", - "name": "destroy", - "desc": "

Closes the underlying file descriptor. Stream will not emit any more events.\nAny queued write data will not be sent.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "stream.destroySoon()", - "type": "method", - "name": "destroySoon", - "desc": "

After the write queue is drained, close the file descriptor. destroySoon()\ncan still destroy straight away, as long as there is no data left in the queue\nfor writes.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - } - ], - "type": "module", - "displayName": "Stream" - }, - { - "textRaw": "Crypto", - "name": "crypto", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Use require('crypto') to access this module.\n\n

\n

The crypto module requires OpenSSL to be available on the underlying platform.\nIt offers a way of encapsulating secure credentials to be used as part\nof a secure HTTPS net or http connection.\n\n

\n

It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods.\n\n

\n", - "methods": [ - { - "textRaw": "crypto.createCredentials(details)", - "type": "method", - "name": "createCredentials", - "desc": "

Creates a credentials object, with the optional details being a dictionary with keys:\n\n

\n
    \n
  • pfx : A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
    • \n
  • key : a string holding the PEM encoded private key
    • \n
  • cert : a string holding the PEM encoded certificate
    • \n
  • passphrase : A string of passphrase for the private key or pfx
    • \n
  • ca : either a string or list of strings of PEM encoded CA certificates to trust.
    • \n
  • ciphers: a string describing the ciphers to use or exclude. Consult\nhttp://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details\non the format.
    • \n
\n

If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in\n

\n

http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "details" - } - ] - } - ] - }, - { - "textRaw": "crypto.createHash(algorithm)", - "type": "method", - "name": "createHash", - "desc": "

Creates and returns a hash object, a cryptographic hash with the given algorithm\nwhich can be used to generate hash digests.\n\n

\n

algorithm is dependent on the available algorithms supported by the version\nof OpenSSL on the platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', etc.\nOn recent releases, openssl list-message-digest-algorithms will display the available digest algorithms.\n\n

\n

Example: this program that takes the sha1 sum of a file\n\n

\n
var filename = process.argv[2];\nvar crypto = require('crypto');\nvar fs = require('fs');\n\nvar shasum = crypto.createHash('sha1');\n\nvar s = fs.ReadStream(filename);\ns.on('data', function(d) {\n  shasum.update(d);\n});\n\ns.on('end', function() {\n  var d = shasum.digest('hex');\n  console.log(d + '  ' + filename);\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - } - ] - } - ] - }, - { - "textRaw": "crypto.createHmac(algorithm, key)", - "type": "method", - "name": "createHmac", - "desc": "

Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key.\n\n

\n

algorithm is dependent on the available algorithms supported by OpenSSL - see createHash above.\nkey is the hmac key to be used.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - }, - { - "name": "key" - } - ] - } - ] - }, - { - "textRaw": "crypto.createCipher(algorithm, password)", - "type": "method", - "name": "createCipher", - "desc": "

Creates and returns a cipher object, with the given algorithm and password.\n\n

\n

algorithm is dependent on OpenSSL, examples are 'aes192', etc.\nOn recent releases, openssl list-cipher-algorithms will display the\navailable cipher algorithms.\npassword is used to derive key and IV, which must be 'binary' encoded\nstring (See the Buffer section for more information).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - }, - { - "name": "password" - } - ] - } - ] - }, - { - "textRaw": "crypto.createCipheriv(algorithm, key, iv)", - "type": "method", - "name": "createCipheriv", - "desc": "

Creates and returns a cipher object, with the given algorithm, key and iv.\n\n

\n

algorithm is the same as the createCipher(). key is a raw key used in\nalgorithm. iv is an Initialization vector. key and iv must be 'binary'\nencoded string (See the Buffer section for more information).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - }, - { - "name": "key" - }, - { - "name": "iv" - } - ] - } - ] - }, - { - "textRaw": "crypto.createDecipher(algorithm, password)", - "type": "method", - "name": "createDecipher", - "desc": "

Creates and returns a decipher object, with the given algorithm and key.\nThis is the mirror of the createCipher() above.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - }, - { - "name": "password" - } - ] - } - ] - }, - { - "textRaw": "crypto.createDecipheriv(algorithm, key, iv)", - "type": "method", - "name": "createDecipheriv", - "desc": "

Creates and returns a decipher object, with the given algorithm, key and iv.\nThis is the mirror of the createCipheriv() above.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - }, - { - "name": "key" - }, - { - "name": "iv" - } - ] - } - ] - }, - { - "textRaw": "crypto.createSign(algorithm)", - "type": "method", - "name": "createSign", - "desc": "

Creates and returns a signing object, with the given algorithm.\nOn recent OpenSSL releases, openssl list-public-key-algorithms will display\nthe available signing algorithms. Examples are 'RSA-SHA256'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - } - ] - } - ] - }, - { - "textRaw": "crypto.createVerify(algorithm)", - "type": "method", - "name": "createVerify", - "desc": "

Creates and returns a verification object, with the given algorithm.\nThis is the mirror of the signing object above.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - } - ] - } - ] - }, - { - "textRaw": "crypto.createDiffieHellman(prime_length)", - "type": "method", - "name": "createDiffieHellman", - "desc": "

Creates a Diffie-Hellman key exchange object and generates a prime of the\ngiven bit length. The generator used is 2.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "prime_length" - } - ] - } - ] - }, - { - "textRaw": "crypto.createDiffieHellman(prime, [encoding])", - "type": "method", - "name": "createDiffieHellman", - "desc": "

Creates a Diffie-Hellman key exchange object using the supplied prime. The\ngenerator used is 2. Encoding can be 'binary', 'hex', or 'base64'.\nDefaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "prime" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "crypto.pbkdf2(password, salt, iterations, keylen, callback)", - "type": "method", - "name": "pbkdf2", - "desc": "

Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive\na key of given length from the given password, salt and iterations.\nThe callback gets two arguments (err, derivedKey).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "password" - }, - { - "name": "salt" - }, - { - "name": "iterations" - }, - { - "name": "keylen" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "crypto.randomBytes(size, [callback])", - "type": "method", - "name": "randomBytes", - "desc": "

Generates cryptographically strong pseudo-random data. Usage:\n\n

\n
// async\ncrypto.randomBytes(256, function(ex, buf) {\n  if (ex) throw ex;\n  console.log('Have %d bytes of random data: %s', buf.length, buf);\n});\n\n// sync\ntry {\n  var buf = crypto.randomBytes(256);\n  console.log('Have %d bytes of random data: %s', buf.length, buf);\n} catch (ex) {\n  // handle error\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "size" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: Hash", - "type": "class", - "name": "Hash", - "desc": "

The class for creating hash digests of data.\n\n

\n

Returned by crypto.createHash.\n\n

\n", - "methods": [ - { - "textRaw": "hash.update(data, [input_encoding])", - "type": "method", - "name": "update", - "desc": "

Updates the hash content with the given data, the encoding of which is given\nin input_encoding and can be 'utf8', 'ascii' or 'binary'.\nDefaults to 'binary'.\nThis can be called many times with new data as it is streamed.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - }, - { - "name": "input_encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "hash.digest([encoding])", - "type": "method", - "name": "digest", - "desc": "

Calculates the digest of all of the passed data to be hashed.\nThe encoding can be 'hex', 'binary' or 'base64'.\nDefaults to 'binary'.\n\n

\n

Note: hash object can not be used after digest() method been called.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: Hmac", - "type": "class", - "name": "Hmac", - "desc": "

Class for creating cryptographic hmac content.\n\n

\n

Returned by crypto.createHmac.\n\n

\n", - "methods": [ - { - "textRaw": "hmac.update(data)", - "type": "method", - "name": "update", - "desc": "

Update the hmac content with the given data.\nThis can be called many times with new data as it is streamed.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - } - ] - } - ] - }, - { - "textRaw": "hmac.digest([encoding])", - "type": "method", - "name": "digest", - "desc": "

Calculates the digest of all of the passed data to the hmac.\nThe encoding can be 'hex', 'binary' or 'base64'.\nDefaults to 'binary'.\n\n

\n

Note: hmac object can not be used after digest() method been called.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: Cipher", - "type": "class", - "name": "Cipher", - "desc": "

Class for encrypting data.\n\n

\n

Returned by crypto.createCipher and crypto.createCipheriv.\n\n

\n", - "methods": [ - { - "textRaw": "cipher.update(data, [input_encoding], [output_encoding])", - "type": "method", - "name": "update", - "desc": "

Updates the cipher with data, the encoding of which is given in\ninput_encoding and can be 'utf8', 'ascii' or 'binary'.\nDefaults to 'binary'.\n\n

\n

The output_encoding specifies the output format of the enciphered data,\nand can be 'binary', 'base64' or 'hex'. Defaults to 'binary'.\n\n

\n

Returns the enciphered contents, and can be called many times with new data as it is streamed.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - }, - { - "name": "input_encoding", - "optional": true - }, - { - "name": "output_encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "cipher.final([output_encoding])", - "type": "method", - "name": "final", - "desc": "

Returns any remaining enciphered contents, with output_encoding being one of:\n'binary', 'base64' or 'hex'. Defaults to 'binary'.\n\n

\n

Note: cipher object can not be used after final() method been called.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "output_encoding", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: Decipher", - "type": "class", - "name": "Decipher", - "desc": "

Class for decrypting data.\n\n

\n

Returned by crypto.createDecipher and crypto.createDecipheriv.\n\n

\n", - "methods": [ - { - "textRaw": "decipher.update(data, [input_encoding], [output_encoding])", - "type": "method", - "name": "update", - "desc": "

Updates the decipher with data, which is encoded in 'binary', 'base64'\nor 'hex'. Defaults to 'binary'.\n\n

\n

The output_decoding specifies in what format to return the deciphered\nplaintext: 'binary', 'ascii' or 'utf8'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - }, - { - "name": "input_encoding", - "optional": true - }, - { - "name": "output_encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "decipher.final([output_encoding])", - "type": "method", - "name": "final", - "desc": "

Returns any remaining plaintext which is deciphered,\nwith output_encoding being one of: 'binary', 'ascii' or 'utf8'.\nDefaults to 'binary'.\n\n

\n

Note: decipher object can not be used after final() method been called.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "output_encoding", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: Signer", - "type": "class", - "name": "Signer", - "desc": "

Class for generating signatures.\n\n

\n

Returned by crypto.createSign.\n\n

\n", - "methods": [ - { - "textRaw": "signer.update(data)", - "type": "method", - "name": "update", - "desc": "

Updates the signer object with data.\nThis can be called many times with new data as it is streamed.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - } - ] - } - ] - }, - { - "textRaw": "signer.sign(private_key, [output_format])", - "type": "method", - "name": "sign", - "desc": "

Calculates the signature on all the updated data passed through the signer.\nprivate_key is a string containing the PEM encoded private key for signing.\n\n

\n

Returns the signature in output_format which can be 'binary', 'hex' or\n'base64'. Defaults to 'binary'.\n\n

\n

Note: signer object can not be used after sign() method been called.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "private_key" - }, - { - "name": "output_format", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: Verify", - "type": "class", - "name": "Verify", - "desc": "

Class for verifying signatures.\n\n

\n

Returned by crypto.createVerify.\n\n

\n", - "methods": [ - { - "textRaw": "verifier.update(data)", - "type": "method", - "name": "update", - "desc": "

Updates the verifier object with data.\nThis can be called many times with new data as it is streamed.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - } - ] - } - ] - }, - { - "textRaw": "verifier.verify(object, signature, [signature_format])", - "type": "method", - "name": "verify", - "desc": "

Verifies the signed data by using the object and signature. object is a\nstring containing a PEM encoded object, which can be one of RSA public key,\nDSA public key, or X.509 certificate. signature is the previously calculated\nsignature for the data, in the signature_format which can be 'binary',\n'hex' or 'base64'. Defaults to 'binary'.\n\n

\n

Returns true or false depending on the validity of the signature for the data and public key.\n\n

\n

Note: verifier object can not be used after verify() method been called.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "object" - }, - { - "name": "signature" - }, - { - "name": "signature_format", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: DiffieHellman", - "type": "class", - "name": "DiffieHellman", - "desc": "

The class for creating Diffie-Hellman key exchanges.\n\n

\n

Returned by crypto.createDiffieHellman.\n\n

\n", - "methods": [ - { - "textRaw": "diffieHellman.generateKeys([encoding])", - "type": "method", - "name": "generateKeys", - "desc": "

Generates private and public Diffie-Hellman key values, and returns the\npublic key in the specified encoding. This key should be transferred to the\nother party. Encoding can be 'binary', 'hex', or 'base64'.\nDefaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])", - "type": "method", - "name": "computeSecret", - "desc": "

Computes the shared secret using other_public_key as the other party's\npublic key and returns the computed shared secret. Supplied key is\ninterpreted using specified input_encoding, and secret is encoded using\nspecified output_encoding. Encodings can be 'binary', 'hex', or\n'base64'. The input encoding defaults to 'binary'.\nIf no output encoding is given, the input encoding is used as output encoding.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "other_public_key" - }, - { - "name": "input_encoding", - "optional": true - }, - { - "name": "output_encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.getPrime([encoding])", - "type": "method", - "name": "getPrime", - "desc": "

Returns the Diffie-Hellman prime in the specified encoding, which can be\n'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.getGenerator([encoding])", - "type": "method", - "name": "getGenerator", - "desc": "

Returns the Diffie-Hellman prime in the specified encoding, which can be\n'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.getPublicKey([encoding])", - "type": "method", - "name": "getPublicKey", - "desc": "

Returns the Diffie-Hellman public key in the specified encoding, which can\nbe 'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.getPrivateKey([encoding])", - "type": "method", - "name": "getPrivateKey", - "desc": "

Returns the Diffie-Hellman private key in the specified encoding, which can\nbe 'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.setPublicKey(public_key, [encoding])", - "type": "method", - "name": "setPublicKey", - "desc": "

Sets the Diffie-Hellman public key. Key encoding can be 'binary', 'hex',\nor 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "public_key" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.setPrivateKey(public_key, [encoding])", - "type": "method", - "name": "setPrivateKey", - "desc": "

Sets the Diffie-Hellman private key. Key encoding can be 'binary', 'hex',\nor 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "public_key" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - } - ] - } - ], - "type": "module", - "displayName": "Crypto" - }, - { - "textRaw": "TLS (SSL)", - "name": "tls_(ssl)", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Use require('tls') to access this module.\n\n

\n

The tls module uses OpenSSL to provide Transport Layer Security and/or\nSecure Socket Layer: encrypted stream communication.\n\n

\n

TLS/SSL is a public/private key infrastructure. Each client and each\nserver must have a private key. A private key is created like this\n\n

\n
openssl genrsa -out ryans-key.pem 1024
\n

All severs and some clients need to have a certificate. Certificates are public\nkeys signed by a Certificate Authority or self-signed. The first step to\ngetting a certificate is to create a "Certificate Signing Request" (CSR)\nfile. This is done with:\n\n

\n
openssl req -new -key ryans-key.pem -out ryans-csr.pem
\n

To create a self-signed certificate with the CSR, do this:\n\n

\n
openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem
\n

Alternatively you can send the CSR to a Certificate Authority for signing.\n\n

\n

(TODO: docs on creating a CA, for now interested users should just look at\ntest/fixtures/keys/Makefile in the Node source code)\n\n

\n

To create .pfx or .p12, do this:\n\n

\n
openssl pkcs12 -export -in agent5-cert.pem -inkey agent5-key.pem \\\n    -certfile ca-cert.pem -out agent5.pfx
\n
    \n
  • in: certificate
    • \n
  • inkey: private key
    • \n
  • certfile: all CA certs concatenated in one file like\ncat ca1-cert.pem ca2-cert.pem > ca-cert.pem
    • \n
\n", - "miscs": [ - { - "textRaw": "Client-initiated renegotiation attack mitigation", - "name": "Client-initiated renegotiation attack mitigation", - "type": "misc", - "desc": "

The TLS protocol lets the client renegotiate certain aspects of the TLS session.\nUnfortunately, session renegotiation requires a disproportional amount of\nserver-side resources, which makes it a potential vector for denial-of-service\nattacks.\n\n

\n

To mitigate this, renegotiations are limited to three times every 10 minutes. An\nerror is emitted on the CleartextStream instance when\nthe threshold is exceeded. The limits are configurable:\n\n

\n
    \n

  • tls.CLIENT_RENEG_LIMIT: renegotiation limit, default is 3.

    \n
    • \n

  • tls.CLIENT_RENEG_WINDOW: renegotiation window in seconds, default is

    \n
                           10 minutes.
    \n
    • \n
\n

Don't change the defaults unless you know what you are doing.\n\n

\n

To test your server, connect to it with openssl s_client -connect address:port\nand tap R<CR> (that's the letter R followed by a carriage return) a few\ntimes.\n\n\n

\n" - }, - { - "textRaw": "NPN and SNI", - "name": "NPN and SNI", - "type": "misc", - "desc": "

NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS\nhandshake extensions allowing you:\n\n

\n
    \n
  • NPN - to use one TLS server for multiple protocols (HTTP, SPDY)
    • \n
  • SNI - to use one TLS server for multiple hostnames with different SSL\ncertificates.
    • \n
\n" - } - ], - "methods": [ - { - "textRaw": "tls.createServer(options, [secureConnectionListener])", - "type": "method", - "name": "createServer", - "desc": "

Creates a new tls.Server.\nThe connectionListener argument is automatically set as a listener for the\nsecureConnection event.\nThe options object has these possibilities:\n\n

\n
    \n

  • pfx: A string or Buffer containing the private key, certificate and\nCA certs of the server in PFX or PKCS12 format. (Mutually exclusive with\nthe key, cert and ca options.)

    \n
    • \n

  • key: A string or Buffer containing the private key of the server in\nPEM format. (Required)

    \n
    • \n

  • passphrase: A string of passphrase for the private key or pfx.

    \n
    • \n

  • cert: A string or Buffer containing the certificate key of the server in\nPEM format. (Required)

    \n
    • \n

  • ca: An array of strings or Buffers of trusted certificates. If this is\nomitted several well known "root" CAs will be used, like VeriSign.\nThese are used to authorize connections.

    \n
    • \n

  • ciphers: A string describing the ciphers to use or exclude. Consult\nhttp://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for\ndetails on the format.

    \n
    • \n

  • requestCert: If true the server will request a certificate from\nclients that connect and attempt to verify that certificate. Default:\nfalse.

    \n
    • \n

  • rejectUnauthorized: If true the server will reject any connection\nwhich is not authorized with the list of supplied CAs. This option only\nhas an effect if requestCert is true. Default: false.

    \n
    • \n

  • NPNProtocols: An array or Buffer of possible NPN protocols. (Protocols\nshould be ordered by their priority).

    \n
    • \n

  • SNICallback: A function that will be called if client supports SNI TLS\nextension. Only one argument will be passed to it: servername. And\nSNICallback should return SecureContext instance.\n(You can use crypto.createCredentials(...).context to get proper\nSecureContext). If SNICallback wasn't provided - default callback with\nhigh-level API will be used (see below).

    \n
    • \n

  • sessionIdContext: A string containing a opaque identifier for session\nresumption. If requestCert is true, the default is MD5 hash value\ngenerated from command-line. Otherwise, the default is not provided.

    \n
    • \n
\n

Here is a simple example echo server:\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  key: fs.readFileSync('server-key.pem'),\n  cert: fs.readFileSync('server-cert.pem'),\n\n  // This is necessary only if using the client certificate authentication.\n  requestCert: true,\n\n  // This is necessary only if the client uses the self-signed certificate.\n  ca: [ fs.readFileSync('client-cert.pem') ]\n};\n\nvar server = tls.createServer(options, function(cleartextStream) {\n  console.log('server connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  cleartextStream.write("welcome!\\n");\n  cleartextStream.setEncoding('utf8');\n  cleartextStream.pipe(cleartextStream);\n});\nserver.listen(8000, function() {\n  console.log('server bound');\n});
\n

Or\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('server.pfx'),\n\n  // This is necessary only if using the client certificate authentication.\n  requestCert: true,\n\n};\n\nvar server = tls.createServer(options, function(cleartextStream) {\n  console.log('server connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  cleartextStream.write("welcome!\\n");\n  cleartextStream.setEncoding('utf8');\n  cleartextStream.pipe(cleartextStream);\n});\nserver.listen(8000, function() {\n  console.log('server bound');\n});
\n

You can test this server by connecting to it with openssl s_client:\n\n\n

\n
openssl s_client -connect 127.0.0.1:8000
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "secureConnectionListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "tls.connect(port, [host], [options], [secureConnectListener])", - "type": "method", - "name": "connect", - "desc": "

Creates a new client connection to the given port and host. (If host\ndefaults to localhost.) options should be an object which specifies\n\n

\n
    \n

  • pfx: A string or Buffer containing the private key, certificate and\nCA certs of the server in PFX or PKCS12 format.

    \n
    • \n

  • key: A string or Buffer containing the private key of the client in\nPEM format.

    \n
    • \n

  • passphrase: A string of passphrase for the private key or pfx.

    \n
    • \n

  • cert: A string or Buffer containing the certificate key of the client in\nPEM format.

    \n
    • \n

  • ca: An array of strings or Buffers of trusted certificates. If this is\nomitted several well known "root" CAs will be used, like VeriSign.\nThese are used to authorize connections.

    \n
    • \n

  • NPNProtocols: An array of string or Buffer containing supported NPN\nprotocols. Buffer should have following format: 0x05hello0x05world,\nwhere first byte is next protocol name's length. (Passing array should\nusually be much simpler: ['hello', 'world'].)

    \n
    • \n

  • servername: Servername for SNI (Server Name Indication) TLS extension.

    \n
    • \n

  • socket: Establish secure connection on a given socket rather than\ncreating a new socket. If this option is specified, host and port\nare ignored. This is intended FOR INTERNAL USE ONLY. As with all\nundocumented APIs in Node, they should not be used.

    \n
    • \n
\n

The secureConnectListener parameter will be added as a listener for the\n'secureConnect' event.\n\n

\n

tls.connect() returns a CleartextStream object.\n\n

\n

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

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  // These are necessary only if using the client certificate authentication\n  key: fs.readFileSync('client-key.pem'),\n  cert: fs.readFileSync('client-cert.pem'),\n\n  // This is necessary only if the server uses the self-signed certificate\n  ca: [ fs.readFileSync('server-cert.pem') ]\n};\n\nvar cleartextStream = tls.connect(8000, options, function() {\n  console.log('client connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  process.stdin.pipe(cleartextStream);\n  process.stdin.resume();\n});\ncleartextStream.setEncoding('utf8');\ncleartextStream.on('data', function(data) {\n  console.log(data);\n});\ncleartextStream.on('end', function() {\n  server.close();\n});
\n

Or\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('client.pfx')\n};\n\nvar cleartextStream = tls.connect(8000, options, function() {\n  console.log('client connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  process.stdin.pipe(cleartextStream);\n  process.stdin.resume();\n});\ncleartextStream.setEncoding('utf8');\ncleartextStream.on('data', function(data) {\n  console.log(data);\n});\ncleartextStream.on('end', function() {\n  server.close();\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "port" - }, - { - "name": "host", - "optional": true - }, - { - "name": "options", - "optional": true - }, - { - "name": "secureConnectListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])", - "type": "method", - "name": "createSecurePair", - "desc": "

Creates a new secure pair object with two streams, one of which reads/writes\nencrypted data, and one reads/writes cleartext data.\nGenerally the encrypted one is piped to/from an incoming encrypted data stream,\nand the cleartext one is used as a replacement for the initial encrypted stream.\n\n

\n
    \n

  • credentials: A credentials object from crypto.createCredentials( ... )

    \n
    • \n

  • isServer: A boolean indicating whether this tls connection should be\nopened as a server or a client.

    \n
    • \n

  • requestCert: A boolean indicating whether a server should request a\ncertificate from a connecting client. Only applies to server connections.

    \n
    • \n

  • rejectUnauthorized: A boolean indicating whether a server should\nautomatically reject clients with invalid certificates. Only applies to\nservers with requestCert enabled.

    \n
    • \n
\n

tls.createSecurePair() returns a SecurePair object with\ncleartext and encrypted stream properties.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "credentials", - "optional": true - }, - { - "name": "isServer", - "optional": true - }, - { - "name": "requestCert", - "optional": true - }, - { - "name": "rejectUnauthorized", - "optional": true - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: SecurePair", - "type": "class", - "name": "SecurePair", - "desc": "

Returned by tls.createSecurePair.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'secure'", - "type": "event", - "name": "secure", - "desc": "

The event is emitted from the SecurePair once the pair has successfully\nestablished a secure connection.\n\n

\n

Similarly to the checking for the server 'secureConnection' event,\npair.cleartext.authorized should be checked to confirm whether the certificate\nused properly authorized.\n\n

\n", - "params": [] - } - ] - }, - { - "textRaw": "Class: tls.Server", - "type": "class", - "name": "tls.Server", - "desc": "

This class is a subclass of net.Server and has the same methods on it.\nInstead of accepting just raw TCP connections, this accepts encrypted\nconnections using TLS or SSL.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'secureConnection'", - "type": "event", - "name": "secureConnection", - "desc": "

function (cleartextStream) {}\n\n

\n

This event is emitted after a new connection has been successfully\nhandshaked. The argument is a instance of\nCleartextStream. It has all the common stream methods\nand events.\n\n

\n

cleartextStream.authorized is a boolean value which indicates if the\nclient has verified by one of the supplied certificate authorities for the\nserver. If cleartextStream.authorized is false, then\ncleartextStream.authorizationError is set to describe how authorization\nfailed. Implied but worth mentioning: depending on the settings of the TLS\nserver, you unauthorized connections may be accepted.\ncleartextStream.npnProtocol is a string containing selected NPN protocol.\ncleartextStream.servername is a string containing servername requested with\nSNI.\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'clientError'", - "type": "event", - "name": "clientError", - "desc": "

function (exception) { }\n\n

\n

When a client connection emits an 'error' event before secure connection is\nestablished - it will be forwarded here.\n\n\n

\n", - "params": [] - } - ], - "methods": [ - { - "textRaw": "server.listen(port, [host], [callback])", - "type": "method", - "name": "listen", - "desc": "

Begin accepting connections on the specified port and host. If the\nhost is omitted, the server will accept connections directed to any\nIPv4 address (INADDR_ANY).\n\n

\n

This function is asynchronous. The last parameter callback will be called\nwhen the server has been bound.\n\n

\n

See net.Server for more information.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "port" - }, - { - "name": "host", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "server.close()", - "type": "method", - "name": "close", - "desc": "

Stops the server from accepting new connections. This function is\nasynchronous, the server is finally closed when the server emits a 'close'\nevent.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "server.address()", - "type": "method", - "name": "address", - "desc": "

Returns the bound address and port of the server as reported by the operating\nsystem.\nSee net.Server.address() for more information.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "server.addContext(hostname, credentials)", - "type": "method", - "name": "addContext", - "desc": "

Add secure context that will be used if client request's SNI hostname is\nmatching passed hostname (wildcards can be used). credentials can contain\nkey, cert and ca.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "hostname" - }, - { - "name": "credentials" - } - ] - } - ] - } - ], - "properties": [ - { - "textRaw": "server.maxConnections", - "name": "maxConnections", - "desc": "

Set this property to reject connections when the server's connection count\ngets high.\n\n

\n" - }, - { - "textRaw": "server.connections", - "name": "connections", - "desc": "

The number of concurrent connections on the server.\n\n\n

\n" - } - ] - }, - { - "textRaw": "Class: tls.CleartextStream", - "type": "class", - "name": "tls.CleartextStream", - "desc": "

This is a stream on top of the Encrypted stream that makes it possible to\nread/write an encrypted data as a cleartext data.\n\n

\n

This instance implements a duplex Stream interfaces.\nIt has all the common stream methods and events.\n\n

\n

A ClearTextStream is the clear member of a SecurePair object.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'secureConnect'", - "type": "event", - "name": "secureConnect", - "desc": "

This event is emitted after a new connection has been successfully handshaked. \nThe listener will be called no matter if the server's certificate was\nauthorized or not. It is up to the user to test cleartextStream.authorized\nto see if the server certificate was signed by one of the specified CAs.\nIf cleartextStream.authorized === false then the error can be found in\ncleartextStream.authorizationError. Also if NPN was used - you can check\ncleartextStream.npnProtocol for negotiated protocol.\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "cleartextStream.authorized", - "name": "authorized", - "desc": "

A boolean that is true if the peer certificate was signed by one of the\nspecified CAs, otherwise false\n\n

\n" - }, - { - "textRaw": "cleartextStream.authorizationError", - "name": "authorizationError", - "desc": "

The reason why the peer's certificate has not been verified. This property\nbecomes available only when cleartextStream.authorized === false.\n\n

\n" - }, - { - "textRaw": "cleartextStream.remoteAddress", - "name": "remoteAddress", - "desc": "

The string representation of the remote IP address. For example,\n'74.125.127.100' or '2001:4860:a005::68'.\n\n

\n" - }, - { - "textRaw": "cleartextStream.remotePort", - "name": "remotePort", - "desc": "

The numeric representation of the remote port. For example, 443.\n\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "cleartextStream.getPeerCertificate()", - "type": "method", - "name": "getPeerCertificate", - "desc": "

Returns an object representing the peer's certificate. The returned object has\nsome properties corresponding to the field of the certificate.\n\n

\n

Example:\n\n

\n
{ subject: \n   { C: 'UK',\n     ST: 'Acknack Ltd',\n     L: 'Rhys Jones',\n     O: 'node.js',\n     OU: 'Test TLS Certificate',\n     CN: 'localhost' },\n  issuer: \n   { C: 'UK',\n     ST: 'Acknack Ltd',\n     L: 'Rhys Jones',\n     O: 'node.js',\n     OU: 'Test TLS Certificate',\n     CN: 'localhost' },\n  valid_from: 'Nov 11 09:52:22 2009 GMT',\n  valid_to: 'Nov  6 09:52:22 2029 GMT',\n  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF' }
\n

If the peer does not provide a certificate, it returns null or an empty\nobject.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "cleartextStream.address()", - "type": "method", - "name": "address", - "desc": "

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

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - } - ], - "type": "module", - "displayName": "TLS (SSL)" - }, - { - "textRaw": "File System", - "name": "fs", - "stability": 3, - "stabilityText": "Stable", - "desc": "

File I/O is provided by simple wrappers around standard POSIX functions. To\nuse this module do require('fs'). All the methods have asynchronous and\nsynchronous forms.\n\n

\n

The asynchronous form always take a completion callback as its last argument.\nThe arguments passed to the completion callback depend on the method, but the\nfirst argument is always reserved for an exception. If the operation was\ncompleted successfully, then the first argument will be null or undefined.\n\n

\n

When using the synchronous form any exceptions are immediately thrown.\nYou can use try/catch to handle exceptions or allow them to bubble up.\n\n

\n

Here is an example of the asynchronous version:\n\n

\n
var fs = require('fs');\n\nfs.unlink('/tmp/hello', function (err) {\n  if (err) throw err;\n  console.log('successfully deleted /tmp/hello');\n});
\n

Here is the synchronous version:\n\n

\n
var fs = require('fs');\n\nfs.unlinkSync('/tmp/hello')\nconsole.log('successfully deleted /tmp/hello');
\n

With the asynchronous methods there is no guaranteed ordering. So the\nfollowing is prone to error:\n\n

\n
fs.rename('/tmp/hello', '/tmp/world', function (err) {\n  if (err) throw err;\n  console.log('renamed complete');\n});\nfs.stat('/tmp/world', function (err, stats) {\n  if (err) throw err;\n  console.log('stats: ' + JSON.stringify(stats));\n});
\n

It could be that fs.stat is executed before fs.rename.\nThe correct way to do this is to chain the callbacks.\n\n

\n
fs.rename('/tmp/hello', '/tmp/world', function (err) {\n  if (err) throw err;\n  fs.stat('/tmp/world', function (err, stats) {\n    if (err) throw err;\n    console.log('stats: ' + JSON.stringify(stats));\n  });\n});
\n

In busy processes, the programmer is strongly encouraged to use the\nasynchronous versions of these calls. The synchronous versions will block\nthe entire process until they complete--halting all connections.\n\n

\n

Relative path to filename can be used, remember however that this path will be relative\nto process.cwd().\n\n

\n", - "methods": [ - { - "textRaw": "fs.rename(path1, path2, [callback])", - "type": "method", - "name": "rename", - "desc": "

Asynchronous rename(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path1" - }, - { - "name": "path2" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.renameSync(path1, path2)", - "type": "method", - "name": "renameSync", - "desc": "

Synchronous rename(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path1" - }, - { - "name": "path2" - } - ] - } - ] - }, - { - "textRaw": "fs.truncate(fd, len, [callback])", - "type": "method", - "name": "truncate", - "desc": "

Asynchronous ftruncate(2). No arguments other than a possible exception are\ngiven to the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "len" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.truncateSync(fd, len)", - "type": "method", - "name": "truncateSync", - "desc": "

Synchronous ftruncate(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "len" - } - ] - } - ] - }, - { - "textRaw": "fs.chown(path, uid, gid, [callback])", - "type": "method", - "name": "chown", - "desc": "

Asynchronous chown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "uid" - }, - { - "name": "gid" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.chownSync(path, uid, gid)", - "type": "method", - "name": "chownSync", - "desc": "

Synchronous chown(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "uid" - }, - { - "name": "gid" - } - ] - } - ] - }, - { - "textRaw": "fs.fchown(fd, uid, gid, [callback])", - "type": "method", - "name": "fchown", - "desc": "

Asynchronous fchown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "uid" - }, - { - "name": "gid" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.fchownSync(fd, uid, gid)", - "type": "method", - "name": "fchownSync", - "desc": "

Synchronous fchown(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "uid" - }, - { - "name": "gid" - } - ] - } - ] - }, - { - "textRaw": "fs.lchown(path, uid, gid, [callback])", - "type": "method", - "name": "lchown", - "desc": "

Asynchronous lchown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "uid" - }, - { - "name": "gid" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.lchownSync(path, uid, gid)", - "type": "method", - "name": "lchownSync", - "desc": "

Synchronous lchown(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "uid" - }, - { - "name": "gid" - } - ] - } - ] - }, - { - "textRaw": "fs.chmod(path, mode, [callback])", - "type": "method", - "name": "chmod", - "desc": "

Asynchronous chmod(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.chmodSync(path, mode)", - "type": "method", - "name": "chmodSync", - "desc": "

Synchronous chmod(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode" - } - ] - } - ] - }, - { - "textRaw": "fs.fchmod(fd, mode, [callback])", - "type": "method", - "name": "fchmod", - "desc": "

Asynchronous fchmod(2). No arguments other than a possible exception\nare given to the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "mode" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.fchmodSync(fd, mode)", - "type": "method", - "name": "fchmodSync", - "desc": "

Synchronous fchmod(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "mode" - } - ] - } - ] - }, - { - "textRaw": "fs.lchmod(path, mode, [callback])", - "type": "method", - "name": "lchmod", - "desc": "

Asynchronous lchmod(2). No arguments other than a possible exception\nare given to the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.lchmodSync(path, mode)", - "type": "method", - "name": "lchmodSync", - "desc": "

Synchronous lchmod(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode" - } - ] - } - ] - }, - { - "textRaw": "fs.stat(path, [callback])", - "type": "method", - "name": "stat", - "desc": "

Asynchronous stat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. See the fs.Stats\nsection below for more information.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.lstat(path, [callback])", - "type": "method", - "name": "lstat", - "desc": "

Asynchronous lstat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. lstat() is identical to stat(), except that if\npath is a symbolic link, then the link itself is stat-ed, not the file that it\nrefers to.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.fstat(fd, [callback])", - "type": "method", - "name": "fstat", - "desc": "

Asynchronous fstat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. fstat() is identical to stat(), except that\nthe file to be stat-ed is specified by the file descriptor fd.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.statSync(path)", - "type": "method", - "name": "statSync", - "desc": "

Synchronous stat(2). Returns an instance of fs.Stats.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.lstatSync(path)", - "type": "method", - "name": "lstatSync", - "desc": "

Synchronous lstat(2). Returns an instance of fs.Stats.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.fstatSync(fd)", - "type": "method", - "name": "fstatSync", - "desc": "

Synchronous fstat(2). Returns an instance of fs.Stats.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - } - ] - } - ] - }, - { - "textRaw": "fs.link(srcpath, dstpath, [callback])", - "type": "method", - "name": "link", - "desc": "

Asynchronous link(2). No arguments other than a possible exception are given to\nthe completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "srcpath" - }, - { - "name": "dstpath" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.linkSync(srcpath, dstpath)", - "type": "method", - "name": "linkSync", - "desc": "

Synchronous link(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "srcpath" - }, - { - "name": "dstpath" - } - ] - } - ] - }, - { - "textRaw": "fs.symlink(linkdata, path, [type], [callback])", - "type": "method", - "name": "symlink", - "desc": "

Asynchronous symlink(2). No arguments other than a possible exception are given\nto the completion callback.\ntype argument can be either 'dir' or 'file' (default is 'file'). It is only \nused on Windows (ignored on other platforms).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "linkdata" - }, - { - "name": "path" - }, - { - "name": "type", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.symlinkSync(linkdata, path, [type])", - "type": "method", - "name": "symlinkSync", - "desc": "

Synchronous symlink(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "linkdata" - }, - { - "name": "path" - }, - { - "name": "type", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readlink(path, [callback])", - "type": "method", - "name": "readlink", - "desc": "

Asynchronous readlink(2). The callback gets two arguments (err,\nlinkString).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readlinkSync(path)", - "type": "method", - "name": "readlinkSync", - "desc": "

Synchronous readlink(2). Returns the symbolic link's string value.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.realpath(path, [callback])", - "type": "method", - "name": "realpath", - "desc": "

Asynchronous realpath(2). The callback gets two arguments (err,\nresolvedPath). May use process.cwd to resolve relative paths.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.realpathSync(path)", - "type": "method", - "name": "realpathSync", - "desc": "

Synchronous realpath(2). Returns the resolved path.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.unlink(path, [callback])", - "type": "method", - "name": "unlink", - "desc": "

Asynchronous unlink(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.unlinkSync(path)", - "type": "method", - "name": "unlinkSync", - "desc": "

Synchronous unlink(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.rmdir(path, [callback])", - "type": "method", - "name": "rmdir", - "desc": "

Asynchronous rmdir(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.rmdirSync(path)", - "type": "method", - "name": "rmdirSync", - "desc": "

Synchronous rmdir(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.mkdir(path, [mode], [callback])", - "type": "method", - "name": "mkdir", - "desc": "

Asynchronous mkdir(2). No arguments other than a possible exception are given\nto the completion callback. mode defaults to 0777.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.mkdirSync(path, [mode])", - "type": "method", - "name": "mkdirSync", - "desc": "

Synchronous mkdir(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readdir(path, [callback])", - "type": "method", - "name": "readdir", - "desc": "

Asynchronous readdir(3). Reads the contents of a directory.\nThe callback gets two arguments (err, files) where files is an array of\nthe names of the files in the directory excluding '.' and '..'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readdirSync(path)", - "type": "method", - "name": "readdirSync", - "desc": "

Synchronous readdir(3). Returns an array of filenames excluding '.' and\n'..'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.close(fd, [callback])", - "type": "method", - "name": "close", - "desc": "

Asynchronous close(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.closeSync(fd)", - "type": "method", - "name": "closeSync", - "desc": "

Synchronous close(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - } - ] - } - ] - }, - { - "textRaw": "fs.open(path, flags, [mode], [callback])", - "type": "method", - "name": "open", - "desc": "

Asynchronous file open. See open(2). flags can be:\n\n

\n
    \n

  • 'r' - Open file for reading.\nAn exception occurs if the file does not exist.

    \n
    • \n

  • 'r+' - Open file for reading and writing.\nAn exception occurs if the file does not exist.

    \n
    • \n

  • 'w' - Open file for writing.\nThe file is created (if it does not exist) or truncated (if it exists).

    \n
    • \n

  • 'w+' - Open file for reading and writing.\nThe file is created (if it does not exist) or truncated (if it exists).

    \n
    • \n

  • 'a' - Open file for appending.\nThe file is created if it does not exist.

    \n
    • \n

  • 'a+' - Open file for reading and appending.\nThe file is created if it does not exist.

    \n
    • \n
\n

mode defaults to 0666. The callback gets two arguments (err, fd).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "flags" - }, - { - "name": "mode", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.openSync(path, flags, [mode])", - "type": "method", - "name": "openSync", - "desc": "

Synchronous open(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "flags" - }, - { - "name": "mode", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.utimes(path, atime, mtime, [callback])", - "type": "method", - "name": "utimes", - "desc": "

Change file timestamps of the file referenced by the supplied path.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "atime" - }, - { - "name": "mtime" - } - ] - }, - { - "params": [ - { - "name": "path" - }, - { - "name": "atime" - }, - { - "name": "mtime" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.utimesSync(path, atime, mtime)", - "type": "method", - "name": "utimesSync", - "desc": "

Change file timestamps of the file referenced by the supplied path.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "atime" - }, - { - "name": "mtime" - } - ] - } - ] - }, - { - "textRaw": "fs.futimes(fd, atime, mtime, [callback])", - "type": "method", - "name": "futimes", - "desc": "

Change the file timestamps of a file referenced by the supplied file\ndescriptor.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "atime" - }, - { - "name": "mtime" - } - ] - }, - { - "params": [ - { - "name": "fd" - }, - { - "name": "atime" - }, - { - "name": "mtime" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.futimesSync(fd, atime, mtime)", - "type": "method", - "name": "futimesSync", - "desc": "

Change the file timestamps of a file referenced by the supplied file\ndescriptor.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "atime" - }, - { - "name": "mtime" - } - ] - } - ] - }, - { - "textRaw": "fs.fsync(fd, [callback])", - "type": "method", - "name": "fsync", - "desc": "

Asynchronous fsync(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.fsyncSync(fd)", - "type": "method", - "name": "fsyncSync", - "desc": "

Synchronous fsync(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - } - ] - } - ] - }, - { - "textRaw": "fs.write(fd, buffer, offset, length, position, [callback])", - "type": "method", - "name": "write", - "desc": "

Write buffer to the file specified by fd.\n\n

\n

offset and length determine the part of the buffer to be written.\n\n

\n

position refers to the offset from the beginning of the file where this data\nshould be written. If position is null, the data will be written at the\ncurrent position.\nSee pwrite(2).\n\n

\n

The callback will be given three arguments (err, written, buffer) where written\nspecifies how many bytes were written from buffer.\n\n

\n

Note that it is unsafe to use fs.write multiple times on the same file\nwithout waiting for the callback. For this scenario,\nfs.createWriteStream is strongly recommended.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "buffer" - }, - { - "name": "offset" - }, - { - "name": "length" - }, - { - "name": "position" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.writeSync(fd, buffer, offset, length, position)", - "type": "method", - "name": "writeSync", - "desc": "

Synchronous version of buffer-based fs.write(). Returns the number of bytes\nwritten.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "buffer" - }, - { - "name": "offset" - }, - { - "name": "length" - }, - { - "name": "position" - } - ] - } - ] - }, - { - "textRaw": "fs.writeSync(fd, str, position, [encoding])", - "type": "method", - "name": "writeSync", - "desc": "

Synchronous version of string-based fs.write(). encoding defaults to\n'utf8'. Returns the number of bytes written.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "str" - }, - { - "name": "position" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.read(fd, buffer, offset, length, position, [callback])", - "type": "method", - "name": "read", - "desc": "

Read data from the file specified by fd.\n\n

\n

buffer is the buffer that the data will be written to.\n\n

\n

offset is offset within the buffer where writing will start.\n\n

\n

length is an integer specifying the number of bytes to read.\n\n

\n

position is an integer specifying where to begin reading from in the file.\nIf position is null, data will be read from the current file position.\n\n

\n

The callback is given the three arguments, (err, bytesRead, buffer).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "buffer" - }, - { - "name": "offset" - }, - { - "name": "length" - }, - { - "name": "position" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readSync(fd, buffer, offset, length, position)", - "type": "method", - "name": "readSync", - "desc": "

Synchronous version of buffer-based fs.read. Returns the number of\nbytesRead.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "buffer" - }, - { - "name": "offset" - }, - { - "name": "length" - }, - { - "name": "position" - } - ] - } - ] - }, - { - "textRaw": "fs.readSync(fd, length, position, encoding)", - "type": "method", - "name": "readSync", - "desc": "

Synchronous version of string-based fs.read. Returns the number of\nbytesRead.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "length" - }, - { - "name": "position" - }, - { - "name": "encoding" - } - ] - } - ] - }, - { - "textRaw": "fs.readFile(filename, [encoding], [callback])", - "type": "method", - "name": "readFile", - "desc": "

Asynchronously reads the entire contents of a file. Example:\n\n

\n
fs.readFile('/etc/passwd', function (err, data) {\n  if (err) throw err;\n  console.log(data);\n});
\n

The callback is passed two arguments (err, data), where data is the\ncontents of the file.\n\n

\n

If no encoding is specified, then the raw buffer is returned.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "encoding", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readFileSync(filename, [encoding])", - "type": "method", - "name": "readFileSync", - "desc": "

Synchronous version of fs.readFile. Returns the contents of the filename.\n\n

\n

If encoding is specified then this function returns a string. Otherwise it\nreturns a buffer.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.writeFile(filename, data, [encoding], [callback])", - "type": "method", - "name": "writeFile", - "desc": "

Asynchronously writes data to a file, replacing the file if it already exists.\ndata can be a string or a buffer. The encoding argument is ignored if\ndata is a buffer. It defaults to 'utf8'.\n\n

\n

Example:\n\n

\n
fs.writeFile('message.txt', 'Hello Node', function (err) {\n  if (err) throw err;\n  console.log('It\\'s saved!');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "data" - }, - { - "name": "encoding", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.writeFileSync(filename, data, [encoding])", - "type": "method", - "name": "writeFileSync", - "desc": "

The synchronous version of fs.writeFile.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "data" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.watchFile(filename, [options], listener)", - "type": "method", - "name": "watchFile", - "stability": 2, - "stabilityText": "Unstable. Use fs.watch instead, if available.", - "desc": "

Watch for changes on filename. The callback listener will be called each\ntime the file is accessed.\n\n

\n

The second argument is optional. The options if provided should be an object\ncontaining two members a boolean, persistent, and interval. persistent\nindicates whether the process should continue to run as long as files are\nbeing watched. interval indicates how often the target should be polled,\nin milliseconds. (On Linux systems with inotify, interval is ignored.) The\ndefault is { persistent: true, interval: 0 }.\n\n

\n

The listener gets two arguments the current stat object and the previous\nstat object:\n\n

\n
fs.watchFile('message.text', function (curr, prev) {\n  console.log('the current mtime is: ' + curr.mtime);\n  console.log('the previous mtime was: ' + prev.mtime);\n});
\n

These stat objects are instances of fs.Stat.\n\n

\n

If you want to be notified when the file was modified, not just accessed\nyou need to compare curr.mtime and prev.mtime.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "options", - "optional": true - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "fs.unwatchFile(filename)", - "type": "method", - "name": "unwatchFile", - "stability": 2, - "stabilityText": "Unstable. Use fs.watch instead, if available.", - "desc": "

Stop watching for changes on filename.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - } - ] - } - ] - }, - { - "textRaw": "fs.watch(filename, [options], listener)", - "type": "method", - "name": "watch", - "stability": 2, - "stabilityText": "Unstable. Not available on all platforms.", - "desc": "

Watch for changes on filename, where filename is either a file or a\ndirectory. The returned object is a fs.FSWatcher.\n\n

\n

The second argument is optional. The options if provided should be an object\ncontaining a boolean member persistent, which indicates whether the process\nshould continue to run as long as files are being watched. The default is\n{ persistent: true }.\n\n

\n

The listener callback gets two arguments (event, filename). event is either\n'rename' or 'change', and filename is the name of the file which triggered\nthe event.\n\n

\n", - "miscs": [ - { - "textRaw": "Caveats", - "name": "Caveats", - "type": "misc", - "desc": "

The fs.watch API is not 100% consistent across platforms, and is\nunavailable in some situations.\n\n

\n", - "miscs": [ - { - "textRaw": "Availability", - "name": "Availability", - "type": "misc", - "desc": "

This feature depends on the underlying operating system providing a way\nto be notified of filesystem changes.\n\n

\n
    \n
  • On Linux systems, this uses inotify.
    • \n
  • On BSD systems (including OS X), this uses kqueue.
    • \n
  • On SunOS systems (including Solaris and SmartOS), this uses event ports.
    • \n
  • On Windows systems, this feature depends on ReadDirectoryChangesW.
    • \n
\n

If the underlying functionality is not available for some reason, then\nfs.watch will not be able to function. You can still use\nfs.watchFile, which uses stat polling, but it is slower and less\nreliable.\n\n

\n" - }, - { - "textRaw": "Filename Argument", - "name": "Filename Argument", - "type": "misc", - "desc": "

Providing filename argument in the callback is not supported\non every platform (currently it's only supported on Linux and Windows). Even\non supported platforms filename is not always guaranteed to be provided.\nTherefore, don't assume that filename argument is always provided in the\ncallback, and have some fallback logic if it is null.\n\n

\n
fs.watch('somedir', function (event, filename) {\n  console.log('event is: ' + event);\n  if (filename) {\n    console.log('filename provided: ' + filename);\n  } else {\n    console.log('filename not provided');\n  }\n});
\n" - } - ] - } - ], - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "options", - "optional": true - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "fs.createReadStream(path, [options])", - "type": "method", - "name": "createReadStream", - "desc": "

Returns a new ReadStream object (See Readable Stream).\n\n

\n

options is an object with the following defaults:\n\n

\n
{ flags: 'r',\n  encoding: null,\n  fd: null,\n  mode: 0666,\n  bufferSize: 64 * 1024\n}
\n

options can include start and end values to read a range of bytes from\nthe file instead of the entire file. Both start and end are inclusive and\nstart at 0.\n\n

\n

An example to read the last 10 bytes of a file which is 100 bytes long:\n\n

\n
fs.createReadStream('sample.txt', {start: 90, end: 99});
\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.createWriteStream(path, [options])", - "type": "method", - "name": "createWriteStream", - "desc": "

Returns a new WriteStream object (See Writable Stream).\n\n

\n

options is an object with the following defaults:\n\n

\n
{ flags: 'w',\n  encoding: null,\n  mode: 0666 }
\n

options may also include a start option to allow writing data at\nsome position past the beginning of the file. Modifying a file rather\nthan replacing it may require a flags mode of r+ rather than the\ndefault mode w.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "options", - "optional": true - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: fs.Stats", - "type": "class", - "name": "fs.Stats", - "desc": "

Objects returned from fs.stat(), fs.lstat() and fs.fstat() and their\nsynchronous counterparts are of this type.\n\n

\n
    \n
  • stats.isFile()
    • \n
  • stats.isDirectory()
    • \n
  • stats.isBlockDevice()
    • \n
  • stats.isCharacterDevice()
    • \n
  • stats.isSymbolicLink() (only valid with fs.lstat())
    • \n
  • stats.isFIFO()
    • \n
  • stats.isSocket()
    • \n
\n

For a regular file util.inspect(stats) would return a string very\nsimilar to this:\n\n

\n
{ dev: 2114,\n  ino: 48064969,\n  mode: 33188,\n  nlink: 1,\n  uid: 85,\n  gid: 100,\n  rdev: 0,\n  size: 527,\n  blksize: 4096,\n  blocks: 8,\n  atime: Mon, 10 Oct 2011 23:24:11 GMT,\n  mtime: Mon, 10 Oct 2011 23:24:11 GMT,\n  ctime: Mon, 10 Oct 2011 23:24:11 GMT }
\n

Please note that atime, mtime and ctime are instances\nof [Date][MDN-Date] object and to compare the values of\nthese objects you should use appropriate methods. For most\ngeneral uses [getTime()][MDN-Date-getTime] will return\nthe number of milliseconds elapsed since 1 January 1970\n00:00:00 UTC and this integer should be sufficient for\nany comparison, however there additional methods which can\nbe used for displaying fuzzy information. More details can\nbe found in the [MDN JavaScript Reference][MDN-Date] page.\n\n

\n" - }, - { - "textRaw": "Class: fs.ReadStream", - "type": "class", - "name": "fs.ReadStream", - "desc": "

ReadStream is a Readable Stream.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'open'", - "type": "event", - "name": "open", - "params": [], - "desc": "

Emitted when the ReadStream's file is opened.\n\n\n

\n" - } - ] - }, - { - "textRaw": "Class: fs.FSWatcher", - "type": "class", - "name": "fs.FSWatcher", - "desc": "

Objects returned from fs.watch() are of this type.\n\n

\n", - "methods": [ - { - "textRaw": "watcher.close()", - "type": "method", - "name": "close", - "desc": "

Stop watching for changes on the given fs.FSWatcher.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "events": [ - { - "textRaw": "Event: 'change'", - "type": "event", - "name": "change", - "params": [], - "desc": "

Emitted when something changes in a watched directory or file.\nSee more details in fs.watch.\n\n

\n" - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "params": [], - "desc": "

Emitted when an error occurs.\n\n

\n" - } - ] - } - ], - "properties": [ - { - "textRaw": "fs.WriteStream", - "name": "WriteStream", - "desc": "

WriteStream is a Writable Stream.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'open'", - "type": "event", - "name": "open", - "params": [], - "desc": "

Emitted when the WriteStream's file is opened.\n\n

\n" - } - ], - "properties": [ - { - "textRaw": "file.bytesWritten", - "name": "bytesWritten", - "desc": "

The number of bytes written so far. Does not include data that is still queued\nfor writing.\n\n

\n" - } - ] - } - ], - "type": "module", - "displayName": "fs" - }, - { - "textRaw": "Path", - "name": "path", - "stability": 3, - "stabilityText": "Stable", - "desc": "

This module contains utilities for handling and transforming file\npaths. Almost all these methods perform only string transformations.\nThe file system is not consulted to check whether paths are valid.\n\n

\n

path.exists and path.existsSync are the exceptions, and should\nlogically be found in the fs module as they do access the file system.\n\n

\n

Use require('path') to use this module. The following methods are provided:\n\n

\n", - "methods": [ - { - "textRaw": "path.normalize(p)", - "type": "method", - "name": "normalize", - "desc": "

Normalize a string path, taking care of '..' and '.' parts.\n\n

\n

When multiple slashes are found, they're replaced by a single one;\nwhen the path contains a trailing slash, it is preserved.\nOn windows backslashes are used. \n\n

\n

Example:\n\n

\n
path.normalize('/foo/bar//baz/asdf/quux/..')\n// returns\n'/foo/bar/baz/asdf'
\n", - "signatures": [ - { - "params": [ - { - "name": "p" - } - ] - } - ] - }, - { - "textRaw": "path.join([path1], [path2], [...])", - "type": "method", - "name": "join", - "desc": "

Join all arguments together and normalize the resulting path.\nNon-string arguments are ignored.\n\n

\n

Example:\n\n

\n
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')\n// returns\n'/foo/bar/baz/asdf'\n\npath.join('foo', {}, 'bar')\n// returns\n'foo/bar'
\n", - "signatures": [ - { - "params": [ - { - "name": "path1", - "optional": true - }, - { - "name": "path2", - "optional": true - }, - { - "name": "...", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "path.resolve([from ...], to)", - "type": "method", - "name": "resolve", - "desc": "

Resolves to to an absolute path.\n\n

\n

If to isn't already absolute from arguments are prepended in right to left\norder, until an absolute path is found. If after using all from paths still\nno absolute path is found, the current working directory is used as well. The\nresulting path is normalized, and trailing slashes are removed unless the path \ngets resolved to the root directory. Non-string arguments are ignored.\n\n

\n

Another way to think of it is as a sequence of cd commands in a shell.\n\n

\n
path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
\n

Is similar to:\n\n

\n
cd foo/bar\ncd /tmp/file/\ncd ..\ncd a/../subfile\npwd
\n

The difference is that the different paths don't need to exist and may also be\nfiles.\n\n

\n

Examples:\n\n

\n
path.resolve('/foo/bar', './baz')\n// returns\n'/foo/bar/baz'\n\npath.resolve('/foo/bar', '/tmp/file/')\n// returns\n'/tmp/file'\n\npath.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')\n// if currently in /home/myself/node, it returns\n'/home/myself/node/wwwroot/static_files/gif/image.gif'
\n", - "signatures": [ - { - "params": [ - { - "name": "from ...", - "optional": true - }, - { - "name": "to" - } - ] - } - ] - }, - { - "textRaw": "path.relative(from, to)", - "type": "method", - "name": "relative", - "desc": "

Solve the relative path from from to to.\n\n

\n

At times we have two absolute paths, and we need to derive the relative\npath from one to the other. This is actually the reverse transform of\npath.resolve, which means we see that:\n\n

\n
path.resolve(from, path.relative(from, to)) == path.resolve(to)
\n

Examples:\n\n

\n
path.relative('C:\\\\orandea\\\\test\\\\aaa', 'C:\\\\orandea\\\\impl\\\\bbb')\n// returns\n'..\\\\..\\\\impl\\\\bbb'\n\npath.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')\n// returns\n'../../impl/bbb'
\n", - "signatures": [ - { - "params": [ - { - "name": "from" - }, - { - "name": "to" - } - ] - } - ] - }, - { - "textRaw": "path.dirname(p)", - "type": "method", - "name": "dirname", - "desc": "

Return the directory name of a path. Similar to the Unix dirname command.\n\n

\n

Example:\n\n

\n
path.dirname('/foo/bar/baz/asdf/quux')\n// returns\n'/foo/bar/baz/asdf'
\n", - "signatures": [ - { - "params": [ - { - "name": "p" - } - ] - } - ] - }, - { - "textRaw": "path.basename(p, [ext])", - "type": "method", - "name": "basename", - "desc": "

Return the last portion of a path. Similar to the Unix basename command.\n\n

\n

Example:\n\n

\n
path.basename('/foo/bar/baz/asdf/quux.html')\n// returns\n'quux.html'\n\npath.basename('/foo/bar/baz/asdf/quux.html', '.html')\n// returns\n'quux'
\n", - "signatures": [ - { - "params": [ - { - "name": "p" - }, - { - "name": "ext", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "path.extname(p)", - "type": "method", - "name": "extname", - "desc": "

Return the extension of the path, from the last '.' to end of string\nin the last portion of the path. If there is no '.' in the last portion\nof the path or the first character of it is '.', then it returns\nan empty string. Examples:\n\n

\n
path.extname('index.html')\n// returns\n'.html'\n\npath.extname('index.')\n// returns\n'.'\n\npath.extname('index')\n// returns\n''
\n", - "signatures": [ - { - "params": [ - { - "name": "p" - } - ] - } - ] - }, - { - "textRaw": "path.exists(p, [callback])", - "type": "method", - "name": "exists", - "desc": "

Test whether or not the given path exists by checking with the file system.\nThen call the callback argument with either true or false. Example:\n\n

\n
path.exists('/etc/passwd', function (exists) {\n  util.debug(exists ? "it's there" : "no passwd!");\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "p" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "path.existsSync(p)", - "type": "method", - "name": "existsSync", - "desc": "

Synchronous version of path.exists.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "p" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "Path" - }, - { - "textRaw": "net", - "name": "net", - "stability": 3, - "stabilityText": "Stable", - "desc": "

The net module provides you with an asynchronous network wrapper. It contains\nmethods for creating both servers and clients (called streams). You can include\nthis module with require('net');\n\n

\n", - "methods": [ - { - "textRaw": "net.createServer([options], [connectionListener])", - "type": "method", - "name": "createServer", - "desc": "

Creates a new TCP server. The connectionListener argument is\nautomatically set as a listener for the 'connection'\nevent.\n\n

\n

options is an object with the following defaults:\n\n

\n
{ allowHalfOpen: false\n}
\n

If allowHalfOpen is true, then the socket won't automatically send FIN\npacket when the other end of the socket sends a FIN packet. The socket becomes\nnon-readable, but still writable. You should call the end() method explicitly.\nSee 'end' event for more information.\n\n

\n

Here is an example of a echo server which listens for connections\non port 8124:\n\n

\n
var net = require('net');\nvar server = net.createServer(function(c) { //'connection' listener\n  console.log('server connected');\n  c.on('end', function() {\n    console.log('server disconnected');\n  });\n  c.write('hello\\r\\n');\n  c.pipe(c);\n});\nserver.listen(8124, function() { //'listening' listener\n  console.log('server bound');\n});
\n

Test this by using telnet:\n\n

\n
telnet localhost 8124
\n

To listen on the socket /tmp/echo.sock the third line from the last would\njust be changed to\n\n

\n
server.listen('/tmp/echo.sock', function() { //'listening' listener
\n

Use nc to connect to a UNIX domain socket server:\n\n

\n
nc -U /tmp/echo.sock
\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - }, - { - "name": "connectionListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "net.connect(arguments...)", - "type": "method", - "name": "connect", - "desc": "

Construct a new socket object and opens a socket to the given location. When\nthe socket is established the 'connect' event will be\nemitted.\n\n

\n

The arguments for these methods change the type of connection:\n\n

\n
    \n
  • net.connect(port, [host], [connectListener])
    • \n

  • net.createConnection(port, [host], [connectListener])

    \n

    Creates a TCP connection to port on host. If host is omitted,\n'localhost' will be assumed.

    \n
    • \n

  • net.connect(path, [connectListener])

    \n
    • \n

  • net.createConnection(path, [connectListener])

    \n

    Creates unix socket connection to path.

    \n
    • \n
\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n

\n

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

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

To connect on the socket /tmp/echo.sock the second line would just be\nchanged to\n\n

\n
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
\n", - "signatures": [ - { - "params": [ - { - "name": "arguments..." - } - ] - }, - { - "params": [ - { - "name": "arguments..." - } - ] - } - ] - }, - { - "textRaw": "net.createConnection(arguments...)", - "type": "method", - "name": "createConnection", - "desc": "

Construct a new socket object and opens a socket to the given location. When\nthe socket is established the 'connect' event will be\nemitted.\n\n

\n

The arguments for these methods change the type of connection:\n\n

\n
    \n
  • net.connect(port, [host], [connectListener])
    • \n

  • net.createConnection(port, [host], [connectListener])

    \n

    Creates a TCP connection to port on host. If host is omitted,\n'localhost' will be assumed.

    \n
    • \n

  • net.connect(path, [connectListener])

    \n
    • \n

  • net.createConnection(path, [connectListener])

    \n

    Creates unix socket connection to path.

    \n
    • \n
\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n

\n

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

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

To connect on the socket /tmp/echo.sock the second line would just be\nchanged to\n\n

\n
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
\n", - "signatures": [ - { - "params": [ - { - "name": "arguments..." - } - ] - } - ] - }, - { - "textRaw": "net.isIP(input)", - "type": "method", - "name": "isIP", - "desc": "

Tests if input is an IP address. Returns 0 for invalid strings,\nreturns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "input" - } - ] - } - ] - }, - { - "textRaw": "net.isIPv4(input)", - "type": "method", - "name": "isIPv4", - "desc": "

Returns true if input is a version 4 IP address, otherwise returns false.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "input" - } - ] - } - ] - }, - { - "textRaw": "net.isIPv6(input)", - "type": "method", - "name": "isIPv6", - "desc": "

Returns true if input is a version 6 IP address, otherwise returns false.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "input" - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: net.Server", - "type": "class", - "name": "net.Server", - "desc": "

This class is used to create a TCP or UNIX server.\nA server is a net.Socket that can listen for new incoming connections.\n\n

\n", - "methods": [ - { - "textRaw": "server.listen(port, [host], [listeningListener])", - "type": "method", - "name": "listen", - "desc": "

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

\n

This function is asynchronous. When the server has been bound,\n'listening' event will be emitted.\nthe last parameter listeningListener will be added as an listener for the\n'listening' event.\n\n

\n

One issue some users run into is getting EADDRINUSE errors. This means that\nanother server is already running on the requested port. One way of handling this\nwould be to wait a second and then try again. This can be done with\n\n

\n
server.on('error', function (e) {\n  if (e.code == 'EADDRINUSE') {\n    console.log('Address in use, retrying...');\n    setTimeout(function () {\n      server.close();\n      server.listen(PORT, HOST);\n    }, 1000);\n  }\n});
\n

(Note: All sockets in Node set SO_REUSEADDR already)\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "port" - }, - { - "name": "host", - "optional": true - }, - { - "name": "listeningListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "server.listen(path, [listeningListener])", - "type": "method", - "name": "listen", - "desc": "

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

\n

This function is asynchronous. When the server has been bound,\n'listening' event will be emitted.\nthe last parameter listeningListener will be added as an listener for the\n'listening' event.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "listeningListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "server.close()", - "type": "method", - "name": "close", - "desc": "

Stops the server from accepting new connections. This function is\nasynchronous, the server is finally closed when the server emits a 'close'\nevent.\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "server.address()", - "type": "method", - "name": "address", - "desc": "

Returns the bound address and port of the server as reported by the operating system.\nUseful to find which port was assigned when giving getting an OS-assigned address.\nReturns an object with two properties, e.g. {"address":"127.0.0.1", "port":2121}\n\n

\n

Example:\n\n

\n
var server = net.createServer(function (socket) {\n  socket.end("goodbye\\n");\n});\n\n// grab a random port.\nserver.listen(function() {\n  address = server.address();\n  console.log("opened server on %j", address);\n});
\n

Don't call server.address() until the 'listening' event has been emitted.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "properties": [ - { - "textRaw": "server.maxConnections", - "name": "maxConnections", - "desc": "

Set this property to reject connections when the server's connection count gets\nhigh.\n\n

\n" - }, - { - "textRaw": "server.connections", - "name": "connections", - "desc": "

The number of concurrent connections on the server.\n\n\n

\n

net.Server is an EventEmitter with the following events:\n\n

\n" - } - ], - "events": [ - { - "textRaw": "Event: 'listening'", - "type": "event", - "name": "listening", - "desc": "

Emitted when the server has been bound after calling server.listen.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'connection'", - "type": "event", - "name": "connection", - "params": [], - "desc": "

Emitted when a new connection is made. socket is an instance of\nnet.Socket.\n\n

\n" - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

Emitted when the server closes.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "params": [], - "desc": "

Emitted when an error occurs. The 'close' event will be called directly\nfollowing this event. See example in discussion of server.listen.\n\n

\n" - } - ] - }, - { - "textRaw": "Class: net.Socket", - "type": "class", - "name": "net.Socket", - "desc": "

This object is an abstraction of a TCP or UNIX socket. net.Socket\ninstances implement a duplex Stream interface. They can be created by the\nuser and used as a client (with connect()) or they can be created by Node\nand passed to the user through the 'connection' event of a server.\n\n

\n", - "methods": [ - { - "textRaw": "new net.Socket([options])", - "type": "method", - "name": "Socket", - "desc": "

Construct a new socket object.\n\n

\n

options is an object with the following defaults:\n\n

\n
{ fd: null\n  type: null\n  allowHalfOpen: false\n}
\n

fd allows you to specify the existing file descriptor of socket. type\nspecified underlying protocol. It can be 'tcp4', 'tcp6', or 'unix'.\nAbout allowHalfOpen, refer to createServer() and 'end' event.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.connect(port, [host], [connectListener])", - "type": "method", - "name": "connect", - "desc": "

Opens the connection for a given socket. If port and host are given,\nthen the socket will be opened as a TCP socket, if host is omitted,\nlocalhost will be assumed. If a path is given, the socket will be\nopened as a unix socket to that path.\n\n

\n

Normally this method is not needed, as net.createConnection opens the\nsocket. Use this only if you are implementing a custom Socket or if a\nSocket is closed and you want to reuse it to connect to another server.\n\n

\n

This function is asynchronous. When the 'connect' event is\nemitted the socket is established. If there is a problem connecting, the\n'connect' event will not be emitted, the 'error' event will be emitted with\nthe exception.\n\n

\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "connectListener", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "port" - }, - { - "name": "host", - "optional": true - }, - { - "name": "connectListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.connect(path, [connectListener])", - "type": "method", - "name": "connect", - "desc": "

Opens the connection for a given socket. If port and host are given,\nthen the socket will be opened as a TCP socket, if host is omitted,\nlocalhost will be assumed. If a path is given, the socket will be\nopened as a unix socket to that path.\n\n

\n

Normally this method is not needed, as net.createConnection opens the\nsocket. Use this only if you are implementing a custom Socket or if a\nSocket is closed and you want to reuse it to connect to another server.\n\n

\n

This function is asynchronous. When the 'connect' event is\nemitted the socket is established. If there is a problem connecting, the\n'connect' event will not be emitted, the 'error' event will be emitted with\nthe exception.\n\n

\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "connectListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.setEncoding([encoding])", - "type": "method", - "name": "setEncoding", - "desc": "

Sets the encoding (either 'ascii', 'utf8', or 'base64') for data that is\nreceived. Defaults to null.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.setSecure()", - "type": "method", - "name": "setSecure", - "desc": "

This function has been removed in v0.3. It used to upgrade the connection to\nSSL/TLS. See the TLS section for the new API.\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "socket.write(data, [encoding], [callback])", - "type": "method", - "name": "write", - "desc": "

Sends data on the socket. The second parameter specifies the encoding in the\ncase of a string--it defaults to UTF8 encoding.\n\n

\n

Returns true if the entire data was flushed successfully to the kernel\nbuffer. Returns false if all or part of the data was queued in user memory.\n'drain' will be emitted when the buffer is again free.\n\n

\n

The optional callback parameter will be executed when the data is finally\nwritten out - this may not be immediately.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - }, - { - "name": "encoding", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.end([data], [encoding])", - "type": "method", - "name": "end", - "desc": "

Half-closes the socket. i.e., it sends a FIN packet. It is possible the\nserver will still send some data.\n\n

\n

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

\n", - "signatures": [ - { - "params": [ - { - "name": "data", - "optional": true - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.destroy()", - "type": "method", - "name": "destroy", - "desc": "

Ensures that no more I/O activity happens on this socket. Only necessary in\ncase of errors (parse error or so).\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "socket.pause()", - "type": "method", - "name": "pause", - "desc": "

Pauses the reading of data. That is, 'data' events will not be emitted.\nUseful to throttle back an upload.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "socket.resume()", - "type": "method", - "name": "resume", - "desc": "

Resumes reading after a call to pause().\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "socket.setTimeout(timeout, [callback])", - "type": "method", - "name": "setTimeout", - "desc": "

Sets the socket to timeout after timeout milliseconds of inactivity on\nthe socket. By default net.Socket do not have a timeout.\n\n

\n

When an idle timeout is triggered the socket will receive a 'timeout'\nevent but the connection will not be severed. The user must manually end()\nor destroy() the socket.\n\n

\n

If timeout is 0, then the existing idle timeout is disabled.\n\n

\n

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

\n", - "signatures": [ - { - "params": [ - { - "name": "timeout" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.setNoDelay([noDelay])", - "type": "method", - "name": "setNoDelay", - "desc": "

Disables the Nagle algorithm. By default TCP connections use the Nagle\nalgorithm, they buffer data before sending it off. Setting true for\nnoDelay will immediately fire off data each time socket.write() is called.\nnoDelay defaults to true.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "noDelay", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.setKeepAlive([enable], [initialDelay])", - "type": "method", - "name": "setKeepAlive", - "desc": "

Enable/disable keep-alive functionality, and optionally set the initial\ndelay before the first keepalive probe is sent on an idle socket.\nenable defaults to false.\n\n

\n

Set initialDelay (in milliseconds) to set the delay between the last\ndata packet received and the first keepalive probe. Setting 0 for\ninitialDelay will leave the value unchanged from the default\n(or previous) setting. Defaults to 0.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "enable", - "optional": true - }, - { - "name": "initialDelay", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.address()", - "type": "method", - "name": "address", - "desc": "

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

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "properties": [ - { - "textRaw": "socket.bufferSize", - "name": "bufferSize", - "desc": "

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

\n

The consequence of this internal buffering is that memory may grow. This\nproperty shows the number of characters currently buffered to be written.\n(Number of characters is approximately equal to the number of bytes to be\nwritten, but the buffer may contain strings, and the strings are lazily\nencoded, so the exact number of bytes is not known.)\n\n

\n

Users who experience large or growing bufferSize should attempt to\n"throttle" the data flows in their program with pause() and resume().\n\n\n

\n" - }, - { - "textRaw": "socket.remoteAddress", - "name": "remoteAddress", - "desc": "

The string representation of the remote IP address. For example,\n'74.125.127.100' or '2001:4860:a005::68'.\n\n

\n" - }, - { - "textRaw": "socket.remotePort", - "name": "remotePort", - "desc": "

The numeric representation of the remote port. For example,\n80 or 21.\n\n

\n" - }, - { - "textRaw": "socket.bytesRead", - "name": "bytesRead", - "desc": "

The amount of received bytes.\n\n

\n" - }, - { - "textRaw": "socket.bytesWritten", - "name": "bytesWritten", - "desc": "

The amount of bytes sent.\n\n\n

\n

net.Socket instances are EventEmitters with the following events:\n\n

\n" - } - ], - "events": [ - { - "textRaw": "Event: 'connect'", - "type": "event", - "name": "connect", - "desc": "

Emitted when a socket connection is successfully established.\nSee connect().\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'data'", - "type": "event", - "name": "data", - "params": [], - "desc": "

Emitted when data is received. The argument data will be a Buffer or\nString. Encoding of data is set by socket.setEncoding().\n(See the Readable Stream section for more\ninformation.)\n\n

\n

Note that the data will be lost if there is no listener when a Socket\nemits a 'data' event.\n\n

\n" - }, - { - "textRaw": "Event: 'end'", - "type": "event", - "name": "end", - "desc": "

Emitted when the other end of the socket sends a FIN packet.\n\n

\n

By default (allowHalfOpen == false) the socket will destroy its file\ndescriptor once it has written out its pending write queue. However, by\nsetting allowHalfOpen == true the socket will not automatically end()\nits side allowing the user to write arbitrary amounts of data, with the\ncaveat that the user is required to end() their side now.\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'timeout'", - "type": "event", - "name": "timeout", - "desc": "

Emitted if the socket times out from inactivity. This is only to notify that\nthe socket has been idle. The user must manually close the connection.\n\n

\n

See also: socket.setTimeout()\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'drain'", - "type": "event", - "name": "drain", - "desc": "

Emitted when the write buffer becomes empty. Can be used to throttle uploads.\n\n

\n

See also: the return values of socket.write()\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "params": [], - "desc": "

Emitted when an error occurs. The 'close' event will be called directly\nfollowing this event.\n\n

\n" - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "params": [], - "desc": "

Emitted once the socket is fully closed. The argument had_error is a boolean\nwhich says if the socket was closed due to a transmission error.\n\n

\n" - } - ] - } - ], - "type": "module", - "displayName": "net" - }, - { - "textRaw": "UDP / Datagram Sockets", - "name": "dgram", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Datagram sockets are available through require('dgram').\n\n

\n", - "methods": [ - { - "textRaw": "dgram.createSocket(type, [callback])", - "type": "method", - "name": "createSocket", - "signatures": [ - { - "return": { - "textRaw": "Returns: Socket object ", - "name": "return", - "desc": "Socket object" - }, - "params": [ - { - "textRaw": "`type` String. Either 'udp4' or 'udp6' ", - "name": "type", - "desc": "String. Either 'udp4' or 'udp6'" - }, - { - "textRaw": "`callback` Function. Attached as a listener to `message` events. Optional ", - "name": "callback", - "optional": true, - "desc": "Function. Attached as a listener to `message` events." - } - ] - }, - { - "params": [ - { - "name": "type" - }, - { - "name": "callback", - "optional": true - } - ] - } - ], - "desc": "

Creates a datagram Socket of the specified types. Valid types are udp4\nand udp6.\n\n

\n

Takes an optional callback which is added as a listener for message events.\n\n

\n

Call socket.bind if you want to receive datagrams. socket.bind() will bind\nto the "all interfaces" address on a random port (it does the right thing for\nboth udp4 and udp6 sockets). You can then retrieve the address and port\nwith socket.address().address and socket.address().port.\n\n

\n" - } - ], - "classes": [ - { - "textRaw": "Class: Socket", - "type": "class", - "name": "Socket", - "desc": "

The dgram Socket class encapsulates the datagram functionality. It\nshould be created via dgram.createSocket(type, [callback]).\n\n

\n", - "events": [ - { - "textRaw": "Event: 'message'", - "type": "event", - "name": "message", - "params": [], - "desc": "

Emitted when a new datagram is available on a socket. msg is a Buffer and rinfo is\nan object with the sender's address information and the number of bytes in the datagram.\n\n

\n" - }, - { - "textRaw": "Event: 'listening'", - "type": "event", - "name": "listening", - "desc": "

Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets\nare created.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

Emitted when a socket is closed with close(). No new message events will be emitted\non this socket.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "params": [], - "desc": "

Emitted when an error occurs.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "dgram.send(buf, offset, length, port, address, [callback])", - "type": "method", - "name": "send", - "signatures": [ - { - "params": [ - { - "textRaw": "`buf` Buffer object. Message to be sent ", - "name": "buf", - "desc": "Buffer object. Message to be sent" - }, - { - "textRaw": "`offset` Integer. Offset in the buffer where the message starts. ", - "name": "offset", - "desc": "Integer. Offset in the buffer where the message starts." - }, - { - "textRaw": "`length` Integer. Number of bytes in the message. ", - "name": "length", - "desc": "Integer. Number of bytes in the message." - }, - { - "textRaw": "`port` Integer. destination port ", - "name": "port", - "desc": "Integer. destination port" - }, - { - "textRaw": "`address` String. destination IP ", - "name": "address", - "desc": "String. destination IP" - }, - { - "textRaw": "`callback` Function. Callback when message is done being delivered. Optional. ", - "name": "callback", - "desc": "Function. Callback when message is done being delivered. Optional.", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "buf" - }, - { - "name": "offset" - }, - { - "name": "length" - }, - { - "name": "port" - }, - { - "name": "address" - }, - { - "name": "callback", - "optional": true - } - ] - } - ], - "desc": "

For UDP sockets, the destination port and IP address must be specified. A string\nmay be supplied for the address parameter, and it will be resolved with DNS. An\noptional callback may be specified to detect any DNS errors and when buf may be\nre-used. Note that DNS lookups will delay the time that a send takes place, at\nleast until the next tick. The only way to know for sure that a send has taken place\nis to use the callback.\n\n

\n

If the socket has not been previously bound with a call to bind, it's\nassigned a random port number and bound to the "all interfaces" address\n(0.0.0.0 for udp4 sockets, ::0 for udp6 sockets).\n\n

\n

Example of sending a UDP packet to a random port on localhost;\n\n

\n
var dgram = require('dgram');\nvar message = new Buffer("Some bytes");\nvar client = dgram.createSocket("udp4");\nclient.send(message, 0, message.length, 41234, "localhost", function(err, bytes) {\n  client.close();\n});
\n

A Note about UDP datagram size\n\n

\n

The maximum size of an IPv4/v6 datagram depends on the MTU (Maximum Transmission Unit)\nand on the Payload Length field size.\n\n

\n
    \n

  • The Payload Length field is 16 bits wide, which means that a normal payload\ncannot be larger than 64K octets including internet header and data\n(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header);\nthis is generally true for loopback interfaces, but such long datagrams\nare impractical for most hosts and networks.

    \n
    • \n

  • The MTU is the largest size a given link layer technology can support for datagrams.\nFor any link, IPv4 mandates a minimum MTU of 68 octets, while the recommended MTU\nfor IPv4 is 576 (typically recommended as the MTU for dial-up type applications),\nwhether they arrive whole or in fragments.

    \n

    For IPv6, the minimum MTU is 1280 octets, however, the mandatory minimum\nfragment reassembly buffer size is 1500 octets.\nThe value of 68 octets is very small, since most current link layer technologies have\na minimum MTU of 1500 (like Ethernet).

    \n
    • \n
\n

Note that it's impossible to know in advance the MTU of each link through which\na packet might travel, and that generally sending a datagram greater than\nthe (receiver) MTU won't work (the packet gets silently dropped, without\ninforming the source that the data did not reach its intended recipient).\n\n

\n" - }, - { - "textRaw": "dgram.bind(port, [address])", - "type": "method", - "name": "bind", - "signatures": [ - { - "params": [ - { - "textRaw": "`port` Integer ", - "name": "port", - "desc": "Integer" - }, - { - "textRaw": "`address` String, Optional ", - "name": "address", - "optional": true, - "desc": "String" - } - ] - }, - { - "params": [ - { - "name": "port" - }, - { - "name": "address", - "optional": true - } - ] - } - ], - "desc": "

For UDP sockets, listen for datagrams on a named port and optional address. If\naddress is not specified, the OS will try to listen on all addresses.\n\n

\n

Example of a UDP server listening on port 41234:\n\n

\n
var dgram = require("dgram");\n\nvar server = dgram.createSocket("udp4");\n\nserver.on("message", function (msg, rinfo) {\n  console.log("server got: " + msg + " from " +\n    rinfo.address + ":" + rinfo.port);\n});\n\nserver.on("listening", function () {\n  var address = server.address();\n  console.log("server listening " +\n      address.address + ":" + address.port);\n});\n\nserver.bind(41234);\n// server listening 0.0.0.0:41234
\n" - }, - { - "textRaw": "dgram.close()", - "type": "method", - "name": "close", - "desc": "

Close the underlying socket and stop listening for data on it.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "dgram.address()", - "type": "method", - "name": "address", - "desc": "

Returns an object containing the address information for a socket. For UDP sockets,\nthis object will contain address and port.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "dgram.setBroadcast(flag)", - "type": "method", - "name": "setBroadcast", - "signatures": [ - { - "params": [ - { - "textRaw": "`flag` Boolean ", - "name": "flag", - "desc": "Boolean" - } - ] - }, - { - "params": [ - { - "name": "flag" - } - ] - } - ], - "desc": "

Sets or clears the SO_BROADCAST socket option. When this option is set, UDP packets\nmay be sent to a local interface's broadcast address.\n\n

\n" - }, - { - "textRaw": "dgram.setTTL(ttl)", - "type": "method", - "name": "setTTL", - "signatures": [ - { - "params": [ - { - "textRaw": "`ttl` Integer ", - "name": "ttl", - "desc": "Integer" - } - ] - }, - { - "params": [ - { - "name": "ttl" - } - ] - } - ], - "desc": "

Sets the IP_TTL socket option. TTL stands for "Time to Live," but in this context it\nspecifies the number of IP hops that a packet is allowed to go through. Each router or\ngateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a\nrouter, it will not be forwarded. Changing TTL values is typically done for network\nprobes or when multicasting.\n\n

\n

The argument to setTTL() is a number of hops between 1 and 255. The default on most\nsystems is 64.\n\n

\n" - }, - { - "textRaw": "dgram.setMulticastTTL(ttl)", - "type": "method", - "name": "setMulticastTTL", - "signatures": [ - { - "params": [ - { - "textRaw": "`ttl` Integer ", - "name": "ttl", - "desc": "Integer" - } - ] - }, - { - "params": [ - { - "name": "ttl" - } - ] - } - ], - "desc": "

Sets the IP_MULTICAST_TTL socket option. TTL stands for "Time to Live," but in this\ncontext it specifies the number of IP hops that a packet is allowed to go through,\nspecifically for multicast traffic. Each router or gateway that forwards a packet\ndecrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded.\n\n

\n

The argument to setMulticastTTL() is a number of hops between 0 and 255. The default on most\nsystems is 64.\n\n

\n" - }, - { - "textRaw": "dgram.setMulticastLoopback(flag)", - "type": "method", - "name": "setMulticastLoopback", - "signatures": [ - { - "params": [ - { - "textRaw": "`flag` Boolean ", - "name": "flag", - "desc": "Boolean" - } - ] - }, - { - "params": [ - { - "name": "flag" - } - ] - } - ], - "desc": "

Sets or clears the IP_MULTICAST_LOOP socket option. When this option is set, multicast\npackets will also be received on the local interface.\n\n

\n" - }, - { - "textRaw": "dgram.addMembership(multicastAddress, [multicastInterface])", - "type": "method", - "name": "addMembership", - "signatures": [ - { - "params": [ - { - "textRaw": "`multicastAddress` String ", - "name": "multicastAddress", - "desc": "String" - }, - { - "textRaw": "`multicastInterface` String, Optional ", - "name": "multicastInterface", - "optional": true, - "desc": "String" - } - ] - }, - { - "params": [ - { - "name": "multicastAddress" - }, - { - "name": "multicastInterface", - "optional": true - } - ] - } - ], - "desc": "

Tells the kernel to join a multicast group with IP_ADD_MEMBERSHIP socket option.\n\n

\n

If multicastInterface is not specified, the OS will try to add membership to all valid\ninterfaces.\n\n

\n" - }, - { - "textRaw": "dgram.dropMembership(multicastAddress, [multicastInterface])", - "type": "method", - "name": "dropMembership", - "signatures": [ - { - "params": [ - { - "textRaw": "`multicastAddress` String ", - "name": "multicastAddress", - "desc": "String" - }, - { - "textRaw": "`multicastInterface` String, Optional ", - "name": "multicastInterface", - "optional": true, - "desc": "String" - } - ] - }, - { - "params": [ - { - "name": "multicastAddress" - }, - { - "name": "multicastInterface", - "optional": true - } - ] - } - ], - "desc": "

Opposite of addMembership - tells the kernel to leave a multicast group with\nIP_DROP_MEMBERSHIP socket option. This is automatically called by the kernel\nwhen the socket is closed or process terminates, so most apps will never need to call\nthis.\n\n

\n

If multicastInterface is not specified, the OS will try to drop membership to all valid\ninterfaces.\n\n

\n" - } - ] - } - ], - "type": "module", - "displayName": "dgram" - }, - { - "textRaw": "DNS", - "name": "dns", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Use require('dns') to access this module. All methods in the dns module\nuse C-Ares except for dns.lookup which uses getaddrinfo(3) in a thread\npool. C-Ares is much faster than getaddrinfo but the system resolver is\nmore constant with how other programs operate. When a user does\nnet.connect(80, 'google.com') or http.get({ host: 'google.com' }) the\ndns.lookup method is used. Users who need to do a large number of look ups\nquickly should use the methods that go through C-Ares.\n\n

\n

Here is an example which resolves 'www.google.com' then reverse\nresolves the IP addresses which are returned.\n\n

\n
var dns = require('dns');\n\ndns.resolve4('www.google.com', function (err, addresses) {\n  if (err) throw err;\n\n  console.log('addresses: ' + JSON.stringify(addresses));\n\n  addresses.forEach(function (a) {\n    dns.reverse(a, function (err, domains) {\n      if (err) {\n        console.log('reverse for ' + a + ' failed: ' +\n          err.message);\n      } else {\n        console.log('reverse for ' + a + ': ' +\n          JSON.stringify(domains));\n      }\n    });\n  });\n});
\n", - "methods": [ - { - "textRaw": "dns.lookup(domain, [family], callback)", - "type": "method", - "name": "lookup", - "desc": "

Resolves a domain (e.g. 'google.com') into the first found A (IPv4) or\nAAAA (IPv6) record.\nThe family can be the integer 4 or 6. Defaults to null that indicates\nboth Ip v4 and v6 address family.\n\n

\n

The callback has arguments (err, address, family). The address argument\nis a string representation of a IP v4 or v6 address. The family argument\nis either the integer 4 or 6 and denotes the family of address (not\nnecessarily the value initially passed to lookup).\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "family", - "optional": true - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolve(domain, [rrtype], callback)", - "type": "method", - "name": "resolve", - "desc": "

Resolves a domain (e.g. 'google.com') into an array of the record types\nspecified by rrtype. Valid rrtypes are 'A' (IPV4 addresses, default),\n'AAAA' (IPV6 addresses), 'MX' (mail exchange records), 'TXT' (text\nrecords), 'SRV' (SRV records), 'PTR' (used for reverse IP lookups),\n'NS' (name server records) and 'CNAME' (canonical name records).\n\n

\n

The callback has arguments (err, addresses). The type of each item\nin addresses is determined by the record type, and described in the\ndocumentation for the corresponding lookup methods below.\n\n

\n

On error, err would be an instanceof Error object, where err.errno is\none of the error codes listed below and err.message is a string describing\nthe error in English.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "rrtype", - "optional": true - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolve4(domain, callback)", - "type": "method", - "name": "resolve4", - "desc": "

The same as dns.resolve(), but only for IPv4 queries (A records).\naddresses is an array of IPv4 addresses (e.g.\n['74.125.79.104', '74.125.79.105', '74.125.79.106']).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolve6(domain, callback)", - "type": "method", - "name": "resolve6", - "desc": "

The same as dns.resolve4() except for IPv6 queries (an AAAA query).\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolveMx(domain, callback)", - "type": "method", - "name": "resolveMx", - "desc": "

The same as dns.resolve(), but only for mail exchange queries (MX records).\n\n

\n

addresses is an array of MX records, each with a priority and an exchange\nattribute (e.g. [{'priority': 10, 'exchange': 'mx.example.com'},...]).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolveTxt(domain, callback)", - "type": "method", - "name": "resolveTxt", - "desc": "

The same as dns.resolve(), but only for text queries (TXT records).\naddresses is an array of the text records available for domain (e.g.,\n['v=spf1 ip4:0.0.0.0 ~all']).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolveSrv(domain, callback)", - "type": "method", - "name": "resolveSrv", - "desc": "

The same as dns.resolve(), but only for service records (SRV records).\naddresses is an array of the SRV records available for domain. Properties\nof SRV records are priority, weight, port, and name (e.g.,\n[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.reverse(ip, callback)", - "type": "method", - "name": "reverse", - "desc": "

Reverse resolves an ip address to an array of domain names.\n\n

\n

The callback has arguments (err, domains).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "ip" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolveNs(domain, callback)", - "type": "method", - "name": "resolveNs", - "desc": "

The same as dns.resolve(), but only for name server records (NS records).\naddresses is an array of the name server records available for domain\n(e.g., ['ns1.example.com', 'ns2.example.com']).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolveCname(domain, callback)", - "type": "method", - "name": "resolveCname", - "desc": "

The same as dns.resolve(), but only for canonical name records (CNAME\nrecords). addresses is an array of the canonical name records available for\ndomain (e.g., ['bar.example.com']).\n\n

\n

If there an an error, err will be non-null and an instanceof the Error\nobject.\n\n

\n

Each DNS query can return an error code.\n\n

\n
    \n
  • dns.TEMPFAIL: timeout, SERVFAIL or similar.
    • \n
  • dns.PROTOCOL: got garbled reply.
    • \n
  • dns.NXDOMAIN: domain does not exists.
    • \n
  • dns.NODATA: domain exists but no data of reqd type.
    • \n
  • dns.NOMEM: out of memory while processing.
    • \n
  • dns.BADQUERY: the query is malformed.
    • \n
\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "DNS" - }, - { - "textRaw": "HTTP", - "name": "http", - "stability": 3, - "stabilityText": "Stable", - "desc": "

To use the HTTP server and client one must require('http').\n\n

\n

The HTTP interfaces in Node are designed to support many features\nof the protocol which have been traditionally difficult to use.\nIn particular, large, possibly chunk-encoded, messages. The interface is\ncareful to never buffer entire requests or responses--the\nuser is able to stream data.\n\n

\n

HTTP message headers are represented by an object like this:\n\n

\n
{ 'content-length': '123',\n  'content-type': 'text/plain',\n  'connection': 'keep-alive',\n  'accept': '*/*' }
\n

Keys are lowercased. Values are not modified.\n\n

\n

In order to support the full spectrum of possible HTTP applications, Node's\nHTTP API is very low-level. It deals with stream handling and message\nparsing only. It parses a message into headers and body but it does not\nparse the actual headers or the body.\n\n\n

\n", - "methods": [ - { - "textRaw": "http.createServer([requestListener])", - "type": "method", - "name": "createServer", - "desc": "

Returns a new web server object.\n\n

\n

The requestListener is a function which is automatically\nadded to the 'request' event.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "requestListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "http.request(options, callback)", - "type": "method", - "name": "request", - "desc": "

Node maintains several connections per server to make HTTP requests.\nThis function allows one to transparently issue requests. options align\nwith url.parse().\n\n

\n

Options:\n\n

\n
    \n
  • host: A domain name or IP address of the server to issue the request to.\nDefaults to 'localhost'.
    • \n
  • hostname: To support url.parse() hostname is preferred over host
    • \n
  • port: Port of remote server. Defaults to 80.
    • \n
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • \n
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • \n
  • path: Request path. Defaults to '/'. Should include query string if any.\nE.G. '/index.html?page=12'
    • \n
  • headers: An object containing request headers.
    • \n
  • auth: Basic authentication i.e. 'user:password' to compute an\nAuthorization header.
    • \n
  • agent: Controls Agent behavior. When an Agent is used\nrequest will default to Connection: keep-alive. Possible values:
      \n
    • undefined (default): use global Agent for this host\nand port.
      • \n
    • Agent object: explicitly use the passed in Agent.
      • \n
    • false: opts out of connection pooling with an Agent, defaults request to\nConnection: close.
      • \n
    \n
    • \n
\n

http.request() returns an instance of the http.ClientRequest\nclass. The ClientRequest instance is a writable stream. If one needs to\nupload a file with a POST request, then write to the ClientRequest object.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'www.google.com',\n  port: 80,\n  path: '/upload',\n  method: 'POST'\n};\n\nvar req = http.request(options, function(res) {\n  console.log('STATUS: ' + res.statusCode);\n  console.log('HEADERS: ' + JSON.stringify(res.headers));\n  res.setEncoding('utf8');\n  res.on('data', function (chunk) {\n    console.log('BODY: ' + chunk);\n  });\n});\n\nreq.on('error', function(e) {\n  console.log('problem with request: ' + e.message);\n});\n\n// write data to request body\nreq.write('data\\n');\nreq.write('data\\n');\nreq.end();
\n

Note that in the example req.end() was called. With http.request() one\nmust always call req.end() to signify that you're done with the request -\neven if there is no data being written to the request body.\n\n

\n

If any error is encountered during the request (be that with DNS resolution,\nTCP level errors, or actual HTTP parse errors) an 'error' event is emitted\non the returned request object.\n\n

\n

There are a few special headers that should be noted.\n\n

\n
    \n

  • Sending a 'Connection: keep-alive' will notify Node that the connection to\nthe server should be persisted until the next request.

    \n
    • \n

  • Sending a 'Content-length' header will disable the default chunked encoding.

    \n
    • \n

  • Sending an 'Expect' header will immediately send the request headers.\nUsually, when sending 'Expect: 100-continue', you should both set a timeout\nand listen for the continue event. See RFC2616 Section 8.2.3 for more\ninformation.

    \n
    • \n

  • Sending an Authorization header will override using the auth option\nto compute basic authentication.

    \n
    • \n
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "http.get(options, callback)", - "type": "method", - "name": "get", - "desc": "

Since most requests are GET requests without bodies, Node provides this\nconvenience method. The only difference between this method and http.request() is\nthat it sets the method to GET and calls req.end() automatically.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'www.google.com',\n  port: 80,\n  path: '/index.html'\n};\n\nhttp.get(options, function(res) {\n  console.log("Got response: " + res.statusCode);\n}).on('error', function(e) {\n  console.log("Got error: " + e.message);\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "callback" - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: http.Server", - "type": "class", - "name": "http.Server", - "desc": "

This is an EventEmitter with the following events:\n\n

\n", - "events": [ - { - "textRaw": "Event: 'request'", - "type": "event", - "name": "request", - "desc": "

function (request, response) { }\n\n

\n

Emitted each time there is a request. Note that there may be multiple requests\nper connection (in the case of keep-alive connections).\n request is an instance of http.ServerRequest and response is\n an instance of http.ServerResponse\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'connection'", - "type": "event", - "name": "connection", - "desc": "

function (socket) { }\n\n

\n

When a new TCP stream is established. socket is an object of type\n net.Socket. Usually users will not want to access this event. The\n socket can also be accessed at request.connection.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () { }\n\n

\n

Emitted when the server closes.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'checkContinue'", - "type": "event", - "name": "checkContinue", - "desc": "

function (request, response) { }\n\n

\n

Emitted each time a request with an http Expect: 100-continue is received.\nIf this event isn't listened for, the server will automatically respond\nwith a 100 Continue as appropriate.\n\n

\n

Handling this event involves calling response.writeContinue if the client\nshould continue to send the request body, or generating an appropriate HTTP\nresponse (e.g., 400 Bad Request) if the client should not continue to send the\nrequest body.\n\n

\n

Note that when this event is emitted and handled, the request event will\nnot be emitted.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'upgrade'", - "type": "event", - "name": "upgrade", - "desc": "

function (request, socket, head) { }\n\n

\n

Emitted each time a client requests a http upgrade. If this event isn't\nlistened for, then clients requesting an upgrade will have their connections\nclosed.\n\n

\n
    \n
  • request is the arguments for the http request, as it is in the request event.
    • \n
  • socket is the network socket between the server and client.
    • \n
  • head is an instance of Buffer, the first packet of the upgraded stream, this may be empty.
    • \n
\n

After this event is emitted, the request's socket will not have a data\nevent listener, meaning you will need to bind to it in order to handle data\nsent to the server on that socket.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'clientError'", - "type": "event", - "name": "clientError", - "desc": "

function (exception) { }\n\n

\n

If a client connection emits an 'error' event - it will forwarded here.\n\n

\n", - "params": [] - } - ], - "methods": [ - { - "textRaw": "server.listen(port, [hostname], [callback])", - "type": "method", - "name": "listen", - "desc": "

Begin accepting connections on the specified port and hostname. If the\nhostname is omitted, the server will accept connections directed to any\nIPv4 address (INADDR_ANY).\n\n

\n

To listen to a unix socket, supply a filename instead of port and hostname.\n\n

\n

This function is asynchronous. The last parameter callback will be added as\na listener for the 'listening' event.\nSee also net.Server.listen().\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "port" - }, - { - "name": "hostname", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "server.listen(path, [callback])", - "type": "method", - "name": "listen", - "desc": "

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

\n

This function is asynchronous. The last parameter callback will be added as\na listener for the 'listening' event.\nSee also net.Server.listen().\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "server.close()", - "type": "method", - "name": "close", - "desc": "

Stops the server from accepting new connections.\nSee net.Server.close().\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - }, - { - "textRaw": "Class: http.ServerRequest", - "type": "class", - "name": "http.ServerRequest", - "desc": "

This object is created internally by a HTTP server -- not by\nthe user -- and passed as the first argument to a 'request' listener.\n\n

\n

The request implements the Readable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", - "events": [ - { - "textRaw": "Event: 'data'", - "type": "event", - "name": "data", - "desc": "

function (chunk) { }\n\n

\n

Emitted when a piece of the message body is received. The chunk is a string if\nan encoding has been set with request.setEncoding(), otherwise it's a\nBuffer.\n\n

\n

Note that the data will be lost if there is no listener when a\nServerRequest emits a 'data' event.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'end'", - "type": "event", - "name": "end", - "desc": "

function () { }\n\n

\n

Emitted exactly once for each request. After that, no more 'data' events\nwill be emitted on the request.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () { }\n\n

\n

Indicates that the underlaying connection was terminated before\nresponse.end() was called or able to flush.\n\n

\n

Just like 'end', this event occurs only once per request, and no more 'data'\nevents will fire afterwards.\n\n

\n

Note: 'close' can fire after 'end', but not vice versa.\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "request.method", - "name": "method", - "desc": "

The request method as a string. Read only. Example:\n'GET', 'DELETE'.\n\n\n

\n" - }, - { - "textRaw": "request.url", - "name": "url", - "desc": "

Request URL string. This contains only the URL that is\npresent in the actual HTTP request. If the request is:\n\n

\n
GET /status?name=ryan HTTP/1.1\\r\\n\nAccept: text/plain\\r\\n\n\\r\\n
\n

Then request.url will be:\n\n

\n
'/status?name=ryan'
\n

If you would like to parse the URL into its parts, you can use\nrequire('url').parse(request.url). Example:\n\n

\n
node> require('url').parse('/status?name=ryan')\n{ href: '/status?name=ryan',\n  search: '?name=ryan',\n  query: 'name=ryan',\n  pathname: '/status' }
\n

If you would like to extract the params from the query string,\nyou can use the require('querystring').parse function, or pass\ntrue as the second argument to require('url').parse. Example:\n\n

\n
node> require('url').parse('/status?name=ryan', true)\n{ href: '/status?name=ryan',\n  search: '?name=ryan',\n  query: { name: 'ryan' },\n  pathname: '/status' }
\n" - }, - { - "textRaw": "request.headers", - "name": "headers", - "desc": "

Read only.\n\n

\n" - }, - { - "textRaw": "request.trailers", - "name": "trailers", - "desc": "

Read only; HTTP trailers (if present). Only populated after the 'end' event.\n\n

\n" - }, - { - "textRaw": "request.httpVersion", - "name": "httpVersion", - "desc": "

The HTTP protocol version as a string. Read only. Examples:\n'1.1', '1.0'.\nAlso request.httpVersionMajor is the first integer and\nrequest.httpVersionMinor is the second.\n\n\n

\n" - }, - { - "textRaw": "request.connection", - "name": "connection", - "desc": "

The net.Socket object associated with the connection.\n\n\n

\n

With HTTPS support, use request.connection.verifyPeer() and\nrequest.connection.getPeerCertificate() to obtain the client's\nauthentication details.\n\n\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "request.setEncoding([encoding])", - "type": "method", - "name": "setEncoding", - "desc": "

Set the encoding for the request body. Either 'utf8' or 'binary'. Defaults\nto null, which means that the 'data' event will emit a Buffer object..\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "request.pause()", - "type": "method", - "name": "pause", - "desc": "

Pauses request from emitting events. Useful to throttle back an upload.\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "request.resume()", - "type": "method", - "name": "resume", - "desc": "

Resumes a paused request.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - }, - { - "textRaw": "Class: http.ServerResponse", - "type": "class", - "name": "http.ServerResponse", - "desc": "

This object is created internally by a HTTP server--not by the user. It is\npassed as the second parameter to the 'request' event.\n\n

\n

The response implements the Writable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", - "events": [ - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () { }\n\n

\n

Indicates that the underlaying connection was terminated before\nresponse.end() was called or able to flush.\n\n

\n", - "params": [] - } - ], - "methods": [ - { - "textRaw": "response.writeContinue()", - "type": "method", - "name": "writeContinue", - "desc": "

Sends a HTTP/1.1 100 Continue message to the client, indicating that\nthe request body should be sent. See the checkContinue event on\nServer.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "response.writeHead(statusCode, [reasonPhrase], [headers])", - "type": "method", - "name": "writeHead", - "desc": "

Sends a response header to the request. The status code is a 3-digit HTTP\nstatus code, like 404. The last argument, headers, are the response headers.\nOptionally one can give a human-readable reasonPhrase as the second\nargument.\n\n

\n

Example:\n\n

\n
var body = 'hello world';\nresponse.writeHead(200, {\n  'Content-Length': body.length,\n  'Content-Type': 'text/plain' });
\n

This method must only be called once on a message and it must\nbe called before response.end() is called.\n\n

\n

If you call response.write() or response.end() before calling this, the\nimplicit/mutable headers will be calculated and call this function for you.\n\n

\n

Note: that Content-Length is given in bytes not characters. The above example\nworks because the string 'hello world' contains only single byte characters.\nIf the body contains higher coded characters then Buffer.byteLength()\nshould be used to determine the number of bytes in a given encoding.\nAnd Node does not check whether Content-Length and the length of the body\nwhich has been transmitted are equal or not.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "statusCode" - }, - { - "name": "reasonPhrase", - "optional": true - }, - { - "name": "headers", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "response.setHeader(name, value)", - "type": "method", - "name": "setHeader", - "desc": "

Sets a single header value for implicit headers. If this header already exists\nin the to-be-sent headers, its value will be replaced. Use an array of strings\nhere if you need to send multiple headers with the same name.\n\n

\n

Example:\n\n

\n
response.setHeader("Content-Type", "text/html");
\n

or\n\n

\n
response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]);
\n", - "signatures": [ - { - "params": [ - { - "name": "name" - }, - { - "name": "value" - } - ] - } - ] - }, - { - "textRaw": "response.getHeader(name)", - "type": "method", - "name": "getHeader", - "desc": "

Reads out a header that's already been queued but not sent to the client. Note\nthat the name is case insensitive. This can only be called before headers get\nimplicitly flushed.\n\n

\n

Example:\n\n

\n
var contentType = response.getHeader('content-type');
\n", - "signatures": [ - { - "params": [ - { - "name": "name" - } - ] - } - ] - }, - { - "textRaw": "response.removeHeader(name)", - "type": "method", - "name": "removeHeader", - "desc": "

Removes a header that's queued for implicit sending.\n\n

\n

Example:\n\n

\n
response.removeHeader("Content-Encoding");
\n", - "signatures": [ - { - "params": [ - { - "name": "name" - } - ] - } - ] - }, - { - "textRaw": "response.write(chunk, [encoding])", - "type": "method", - "name": "write", - "desc": "

If this method is called and response.writeHead() has not been called, it will\nswitch to implicit header mode and flush the implicit headers.\n\n

\n

This sends a chunk of the response body. This method may\nbe called multiple times to provide successive parts of the body.\n\n

\n

chunk can be a string or a buffer. If chunk is a string,\nthe second parameter specifies how to encode it into a byte stream.\nBy default the encoding is 'utf8'.\n\n

\n

Note: This is the raw HTTP body and has nothing to do with\nhigher-level multi-part body encodings that may be used.\n\n

\n

The first time response.write() is called, it will send the buffered\nheader information and the first body to the client. The second time\nresponse.write() is called, Node assumes you're going to be streaming\ndata, and sends that separately. That is, the response is buffered up to the\nfirst chunk of body.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "chunk" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "response.addTrailers(headers)", - "type": "method", - "name": "addTrailers", - "desc": "

This method adds HTTP trailing headers (a header but at the end of the\nmessage) to the response.\n\n

\n

Trailers will only be emitted if chunked encoding is used for the\nresponse; if it is not (e.g., if the request was HTTP/1.0), they will\nbe silently discarded.\n\n

\n

Note that HTTP requires the Trailer header to be sent if you intend to\nemit trailers, with a list of the header fields in its value. E.g.,\n\n

\n
response.writeHead(200, { 'Content-Type': 'text/plain',\n                          'Trailer': 'Content-MD5' });\nresponse.write(fileData);\nresponse.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});\nresponse.end();
\n", - "signatures": [ - { - "params": [ - { - "name": "headers" - } - ] - } - ] - }, - { - "textRaw": "response.end([data], [encoding])", - "type": "method", - "name": "end", - "desc": "

This method signals to the server that all of the response headers and body\nhas been sent; that server should consider this message complete.\nThe method, response.end(), MUST be called on each\nresponse.\n\n

\n

If data is specified, it is equivalent to calling response.write(data, encoding)\nfollowed by response.end().\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data", - "optional": true - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - } - ], - "properties": [ - { - "textRaw": "response.statusCode", - "name": "statusCode", - "desc": "

When using implicit headers (not calling response.writeHead() explicitly), this property\ncontrols the status code that will be send to the client when the headers get\nflushed.\n\n

\n

Example:\n\n

\n
response.statusCode = 404;
\n

After response header was sent to the client, this property indicates the\nstatus code which was sent out.\n\n

\n" - } - ] - }, - { - "textRaw": "Class: http.Agent", - "type": "class", - "name": "http.Agent", - "desc": "

In node 0.5.3+ there is a new implementation of the HTTP Agent which is used\nfor pooling sockets used in HTTP client requests.\n\n

\n

Previously, a single agent instance help the pool for single host+port. The\ncurrent implementation now holds sockets for any number of hosts.\n\n

\n

The current HTTP Agent also defaults client requests to using\nConnection:keep-alive. If no pending HTTP requests are waiting on a socket\nto become free the socket is closed. This means that node's pool has the\nbenefit of keep-alive when under load but still does not require developers\nto manually close the HTTP clients using keep-alive.\n\n

\n

Sockets are removed from the agent's pool when the socket emits either a\n"close" event or a special "agentRemove" event. This means that if you intend\nto keep one HTTP request open for a long time and don't want it to stay in the\npool you can do something along the lines of:\n\n

\n
http.get(options, function(res) {\n  // Do stuff\n}).on("socket", function (socket) {\n  socket.emit("agentRemove");\n});
\n

Alternatively, you could just opt out of pooling entirely using agent:false:\n\n

\n
http.get({host:'localhost', port:80, path:'/', agent:false}, function (res) {\n  // Do stuff\n})
\n", - "properties": [ - { - "textRaw": "agent.maxSockets", - "name": "maxSockets", - "desc": "

By default set to 5. Determines how many concurrent sockets the agent can have \nopen per host.\n\n

\n" - }, - { - "textRaw": "agent.sockets", - "name": "sockets", - "desc": "

An object which contains arrays of sockets currently in use by the Agent. Do not \nmodify.\n\n

\n" - }, - { - "textRaw": "agent.requests", - "name": "requests", - "desc": "

An object which contains queues of requests that have not yet been assigned to \nsockets. Do not modify.\n\n

\n" - } - ] - }, - { - "textRaw": "Class: http.ClientRequest", - "type": "class", - "name": "http.ClientRequest", - "desc": "

This object is created internally and returned from http.request(). It\nrepresents an in-progress request whose header has already been queued. The\nheader is still mutable using the setHeader(name, value), getHeader(name),\nremoveHeader(name) API. The actual header will be sent along with the first\ndata chunk or when closing the connection.\n\n

\n

To get the response, add a listener for 'response' to the request object.\n'response' will be emitted from the request object when the response\nheaders have been received. The 'response' event is executed with one\nargument which is an instance of http.ClientResponse.\n\n

\n

During the 'response' event, one can add listeners to the\nresponse object; particularly to listen for the 'data' event. Note that\nthe 'response' event is called before any part of the response body is received,\nso there is no need to worry about racing to catch the first part of the\nbody. As long as a listener for 'data' is added during the 'response'\nevent, the entire body will be caught.\n\n\n

\n
// Good\nrequest.on('response', function (response) {\n  response.on('data', function (chunk) {\n    console.log('BODY: ' + chunk);\n  });\n});\n\n// Bad - misses all or part of the body\nrequest.on('response', function (response) {\n  setTimeout(function () {\n    response.on('data', function (chunk) {\n      console.log('BODY: ' + chunk);\n    });\n  }, 10);\n});
\n

Note: Node does not check whether Content-Length and the length of the body\nwhich has been transmitted are equal or not.\n\n

\n

The request implements the Writable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", - "events": [ - { - "textRaw": "Event 'response'", - "type": "event", - "name": "response", - "desc": "

function (response) { }\n\n

\n

Emitted when a response is received to this request. This event is emitted only once. The\nresponse argument will be an instance of http.ClientResponse.\n\n

\n

Options:\n\n

\n
    \n
  • host: A domain name or IP address of the server to issue the request to.
    • \n
  • port: Port of remote server.
    • \n
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • \n
\n", - "params": [] - }, - { - "textRaw": "Event: 'socket'", - "type": "event", - "name": "socket", - "desc": "

function (socket) { }\n\n

\n

Emitted after a socket is assigned to this request.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'upgrade'", - "type": "event", - "name": "upgrade", - "desc": "

function (response, socket, head) { }\n\n

\n

Emitted each time a server responds to a request with an upgrade. If this\nevent isn't being listened for, clients receiving an upgrade header will have\ntheir connections closed.\n\n

\n

A client server pair that show you how to listen for the upgrade event using http.getAgent:\n\n

\n
var http = require('http');\nvar net = require('net');\n\n// Create an HTTP server\nvar srv = http.createServer(function (req, res) {\n  res.writeHead(200, {'Content-Type': 'text/plain'});\n  res.end('okay');\n});\nsrv.on('upgrade', function(req, socket, upgradeHead) {\n  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\\r\\n' +\n               'Upgrade: WebSocket\\r\\n' +\n               'Connection: Upgrade\\r\\n' +\n               '\\r\\n\\r\\n');\n\n  socket.ondata = function(data, start, end) {\n    socket.write(data.toString('utf8', start, end), 'utf8'); // echo back\n  };\n});\n\n// now that server is running\nsrv.listen(1337, '127.0.0.1', function() {\n\n  // make a request\n  var options = {\n    port: 1337,\n    host: '127.0.0.1',\n    headers: {\n      'Connection': 'Upgrade',\n      'Upgrade': 'websocket'\n    }\n  };\n\n  var req = http.request(options);\n  req.end();\n\n  req.on('upgrade', function(res, socket, upgradeHead) {\n    console.log('got upgraded!');\n    socket.end();\n    process.exit(0);\n  });\n});
\n", - "params": [] - }, - { - "textRaw": "Event: 'continue'", - "type": "event", - "name": "continue", - "desc": "

function () { }\n\n

\n

Emitted when the server sends a '100 Continue' HTTP response, usually because\nthe request contained 'Expect: 100-continue'. This is an instruction that\nthe client should send the request body.\n\n

\n", - "params": [] - } - ], - "methods": [ - { - "textRaw": "request.write(chunk, [encoding])", - "type": "method", - "name": "write", - "desc": "

Sends a chunk of the body. By calling this method\nmany times, the user can stream a request body to a\nserver--in that case it is suggested to use the\n['Transfer-Encoding', 'chunked'] header line when\ncreating the request.\n\n

\n

The chunk argument should be a buffer or a string.\n\n

\n

The encoding argument is optional and only applies when chunk is a string.\nDefaults to 'utf8'.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "chunk" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "request.end([data], [encoding])", - "type": "method", - "name": "end", - "desc": "

Finishes sending the request. If any parts of the body are\nunsent, it will flush them to the stream. If the request is\nchunked, this will send the terminating '0\\r\\n\\r\\n'.\n\n

\n

If data is specified, it is equivalent to calling\nrequest.write(data, encoding) followed by request.end().\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data", - "optional": true - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "request.abort()", - "type": "method", - "name": "abort", - "desc": "

Aborts a request. (New since v0.3.8.)\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "request.setTimeout(timeout, [callback])", - "type": "method", - "name": "setTimeout", - "desc": "

Once a socket is assigned to this request and is connected \nsocket.setTimeout(timeout, [callback])\nwill be called.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "timeout" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "request.setNoDelay([noDelay])", - "type": "method", - "name": "setNoDelay", - "desc": "

Once a socket is assigned to this request and is connected \nsocket.setNoDelay(noDelay)\nwill be called.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "noDelay", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "request.setSocketKeepAlive([enable], [initialDelay])", - "type": "method", - "name": "setSocketKeepAlive", - "desc": "

Once a socket is assigned to this request and is connected \nsocket.setKeepAlive(enable, [initialDelay])\nwill be called.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "enable", - "optional": true - }, - { - "name": "initialDelay", - "optional": true - } - ] - } - ] - } - ] - } - ], - "properties": [ - { - "textRaw": "http.globalAgent", - "name": "globalAgent", - "desc": "

Global instance of Agent which is used as the default for all http client\nrequests.\n\n\n

\n" - }, - { - "textRaw": "http.ClientResponse", - "name": "ClientResponse", - "desc": "

This object is created when making a request with http.request(). It is\npassed to the 'response' event of the request object.\n\n

\n

The response implements the Readable Stream\ninterface. This is an EventEmitter with the following events:\n\n\n

\n", - "events": [ - { - "textRaw": "Event: 'data'", - "type": "event", - "name": "data", - "desc": "

function (chunk) { }\n\n

\n

Emitted when a piece of the message body is received.\n\n

\n

Note that the data will be lost if there is no listener when a\nClientResponse emits a 'data' event.\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'end'", - "type": "event", - "name": "end", - "desc": "

function () { }\n\n

\n

Emitted exactly once for each message. No arguments. After\nemitted no other events will be emitted on the response.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function (err) { }\n\n

\n

Indicates that the underlaying connection was terminated before\nend event was emitted.\nSee http.ServerRequest's 'close' event for more\ninformation.\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "response.statusCode", - "name": "statusCode", - "desc": "

The 3-digit HTTP response status code. E.G. 404.\n\n

\n" - }, - { - "textRaw": "response.httpVersion", - "name": "httpVersion", - "desc": "

The HTTP version of the connected-to server. Probably either\n'1.1' or '1.0'.\nAlso response.httpVersionMajor is the first integer and\nresponse.httpVersionMinor is the second.\n\n

\n" - }, - { - "textRaw": "response.headers", - "name": "headers", - "desc": "

The response headers object.\n\n

\n" - }, - { - "textRaw": "response.trailers", - "name": "trailers", - "desc": "

The response trailers object. Only populated after the 'end' event.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "response.setEncoding([encoding])", - "type": "method", - "name": "setEncoding", - "desc": "

Set the encoding for the response body. Either 'utf8', 'ascii', or\n'base64'. Defaults to null, which means that the 'data' event will emit\na Buffer object.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "response.pause()", - "type": "method", - "name": "pause", - "desc": "

Pauses response from emitting events. Useful to throttle back a download.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "response.resume()", - "type": "method", - "name": "resume", - "desc": "

Resumes a paused response.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - } - ], - "type": "module", - "displayName": "HTTP" - }, - { - "textRaw": "HTTPS", - "name": "https", - "stability": 3, - "stabilityText": "Stable", - "desc": "

HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a\nseparate module.\n\n

\n", - "classes": [ - { - "textRaw": "Class: https.Server", - "type": "class", - "name": "https.Server", - "desc": "

This class is a subclass of tls.Server and emits events same as\nhttp.Server. See http.Server for more information.\n\n

\n" - }, - { - "textRaw": "Class: https.Agent", - "type": "class", - "name": "https.Agent", - "desc": "

An Agent object for HTTPS similar to http.Agent.\nSee https.request() for more information.\n\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "https.createServer(options, [requestListener])", - "type": "method", - "name": "createServer", - "desc": "

Returns a new HTTPS web server object. The options is similar to\ntls.createServer(). The requestListener is a function which is\nautomatically added to the 'request' event.\n\n

\n

Example:\n\n

\n
// curl -k https://localhost:8000/\nvar https = require('https');\nvar fs = require('fs');\n\nvar options = {\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\n\nhttps.createServer(options, function (req, res) {\n  res.writeHead(200);\n  res.end("hello world\\n");\n}).listen(8000);
\n

Or\n\n

\n
var https = require('https');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('server.pfx')\n};\n\nhttps.createServer(options, function (req, res) {\n  res.writeHead(200);\n  res.end("hello world\\n");\n}).listen(8000);
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "requestListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "https.request(options, callback)", - "type": "method", - "name": "request", - "desc": "

Makes a request to a secure web server.\nAll options from http.request() are valid.\n\n

\n

Example:\n\n

\n
var https = require('https');\n\nvar options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET'\n};\n\nvar req = https.request(options, function(res) {\n  console.log("statusCode: ", res.statusCode);\n  console.log("headers: ", res.headers);\n\n  res.on('data', function(d) {\n    process.stdout.write(d);\n  });\n});\nreq.end();\n\nreq.on('error', function(e) {\n  console.error(e);\n});
\n

The options argument has the following options\n\n

\n
    \n
  • host: IP or domain of host to make request to. Defaults to 'localhost'.
    • \n
  • port: port of host to request to. Defaults to 443.
    • \n
  • path: Path to request. Default '/'.
    • \n

  • method: HTTP request method. Default 'GET'.

    \n
    • \n

  • host: A domain name or IP address of the server to issue the request to.\nDefaults to 'localhost'.

    \n
    • \n
  • hostname: To support url.parse() hostname is preferred over host
    • \n
  • port: Port of remote server. Defaults to 443.
    • \n
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • \n
  • path: Request path. Defaults to '/'. Should include query string if any.\nE.G. '/index.html?page=12'
    • \n
  • headers: An object containing request headers.
    • \n
  • auth: Basic authentication i.e. 'user:password' to compute an\nAuthorization header.
    • \n
  • agent: Controls Agent behavior. When an Agent is\nused request will default to Connection: keep-alive. Possible values:
      \n
    • undefined (default): use globalAgent for this\nhost and port.
      • \n
    • Agent object: explicitly use the passed in Agent.
      • \n
    • false: opts out of connection pooling with an Agent, defaults request to\nConnection: close.
      • \n
    \n
    • \n
\n

The following options from tls.connect() can also be\nspecified. However, a globalAgent silently ignores these.\n\n

\n
    \n
  • pfx: Certificate, Private key and CA certificates to use for SSL. Default null.
    • \n
  • key: Private key to use for SSL. Default null.
    • \n
  • passphrase: A string of passphrase for the private key or pfx. Default null.
    • \n
  • cert: Public x509 certificate to use. Default null.
    • \n
  • ca: An authority certificate or array of authority certificates to check\nthe remote host against.
    • \n
\n

In order to specify these options, use a custom Agent.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\noptions.agent = new https.Agent(options);\n\nvar req = https.request(options, function(res) {\n  ...\n}
\n

Or does not use an Agent.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),\n  agent: false\n};\n\nvar req = https.request(options, function(res) {\n  ...\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "https.get(options, callback)", - "type": "method", - "name": "get", - "desc": "

Like http.get() but for HTTPS.\n\n

\n

Example:\n\n

\n
var https = require('https');\n\nhttps.get({ host: 'encrypted.google.com', path: '/' }, function(res) {\n  console.log("statusCode: ", res.statusCode);\n  console.log("headers: ", res.headers);\n\n  res.on('data', function(d) {\n    process.stdout.write(d);\n  });\n\n}).on('error', function(e) {\n  console.error(e);\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "callback" - } - ] - } - ] - } - ], - "properties": [ - { - "textRaw": "https.globalAgent", - "name": "globalAgent", - "desc": "

Global instance of https.Agent which is used as the default\nfor all HTTPS client requests.\n\n

\n" - } - ], - "type": "module", - "displayName": "HTTPS" - }, - { - "textRaw": "URL", - "name": "url", - "stability": 3, - "stabilityText": "Stable", - "desc": "

This module has utilities for URL resolution and parsing.\nCall require('url') to use it.\n\n

\n

Parsed URL objects have some or all of the following fields, depending on\nwhether or not they exist in the URL string. Any parts that are not in the URL\nstring will not be in the parsed object. Examples are shown for the URL\n\n

\n

'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'\n\n

\n
    \n

  • href: The full URL that was originally parsed. Both the protocol and host are lowercased.

    \n

    Example: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

    \n
    • \n

  • protocol: The request protocol, lowercased.

    \n

    Example: 'http:'

    \n
    • \n

  • host: The full lowercased host portion of the URL, including port\ninformation.

    \n

    Example: 'host.com:8080'

    \n
    • \n

  • auth: The authentication information portion of a URL.

    \n

    Example: 'user:pass'

    \n
    • \n

  • hostname: Just the lowercased hostname portion of the host.

    \n

    Example: 'host.com'

    \n
    • \n

  • port: The port number portion of the host.

    \n

    Example: '8080'

    \n
    • \n

  • pathname: The path section of the URL, that comes after the host and\nbefore the query, including the initial slash if present.

    \n

    Example: '/p/a/t/h'

    \n
    • \n

  • search: The 'query string' portion of the URL, including the leading\nquestion mark.

    \n

    Example: '?query=string'

    \n
    • \n

  • path: Concatenation of pathname and search.

    \n

    Example: '/p/a/t/h?query=string'

    \n
    • \n

  • query: Either the 'params' portion of the query string, or a\nquerystring-parsed object.

    \n

    Example: 'query=string' or {'query':'string'}

    \n
    • \n

  • hash: The 'fragment' portion of the URL including the pound-sign.

    \n

    Example: '#hash'

    \n
    • \n
\n

The following methods are provided by the URL module:\n\n

\n", - "methods": [ - { - "textRaw": "url.parse(urlStr, [parseQueryString], [slashesDenoteHost])", - "type": "method", - "name": "parse", - "desc": "

Take a URL string, and return an object.\n\n

\n

Pass true as the second argument to also parse\nthe query string using the querystring module.\nDefaults to false.\n\n

\n

Pass true as the third argument to treat //foo/bar as\n{ host: 'foo', pathname: '/bar' } rather than\n{ pathname: '//foo/bar' }. Defaults to false.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "urlStr" - }, - { - "name": "parseQueryString", - "optional": true - }, - { - "name": "slashesDenoteHost", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "url.format(urlObj)", - "type": "method", - "name": "format", - "desc": "

Take a parsed URL object, and return a formatted URL string.\n\n

\n
    \n
  • href will be ignored.
    • \n
  • protocolis treated the same with or without the trailing : (colon).
      \n
    • The protocols http, https, ftp, gopher, file will be\npostfixed with :// (colon-slash-slash).
      • \n
    • All other protocols mailto, xmpp, aim, sftp, foo, etc will\nbe postfixed with : (colon)
      • \n
    \n
    • \n
  • auth will be used if present.
    • \n
  • hostname will only be used if host is absent.
    • \n
  • port will only be used if host is absent.
    • \n
  • host will be used in place of auth, hostname, and port
    • \n
  • pathname is treated the same with or without the leading / (slash)
    • \n
  • search will be used in place of query
    • \n
  • query (object; see querystring) will only be used if search is absent.
    • \n
  • search is treated the same with or without the leading ? (question mark)
    • \n
  • hash is treated the same with or without the leading # (pound sign, anchor)
    • \n
\n", - "signatures": [ - { - "params": [ - { - "name": "urlObj" - } - ] - } - ] - }, - { - "textRaw": "url.resolve(from, to)", - "type": "method", - "name": "resolve", - "desc": "

Take a base URL, and a href URL, and resolve them as a browser would for\nan anchor tag.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "from" - }, - { - "name": "to" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "URL" - }, - { - "textRaw": "Query String", - "name": "querystring", - "stability": 3, - "stabilityText": "Stable", - "desc": "

This module provides utilities for dealing with query strings.\nIt provides the following methods:\n\n

\n", - "methods": [ - { - "textRaw": "querystring.stringify(obj, [sep], [eq])", - "type": "method", - "name": "stringify", - "desc": "

Serialize an object to a query string.\nOptionally override the default separator ('&') and assignment ('=')\ncharacters.\n\n

\n

Example:\n\n

\n
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })\n// returns\n'foo=bar&baz=qux&baz=quux&corge='\n\nquerystring.stringify({foo: 'bar', baz: 'qux'}, ';', ':')\n// returns\n'foo:bar;baz:qux'
\n", - "signatures": [ - { - "params": [ - { - "name": "obj" - }, - { - "name": "sep", - "optional": true - }, - { - "name": "eq", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "querystring.parse(str, [sep], [eq])", - "type": "method", - "name": "parse", - "desc": "

Deserialize a query string to an object.\nOptionally override the default separator ('&') and assignment ('=')\ncharacters.\n\n

\n

Example:\n\n

\n
querystring.parse('foo=bar&baz=qux&baz=quux&corge')\n// returns\n{ foo: 'bar', baz: ['qux', 'quux'], corge: '' }
\n", - "signatures": [ - { - "params": [ - { - "name": "str" - }, - { - "name": "sep", - "optional": true - }, - { - "name": "eq", - "optional": true - } - ] - } - ] - } - ], - "properties": [ - { - "textRaw": "querystring.escape", - "name": "escape", - "desc": "

The escape function used by querystring.stringify,\nprovided so that it could be overridden if necessary.\n\n

\n" - }, - { - "textRaw": "querystring.unescape", - "name": "unescape", - "desc": "

The unescape function used by querystring.parse,\nprovided so that it could be overridden if necessary.\n\n

\n" - } - ], - "type": "module", - "displayName": "querystring" - }, - { - "textRaw": "Readline", - "name": "readline", - "stability": 3, - "stabilityText": "Stable", - "desc": "

To use this module, do require('readline'). Readline allows reading of a\nstream (such as STDIN) on a line-by-line basis.\n\n

\n

Note that once you've invoked this module, your node program will not\nterminate until you've closed the interface, and the STDIN stream. Here's how\nto allow your program to gracefully terminate:\n\n

\n
var rl = require('readline');\n\nvar i = rl.createInterface(process.stdin, process.stdout, null);\ni.question("What do you think of node.js?", function(answer) {\n  // TODO: Log the answer in a database\n  console.log("Thank you for your valuable feedback.");\n\n  // These two lines together allow the program to terminate. Without\n  // them, it would run forever.\n  i.close();\n  process.stdin.destroy();\n});
\n", - "methods": [ - { - "textRaw": "rl.createInterface(input, output, completer)", - "type": "method", - "name": "createInterface", - "desc": "

Takes two streams and creates a readline interface. The completer function\nis used for autocompletion. When given a substring, it returns [[substr1,\nsubstr2, ...], originalsubstring].\n\n

\n

Also completer can be run in async mode if it accepts two arguments:\n\n

\n

function completer(linePartial, callback) {\n callback(null, [['123'], linePartial]);\n }\n\n

\n

createInterface is commonly used with process.stdin and\nprocess.stdout in order to accept user input:\n\n

\n
var readline = require('readline'),\n  rl = readline.createInterface(process.stdin, process.stdout);
\n", - "signatures": [ - { - "params": [ - { - "name": "input" - }, - { - "name": "output" - }, - { - "name": "completer" - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: Interface", - "type": "class", - "name": "Interface", - "desc": "

The class that represents a readline interface with a stdin and stdout\nstream.\n\n

\n", - "methods": [ - { - "textRaw": "rl.setPrompt(prompt, length)", - "type": "method", - "name": "setPrompt", - "desc": "

Sets the prompt, for example when you run node on the command line, you see\n> , which is node's prompt.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "prompt" - }, - { - "name": "length" - } - ] - } - ] - }, - { - "textRaw": "rl.prompt()", - "type": "method", - "name": "prompt", - "desc": "

Readies readline for input from the user, putting the current setPrompt\noptions on a new line, giving the user a new spot to write.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "rl.question(query, callback)", - "type": "method", - "name": "question", - "desc": "

Prepends the prompt with query and invokes callback with the user's\nresponse. Displays the query to the user, and then invokes callback with the\nuser's response after it has been typed.\n\n

\n

Example usage:\n\n

\n
interface.question('What is your favorite food?', function(answer) {\n  console.log('Oh, so your favorite food is ' + answer);\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "query" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "rl.close()", - "type": "method", - "name": "close", - "desc": "

Closes tty.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "rl.pause()", - "type": "method", - "name": "pause", - "desc": "

Pauses tty.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "rl.resume()", - "type": "method", - "name": "resume", - "desc": "

Resumes tty.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "rl.write()", - "type": "method", - "name": "write", - "desc": "

Writes to tty.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "events": [ - { - "textRaw": "Event: 'line'", - "type": "event", - "name": "line", - "desc": "

function (line) {}\n\n

\n

Emitted whenever the in stream receives a \\n, usually received when the\nuser hits enter, or return. This is a good hook to listen for user input.\n\n

\n

Example of listening for line:\n\n

\n
rl.on('line', function (cmd) {\n  console.log('You just typed: '+cmd);\n});
\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () {}\n\n

\n

Emitted whenever the in stream receives a ^C or ^D, respectively known\nas SIGINT and EOT. This is a good way to know the user is finished using\nyour program.\n\n

\n

Example of listening for close, and exiting the program afterward:\n\n

\n
rl.on('close', function() {\n  console.log('goodbye!');\n  process.exit(0);\n});
\n

Here's an example of how to use all these together to craft a tiny command\nline interface:\n\n

\n
var readline = require('readline'),\n  rl = readline.createInterface(process.stdin, process.stdout),\n  prefix = 'OHAI> ';\n\nrl.on('line', function(line) {\n  switch(line.trim()) {\n    case 'hello':\n      console.log('world!');\n      break;\n    default:\n      console.log('Say what? I might have heard `' + line.trim() + '`');\n      break;\n  }\n  rl.setPrompt(prefix, prefix.length);\n  rl.prompt();\n}).on('close', function() {\n  console.log('Have a great day!');\n  process.exit(0);\n});\nconsole.log(prefix + 'Good to see you. Try typing stuff.');\nrl.setPrompt(prefix, prefix.length);\nrl.prompt();
\n

Take a look at this slightly more complicated\nexample, and\nhttp-console for a real-life use\ncase.\n\n

\n", - "params": [] - } - ] - } - ], - "type": "module", - "displayName": "Readline" - }, - { - "textRaw": "REPL", - "name": "repl", - "desc": "

A Read-Eval-Print-Loop (REPL) is available both as a standalone program and easily\nincludable in other programs. REPL provides a way to interactively run\nJavaScript and see the results. It can be used for debugging, testing, or\njust trying things out.\n\n

\n

By executing node without any arguments from the command-line you will be\ndropped into the REPL. It has simplistic emacs line-editing.\n\n

\n
mjr:~$ node\nType '.help' for options.\n> a = [ 1, 2, 3];\n[ 1, 2, 3 ]\n> a.forEach(function (v) {\n...   console.log(v);\n...   });\n1\n2\n3
\n

For advanced line-editors, start node with the environmental variable NODE_NO_READLINE=1.\nThis will start the REPL in canonical terminal settings which will allow you to use with rlwrap.\n\n

\n

For example, you could add this to your bashrc file:\n\n

\n
alias node="env NODE_NO_READLINE=1 rlwrap node"
\n", - "methods": [ - { - "textRaw": "repl.start([prompt], [stream], [eval], [useGlobal], [ignoreUndefined])", - "type": "method", - "name": "start", - "desc": "

Starts a REPL with prompt as the prompt and stream for all I/O. prompt\nis optional and defaults to > . stream is optional and defaults to\nprocess.stdin. eval is optional too and defaults to async wrapper for\neval().\n\n

\n

If useGlobal is set to true, then the repl will use the global object,\ninstead of running scripts in a separate context. Defaults to false.\n\n

\n

If ignoreUndefined is set to true, then the repl will not output return value\nof command if it's undefined. Defaults to false.\n\n

\n

You can use your own eval function if it has following signature:\n\n

\n
function eval(cmd, callback) {\n  callback(null, result);\n}
\n

Multiple REPLs may be started against the same running instance of node. Each\nwill share the same global object but will have unique I/O.\n\n

\n

Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:\n\n

\n
var net = require("net"),\n    repl = require("repl");\n\nconnections = 0;\n\nrepl.start("node via stdin> ");\n\nnet.createServer(function (socket) {\n  connections += 1;\n  repl.start("node via Unix socket> ", socket);\n}).listen("/tmp/node-repl-sock");\n\nnet.createServer(function (socket) {\n  connections += 1;\n  repl.start("node via TCP socket> ", socket);\n}).listen(5001);
\n

Running this program from the command line will start a REPL on stdin. Other\nREPL clients may connect through the Unix socket or TCP socket. telnet is useful\nfor connecting to TCP sockets, and socat can be used to connect to both Unix and\nTCP sockets.\n\n

\n

By starting a REPL from a Unix socket-based server instead of stdin, you can\nconnect to a long-running node process without restarting it.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "prompt", - "optional": true - }, - { - "name": "stream", - "optional": true - }, - { - "name": "eval", - "optional": true - }, - { - "name": "useGlobal", - "optional": true - }, - { - "name": "ignoreUndefined", - "optional": true - } - ] - } - ] - } - ], - "miscs": [ - { - "textRaw": "REPL Features", - "name": "REPL Features", - "type": "misc", - "desc": "

Inside the REPL, Control+D will exit. Multi-line expressions can be input.\nTab completion is supported for both global and local variables.\n\n

\n

The special variable _ (underscore) contains the result of the last expression.\n\n

\n
> [ "a", "b", "c" ]\n[ 'a', 'b', 'c' ]\n> _.length\n3\n> _ += 1\n4
\n

The REPL provides access to any variables in the global scope. You can expose\na variable to the REPL explicitly by assigning it to the context object\nassociated with each REPLServer. For example:\n\n

\n
// repl_test.js\nvar repl = require("repl"),\n    msg = "message";\n\nrepl.start().context.m = msg;
\n

Things in the context object appear as local within the REPL:\n\n

\n
mjr:~$ node repl_test.js\n> m\n'message'
\n

There are a few special REPL commands:\n\n

\n
    \n
  • .break - While inputting a multi-line expression, sometimes you get lost\nor just don't care about completing it. .break will start over.
    • \n
  • .clear - Resets the context object to an empty object and clears any\nmulti-line expression.
    • \n
  • .exit - Close the I/O stream, which will cause the REPL to exit.
    • \n
  • .help - Show this list of special commands.
    • \n
  • .save - Save the current REPL session to a file
    \n

    .save ./file/to/save.js

    \n
    \n
    • \n
  • .load - Load a file into the current REPL session.
    \n

    .load ./file/to/load.js

    \n
    \n
    • \n
\n

The following key combinations in the REPL have these special effects:\n\n

\n
    \n
  • <ctrl>C - Similar to the .break keyword. Terminates the current\ncommand. Press twice on a blank line to forcibly exit.
    • \n
  • <ctrl>D - Similar to the .exit keyword.
    • \n
\n" - } - ], - "type": "module", - "displayName": "REPL" - }, - { - "textRaw": "Executing JavaScript", - "name": "vm", - "stability": 3, - "stabilityText": "Stable", - "desc": "

You can access this module with:\n\n

\n
var vm = require('vm');
\n

JavaScript code can be compiled and run immediately or compiled, saved, and run later.\n\n\n

\n", - "methods": [ - { - "textRaw": "vm.runInThisContext(code, [filename])", - "type": "method", - "name": "runInThisContext", - "desc": "

vm.runInThisContext() compiles code, runs it and returns the result. Running\ncode does not have access to local scope. filename is optional, it's used only\nin stack traces.\n\n

\n

Example of using vm.runInThisContext and eval to run the same code:\n\n

\n
var localVar = 123,\n    usingscript, evaled,\n    vm = require('vm');\n\nusingscript = vm.runInThisContext('localVar = 1;',\n  'myfile.vm');\nconsole.log('localVar: ' + localVar + ', usingscript: ' +\n  usingscript);\nevaled = eval('localVar = 1;');\nconsole.log('localVar: ' + localVar + ', evaled: ' +\n  evaled);\n\n// localVar: 123, usingscript: 1\n// localVar: 1, evaled: 1
\n

vm.runInThisContext does not have access to the local scope, so localVar is unchanged.\neval does have access to the local scope, so localVar is changed.\n\n

\n

In case of syntax error in code, vm.runInThisContext emits the syntax error to stderr\nand throws an exception.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code" - }, - { - "name": "filename", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "vm.runInNewContext(code, [sandbox], [filename])", - "type": "method", - "name": "runInNewContext", - "desc": "

vm.runInNewContext compiles code, then runs it in sandbox and returns the\nresult. Running code does not have access to local scope. The object sandbox\nwill be used as the global object for code.\nsandbox and filename are optional, filename is only used in stack traces.\n\n

\n

Example: compile and execute code that increments a global variable and sets a new one.\nThese globals are contained in the sandbox.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    sandbox = {\n      animal: 'cat',\n      count: 2\n    };\n\nvm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');\nconsole.log(util.inspect(sandbox));\n\n// { animal: 'cat', count: 3, name: 'kitty' }
\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, vm.runInNewContext is quite useful, but safely running untrusted code\nrequires a separate process.\n\n

\n

In case of syntax error in code, vm.runInNewContext emits the syntax error to stderr\nand throws an exception.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code" - }, - { - "name": "sandbox", - "optional": true - }, - { - "name": "filename", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "vm.runInContext(code, context, [filename])", - "type": "method", - "name": "runInContext", - "desc": "

vm.runInContext compiles code, then runs it in context and returns the\nresult. A (V8) context comprises a global object, together with a set of\nbuilt-in objects and functions. Running code does not have access to local scope\nand the global object held within context will be used as the global object\nfor code.\nfilename is optional, it's used only in stack traces.\n\n

\n

Example: compile and execute code in a existing context.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    initSandbox = {\n      animal: 'cat',\n      count: 2\n    },\n    context = vm.createContext(initSandbox);\n\nvm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');\nconsole.log(util.inspect(context));\n\n// { animal: 'cat', count: 3, name: 'CATT' }
\n

Note that createContext will perform a shallow clone of the supplied sandbox object in order to\ninitialise the global object of the freshly constructed context.\n\n

\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, vm.runInContext is quite useful, but safely running untrusted code\nrequires a separate process.\n\n

\n

In case of syntax error in code, vm.runInContext emits the syntax error to stderr\nand throws an exception.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code" - }, - { - "name": "context" - }, - { - "name": "filename", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "vm.createContext([initSandbox])", - "type": "method", - "name": "createContext", - "desc": "

vm.createContext creates a new context which is suitable for use as the 2nd argument of a subsequent\ncall to vm.runInContext. A (V8) context comprises a global object together with a set of\nbuild-in objects and functions. The optional argument initSandbox will be shallow-copied\nto seed the initial contents of the global object used by the context.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "initSandbox", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "vm.createScript(code, [filename])", - "type": "method", - "name": "createScript", - "desc": "

createScript compiles code but does not run it. Instead, it returns a\nvm.Script object representing this compiled code. This script can be run\nlater many times using methods below. The returned script is not bound to any\nglobal object. It is bound before each run, just for that run. filename is\noptional, it's only used in stack traces.\n\n

\n

In case of syntax error in code, createScript prints the syntax error to stderr\nand throws an exception.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code" - }, - { - "name": "filename", - "optional": true - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: Script", - "type": "class", - "name": "Script", - "desc": "

A class for running scripts. Returned by vm.createScript.\n\n

\n", - "methods": [ - { - "textRaw": "script.runInThisContext()", - "type": "method", - "name": "runInThisContext", - "desc": "

Similar to vm.runInThisContext but a method of a precompiled Script object.\nscript.runInThisContext runs the code of script and returns the result.\nRunning code does not have access to local scope, but does have access to the global object\n(v8: in actual context).\n\n

\n

Example of using script.runInThisContext to compile code once and run it multiple times:\n\n

\n
var vm = require('vm');\n\nglobalVar = 0;\n\nvar script = vm.createScript('globalVar += 1', 'myfile.vm');\n\nfor (var i = 0; i < 1000 ; i += 1) {\n  script.runInThisContext();\n}\n\nconsole.log(globalVar);\n\n// 1000
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "script.runInNewContext([sandbox])", - "type": "method", - "name": "runInNewContext", - "desc": "

Similar to vm.runInNewContext a method of a precompiled Script object.\nscript.runInNewContext runs the code of script with sandbox as the global object and returns the result.\nRunning code does not have access to local scope. sandbox is optional.\n\n

\n

Example: compile code that increments a global variable and sets one, then execute this code multiple times.\nThese globals are contained in the sandbox.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    sandbox = {\n      animal: 'cat',\n      count: 2\n    };\n\nvar script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');\n\nfor (var i = 0; i < 10 ; i += 1) {\n  script.runInNewContext(sandbox);\n}\n\nconsole.log(util.inspect(sandbox));\n\n// { animal: 'cat', count: 12, name: 'kitty' }
\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, script.runInNewContext is quite useful, but safely running untrusted code\nrequires a separate process.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "sandbox", - "optional": true - } - ] - } - ] - } - ] - } - ], - "type": "module", - "displayName": "vm" - }, - { - "textRaw": "Child Process", - "name": "child_process", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Node provides a tri-directional popen(3) facility through the\nchild_process module.\n\n

\n

It is possible to stream data through a child's stdin, stdout, and\nstderr in a fully non-blocking way.\n\n

\n

To create a child process use require('child_process').spawn() or\nrequire('child_process').fork(). The semantics of each are slightly\ndifferent, and explained below.\n\n

\n", - "classes": [ - { - "textRaw": "Class: ChildProcess", - "type": "class", - "name": "ChildProcess", - "desc": "

ChildProcess is an EventEmitter.\n\n

\n

Child processes always have three streams associated with them. child.stdin,\nchild.stdout, and child.stderr. These may be shared with the stdio\nstreams of the parent process, or they may be separate stream objects\nwhich can be piped to and from.\n\n

\n

The ChildProcess class is not intended to be used directly. Use the\nspawn() or fork() methods to create a Child Process instance.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'exit'", - "type": "event", - "name": "exit", - "params": [], - "desc": "

This event is emitted after the child process ends. If the process terminated\nnormally, code is the final exit code of the process, otherwise null. If\nthe process terminated due to receipt of a signal, signal is the string name\nof the signal, otherwise null.\n\n

\n

See waitpid(2).\n\n

\n" - } - ], - "properties": [ - { - "textRaw": "`stdin` {Stream object} ", - "name": "stdin", - "desc": "

A Writable Stream that represents the child process's stdin.\nClosing this stream via end() often causes the child process to terminate.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" - }, - { - "textRaw": "`stdout` {Stream object} ", - "name": "stdout", - "desc": "

A Readable Stream that represents the child process's stdout.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" - }, - { - "textRaw": "`stderr` {Stream object} ", - "name": "stderr", - "desc": "

A Readable Stream that represents the child process's stderr.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" - }, - { - "textRaw": "`pid` {Integer} ", - "name": "pid", - "desc": "

The PID of the child process.\n\n

\n

Example:\n\n

\n
var spawn = require('child_process').spawn,\n    grep  = spawn('grep', ['ssh']);\n\nconsole.log('Spawned child pid: ' + grep.pid);\ngrep.stdin.end();
\n" - } - ], - "methods": [ - { - "textRaw": "child.kill([signal])", - "type": "method", - "name": "kill", - "signatures": [ - { - "params": [ - { - "textRaw": "`signal` {String} ", - "name": "signal", - "type": "String", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "signal", - "optional": true - } - ] - } - ], - "desc": "

Send a signal to the child process. If no argument is given, the process will\nbe sent 'SIGTERM'. See signal(7) for a list of available signals.\n\n

\n
var spawn = require('child_process').spawn,\n    grep  = spawn('grep', ['ssh']);\n\ngrep.on('exit', function (code, signal) {\n  console.log('child process terminated due to receipt of signal '+signal);\n});\n\n// send SIGHUP to process\ngrep.kill('SIGHUP');
\n

Note that while the function is called kill, the signal delivered to the child\nprocess may not actually kill it. kill really just sends a signal to a process.\n\n

\n

See kill(2)\n\n

\n" - }, - { - "textRaw": "child.send(message, [sendHandle])", - "type": "method", - "name": "send", - "signatures": [ - { - "params": [ - { - "textRaw": "`message` {Object} ", - "name": "message", - "type": "Object" - }, - { - "textRaw": "`sendHandle` {Handle object} ", - "name": "sendHandle", - "type": "Handle object", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "message" - }, - { - "name": "sendHandle", - "optional": true - } - ] - } - ], - "desc": "

Send a message (and, optionally, a handle object) to a child process.\n\n

\n

See child_process.fork() for details.\n\n

\n" - } - ] - } - ], - "methods": [ - { - "textRaw": "child_process.spawn(command, [args], [options])", - "type": "method", - "name": "spawn", - "signatures": [ - { - "return": { - "textRaw": "return: {ChildProcess object} ", - "name": "return", - "type": "ChildProcess object" - }, - "params": [ - { - "textRaw": "`command` {String} The command to run ", - "name": "command", - "type": "String", - "desc": "The command to run" - }, - { - "textRaw": "`args` {Array} List of string arguments ", - "name": "args", - "type": "Array", - "desc": "List of string arguments", - "optional": true - }, - { - "textRaw": "`options` {Object} ", - "options": [ - { - "textRaw": "`cwd` {String} Current working directory of the child process ", - "name": "cwd", - "type": "String", - "desc": "Current working directory of the child process" - }, - { - "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", - "name": "customFds", - "type": "Array", - "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" - }, - { - "textRaw": "`env` {Object} Environment key-value pairs ", - "name": "env", - "type": "Object", - "desc": "Environment key-value pairs" - }, - { - "textRaw": "`setsid` {Boolean} ", - "name": "setsid", - "type": "Boolean" - } - ], - "name": "options", - "type": "Object", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "command" - }, - { - "name": "args", - "optional": true - }, - { - "name": "options", - "optional": true - } - ] - } - ], - "desc": "

Launches a new process with the given command, with command line arguments in args.\nIf omitted, args defaults to an empty Array.\n\n

\n

The third argument is used to specify additional options, which defaults to:\n\n

\n
{ cwd: undefined,\n  env: process.env\n}
\n

cwd allows you to specify the working directory from which the process is spawned.\nUse env to specify environment variables that will be visible to the new process.\n\n

\n

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:\n\n

\n
var util  = require('util'),\n    spawn = require('child_process').spawn,\n    ls    = spawn('ls', ['-lh', '/usr']);\n\nls.stdout.on('data', function (data) {\n  console.log('stdout: ' + data);\n});\n\nls.stderr.on('data', function (data) {\n  console.log('stderr: ' + data);\n});\n\nls.on('exit', function (code) {\n  console.log('child process exited with code ' + code);\n});
\n

Example: A very elaborate way to run 'ps ax | grep ssh'\n\n

\n
var util  = require('util'),\n    spawn = require('child_process').spawn,\n    ps    = spawn('ps', ['ax']),\n    grep  = spawn('grep', ['ssh']);\n\nps.stdout.on('data', function (data) {\n  grep.stdin.write(data);\n});\n\nps.stderr.on('data', function (data) {\n  console.log('ps stderr: ' + data);\n});\n\nps.on('exit', function (code) {\n  if (code !== 0) {\n    console.log('ps process exited with code ' + code);\n  }\n  grep.stdin.end();\n});\n\ngrep.stdout.on('data', function (data) {\n  console.log(data);\n});\n\ngrep.stderr.on('data', function (data) {\n  console.log('grep stderr: ' + data);\n});\n\ngrep.on('exit', function (code) {\n  if (code !== 0) {\n    console.log('grep process exited with code ' + code);\n  }\n});
\n

Example of checking for failed exec:\n\n

\n
var spawn = require('child_process').spawn,\n    child = spawn('bad_command');\n\nchild.stderr.setEncoding('utf8');\nchild.stderr.on('data', function (data) {\n  if (/^execvp\\(\\)/.test(data)) {\n    console.log('Failed to start child process.');\n  }\n});
\n

Note that if spawn receives an empty options object, it will result in\nspawning the process with an empty environment rather than using\nprocess.env. This due to backwards compatibility issues with a deprecated\nAPI.\n\n

\n

There is a deprecated option called customFds which allows one to specify\nspecific file descriptors for the stdio of the child process. This API was\nnot portable to all platforms and therefore removed.\nWith customFds it was possible to hook up the new process' [stdin, stdout,\nstderr] to existing streams; -1 meant that a new stream should be created.\nUse at your own risk.\n\n

\n

There are several internal options. In particular stdinStream,\nstdoutStream, stderrStream. They are for INTERNAL USE ONLY. As with all\nundocumented APIs in Node, they should not be used.\n\n

\n

See also: child_process.exec() and child_process.fork()\n\n

\n" - }, - { - "textRaw": "child_process.exec(command, [options], callback)", - "type": "method", - "name": "exec", - "signatures": [ - { - "return": { - "textRaw": "Return: ChildProcess object ", - "name": "return", - "desc": "ChildProcess object" - }, - "params": [ - { - "textRaw": "`command` {String} The command to run, with space-separated arguments ", - "name": "command", - "type": "String", - "desc": "The command to run, with space-separated arguments" - }, - { - "textRaw": "`options` {Object} ", - "options": [ - { - "textRaw": "`cwd` {String} Current working directory of the child process ", - "name": "cwd", - "type": "String", - "desc": "Current working directory of the child process" - }, - { - "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", - "name": "customFds", - "type": "Array", - "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" - }, - { - "textRaw": "`env` {Object} Environment key-value pairs ", - "name": "env", - "type": "Object", - "desc": "Environment key-value pairs" - }, - { - "textRaw": "`setsid` {Boolean} ", - "name": "setsid", - "type": "Boolean" - }, - { - "textRaw": "`encoding` {String} (Default: 'utf8') ", - "name": "encoding", - "default": "utf8", - "type": "String" - }, - { - "textRaw": "`timeout` {Number} (Default: 0) ", - "name": "timeout", - "default": "0", - "type": "Number" - }, - { - "textRaw": "`maxBuffer` {Number} (Default: 200*1024) ", - "name": "maxBuffer", - "default": "200*1024", - "type": "Number" - }, - { - "textRaw": "`killSignal` {String} (Default: 'SIGTERM') ", - "name": "killSignal", - "default": "SIGTERM", - "type": "String" - } - ], - "name": "options", - "type": "Object", - "optional": true - }, - { - "textRaw": "`callback` {Function} called with the output when process terminates ", - "options": [ - { - "textRaw": "`error` {Error} ", - "name": "error", - "type": "Error" - }, - { - "textRaw": "`stdout` {Buffer} ", - "name": "stdout", - "type": "Buffer" - }, - { - "textRaw": "`stderr` {Buffer} ", - "name": "stderr", - "type": "Buffer" - } - ], - "name": "callback", - "type": "Function", - "desc": "called with the output when process terminates" - } - ] - }, - { - "params": [ - { - "name": "command" - }, - { - "name": "options", - "optional": true - }, - { - "name": "callback" - } - ] - } - ], - "desc": "

Runs a command in a shell and buffers the output.\n\n

\n
var util = require('util'),\n    exec = require('child_process').exec,\n    child;\n\nchild = exec('cat *.js bad_file | wc -l',\n  function (error, stdout, stderr) {\n    console.log('stdout: ' + stdout);\n    console.log('stderr: ' + stderr);\n    if (error !== null) {\n      console.log('exec error: ' + error);\n    }\n});
\n

The callback gets the arguments (error, stdout, stderr). On success, error\nwill be null. On error, error will be an instance of Error and err.code\nwill be the exit code of the child process, and err.signal will be set to the\nsignal that terminated the process.\n\n

\n

There is a second optional argument to specify several options. The\ndefault options are\n\n

\n
{ encoding: 'utf8',\n  timeout: 0,\n  maxBuffer: 200*1024,\n  killSignal: 'SIGTERM',\n  cwd: null,\n  env: null }
\n

If timeout is greater than 0, then it will kill the child process\nif it runs longer than timeout milliseconds. The child process is killed with\nkillSignal (default: 'SIGTERM'). maxBuffer specifies the largest\namount of data allowed on stdout or stderr - if this value is exceeded then\nthe child process is killed.\n\n\n

\n" - }, - { - "textRaw": "child_process.execFile(file, args, options, callback)", - "type": "method", - "name": "execFile", - "signatures": [ - { - "return": { - "textRaw": "Return: ChildProcess object ", - "name": "return", - "desc": "ChildProcess object" - }, - "params": [ - { - "textRaw": "`file` {String} The filename of the program to run ", - "name": "file", - "type": "String", - "desc": "The filename of the program to run" - }, - { - "textRaw": "`args` {Array} List of string arguments ", - "name": "args", - "type": "Array", - "desc": "List of string arguments" - }, - { - "textRaw": "`options` {Object} ", - "options": [ - { - "textRaw": "`cwd` {String} Current working directory of the child process ", - "name": "cwd", - "type": "String", - "desc": "Current working directory of the child process" - }, - { - "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", - "name": "customFds", - "type": "Array", - "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" - }, - { - "textRaw": "`env` {Object} Environment key-value pairs ", - "name": "env", - "type": "Object", - "desc": "Environment key-value pairs" - }, - { - "textRaw": "`setsid` {Boolean} ", - "name": "setsid", - "type": "Boolean" - }, - { - "textRaw": "`encoding` {String} (Default: 'utf8') ", - "name": "encoding", - "default": "utf8", - "type": "String" - }, - { - "textRaw": "`timeout` {Number} (Default: 0) ", - "name": "timeout", - "default": "0", - "type": "Number" - }, - { - "textRaw": "`maxBuffer` {Number} (Default: 200*1024) ", - "name": "maxBuffer", - "default": "200*1024", - "type": "Number" - }, - { - "textRaw": "`killSignal` {String} (Default: 'SIGTERM') ", - "name": "killSignal", - "default": "SIGTERM", - "type": "String" - } - ], - "name": "options", - "type": "Object" - }, - { - "textRaw": "`callback` {Function} called with the output when process terminates ", - "options": [ - { - "textRaw": "`error` {Error} ", - "name": "error", - "type": "Error" - }, - { - "textRaw": "`stdout` {Buffer} ", - "name": "stdout", - "type": "Buffer" - }, - { - "textRaw": "`stderr` {Buffer} ", - "name": "stderr", - "type": "Buffer" - } - ], - "name": "callback", - "type": "Function", - "desc": "called with the output when process terminates" - } - ] - }, - { - "params": [ - { - "name": "file" - }, - { - "name": "args" - }, - { - "name": "options" - }, - { - "name": "callback" - } - ] - } - ], - "desc": "

This is similar to child_process.exec() except it does not execute a\nsubshell but rather the specified file directly. This makes it slightly\nleaner than child_process.exec. It has the same options.\n\n\n

\n" - }, - { - "textRaw": "child_process.fork(modulePath, [args], [options])", - "type": "method", - "name": "fork", - "signatures": [ - { - "return": { - "textRaw": "Return: ChildProcess object ", - "name": "return", - "desc": "ChildProcess object" - }, - "params": [ - { - "textRaw": "`modulePath` {String} The module to run in the child ", - "name": "modulePath", - "type": "String", - "desc": "The module to run in the child" - }, - { - "textRaw": "`args` {Array} List of string arguments ", - "name": "args", - "type": "Array", - "desc": "List of string arguments", - "optional": true - }, - { - "textRaw": "`options` {Object} ", - "options": [ - { - "textRaw": "`cwd` {String} Current working directory of the child process ", - "name": "cwd", - "type": "String", - "desc": "Current working directory of the child process" - }, - { - "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", - "name": "customFds", - "type": "Array", - "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" - }, - { - "textRaw": "`env` {Object} Environment key-value pairs ", - "name": "env", - "type": "Object", - "desc": "Environment key-value pairs" - }, - { - "textRaw": "`setsid` {Boolean} ", - "name": "setsid", - "type": "Boolean" - }, - { - "textRaw": "`encoding` {String} (Default: 'utf8') ", - "name": "encoding", - "default": "utf8", - "type": "String" - }, - { - "textRaw": "`timeout` {Number} (Default: 0) ", - "name": "timeout", - "default": "0", - "type": "Number" - } - ], - "name": "options", - "type": "Object", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "modulePath" - }, - { - "name": "args", - "optional": true - }, - { - "name": "options", - "optional": true - } - ] - } - ], - "desc": "

This is a special case of the spawn() functionality for spawning Node\nprocesses. In addition to having all the methods in a normal ChildProcess\ninstance, the returned object has a communication channel built-in. The\nchannel is written to with child.send(message, [sendHandle]) and messages\nare received by a 'message' event on the child.\n\n

\n

For example:\n\n

\n
var cp = require('child_process');\n\nvar n = cp.fork(__dirname + '/sub.js');\n\nn.on('message', function(m) {\n  console.log('PARENT got message:', m);\n});\n\nn.send({ hello: 'world' });
\n

And then the child script, 'sub.js' might look like this:\n\n

\n
process.on('message', function(m) {\n  console.log('CHILD got message:', m);\n});\n\nprocess.send({ foo: 'bar' });
\n

In the child the process object will have a send() method, and process\nwill emit objects each time it receives a message on its channel.\n\n

\n

By default the spawned Node process will have the stdin, stdout, stderr\nassociated with the parent's.\n\n

\n

These child Nodes are still whole new instances of V8. Assume at least 30ms\nstartup and 10mb memory for each new Node. That is, you cannot create many\nthousands of them.\n\n

\n

The sendHandle option to child.send() is for sending a handle object to\nanother process. Child will receive the handle as as second argument to the\nmessage event. Here is an example of sending a handle:\n\n

\n
var server = require('net').createServer();\nvar child = require('child_process').fork(__dirname + '/child.js');\n// Open up the server object and send the handle.\nserver.listen(1337, function() {\n  child.send({ server: true }, server._handle);\n});
\n

Here is an example of receiving the server handle and sharing it between\nprocesses:\n\n

\n
process.on('message', function(m, serverHandle) {\n  if (serverHandle) {\n    var server = require('net').createServer();\n    server.listen(serverHandle);\n  }\n});
\n" - } - ], - "type": "module", - "displayName": "Child Process" - }, - { - "textRaw": "Assert", - "name": "assert", - "stability": 5, - "stabilityText": "Locked", - "desc": "

This module is used for writing unit tests for your applications, you can\naccess it with require('assert').\n\n

\n", - "methods": [ - { - "textRaw": "assert.fail(actual, expected, message, operator)", - "type": "method", - "name": "fail", - "desc": "

Throws an exception that displays the values for actual and expected separated by the provided operator.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message" - }, - { - "name": "operator" - } - ] - } - ] - }, - { - "textRaw": "assert(value, message), assert.ok(value, [message])", - "type": "method", - "name": "ok", - "desc": "

Tests if value is a true value, it is equivalent to assert.equal(true, value, message);\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "value" - }, - { - "name": "message)" - }, - { - "name": "assert.ok(value" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.equal(actual, expected, [message])", - "type": "method", - "name": "equal", - "desc": "

Tests shallow, coercive equality with the equal comparison operator ( == ).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.notEqual(actual, expected, [message])", - "type": "method", - "name": "notEqual", - "desc": "

Tests shallow, coercive non-equality with the not equal comparison operator ( != ).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.deepEqual(actual, expected, [message])", - "type": "method", - "name": "deepEqual", - "desc": "

Tests for deep equality.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.notDeepEqual(actual, expected, [message])", - "type": "method", - "name": "notDeepEqual", - "desc": "

Tests for any deep inequality.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.strictEqual(actual, expected, [message])", - "type": "method", - "name": "strictEqual", - "desc": "

Tests strict equality, as determined by the strict equality operator ( === )\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.notStrictEqual(actual, expected, [message])", - "type": "method", - "name": "notStrictEqual", - "desc": "

Tests strict non-equality, as determined by the strict not equal operator ( !== )\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.throws(block, [error], [message])", - "type": "method", - "name": "throws", - "desc": "

Expects block to throw an error. error can be constructor, regexp or \nvalidation function.\n\n

\n

Validate instanceof using constructor:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  Error\n);
\n

Validate error message using RegExp:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  /value/\n);
\n

Custom error validation:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  function(err) {\n    if ( (err instanceof Error) && /value/.test(err) ) {\n      return true;\n    }\n  },\n  "unexpected error"\n);
\n", - "signatures": [ - { - "params": [ - { - "name": "block" - }, - { - "name": "error", - "optional": true - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.doesNotThrow(block, [error], [message])", - "type": "method", - "name": "doesNotThrow", - "desc": "

Expects block not to throw an error, see assert.throws for details.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "block" - }, - { - "name": "error", - "optional": true - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.ifError(value)", - "type": "method", - "name": "ifError", - "desc": "

Tests if value is not a false value, throws if it is a true value. Useful when\ntesting the first argument, error in callbacks.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "value" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "Assert" - }, - { - "textRaw": "TTY", - "name": "tty", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Use require('tty') to access this module.\n\n

\n

Example:\n\n

\n
var tty = require('tty');\nprocess.stdin.resume();\ntty.setRawMode(true);\nprocess.stdin.on('keypress', function(char, key) {\n  if (key && key.ctrl && key.name == 'c') {\n    console.log('graceful exit');\n    process.exit()\n  }\n});
\n", - "methods": [ - { - "textRaw": "tty.isatty(fd)", - "type": "method", - "name": "isatty", - "desc": "

Returns true or false depending on if the fd is associated with a\nterminal.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - } - ] - } - ] - }, - { - "textRaw": "tty.setRawMode(mode)", - "type": "method", - "name": "setRawMode", - "desc": "

mode should be true or false. This sets the properties of the current\nprocess's stdin fd to act either as a raw device or default.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "mode" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "TTY" - }, - { - "textRaw": "Zlib", - "name": "zlib", - "stability": 3, - "stabilityText": "Stable", - "desc": "

You can access this module with:\n\n

\n
var zlib = require('zlib');
\n

This provides bindings to Gzip/Gunzip, Deflate/Inflate, and\nDeflateRaw/InflateRaw classes. Each class takes the same options, and\nis a readable/writable Stream.\n\n

\n

Examples

\n

Compressing or decompressing a file can be done by piping an\nfs.ReadStream into a zlib stream, then into an fs.WriteStream.\n\n

\n
var gzip = zlib.createGzip();\nvar fs = require('fs');\nvar inp = fs.createReadStream('input.txt');\nvar out = fs.createWriteStream('input.txt.gz');\n\ninp.pipe(gzip).pipe(out);
\n

Compressing or decompressing data in one step can be done by using\nthe convenience methods.\n\n

\n
var input = '.................................';\nzlib.deflate(input, function(err, buffer) {\n  if (!err) {\n    console.log(buffer.toString('base64'));\n  }\n});\n\nvar buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');\nzlib.unzip(buffer, function(err, buffer) {\n  if (!err) {\n    console.log(buffer.toString());\n  }\n});
\n

To use this module in an HTTP client or server, use the\naccept-encoding\non requests, and the\ncontent-encoding\nheader on responses.\n\n

\n

Note: these examples are drastically simplified to show\nthe basic concept. Zlib encoding can be expensive, and the results\nought to be cached. See Memory Usage Tuning\nbelow for more information on the speed/memory/compression\ntradeoffs involved in zlib usage.\n\n

\n
// client request example\nvar zlib = require('zlib');\nvar http = require('http');\nvar fs = require('fs');\nvar request = http.get({ host: 'izs.me',\n                         path: '/',\n                         port: 80,\n                         headers: { 'accept-encoding': 'gzip,deflate' } });\nrequest.on('response', function(response) {\n  var output = fs.createWriteStream('izs.me_index.html');\n\n  switch (response.headers['content-encoding']) {\n    // or, just use zlib.createUnzip() to handle both cases\n    case 'gzip':\n      response.pipe(zlib.createGunzip()).pipe(output);\n      break;\n    case 'deflate':\n      response.pipe(zlib.createInflate()).pipe(output);\n      break;\n    default:\n      response.pipe(output);\n      break;\n  }\n});\n\n// server example\n// Running a gzip operation on every request is quite expensive.\n// It would be much more efficient to cache the compressed buffer.\nvar zlib = require('zlib');\nvar http = require('http');\nvar fs = require('fs');\nhttp.createServer(function(request, response) {\n  var raw = fs.createReadStream('index.html');\n  var acceptEncoding = request.headers['accept-encoding'];\n  if (!acceptEncoding) {\n    acceptEncoding = '';\n  }\n\n  // Note: this is not a conformant accept-encoding parser.\n  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3\n  if (acceptEncoding.match(/\\bdeflate\\b/)) {\n    response.writeHead(200, { 'content-encoding': 'deflate' });\n    raw.pipe(zlib.createDeflate()).pipe(response);\n  } else if (acceptEncoding.match(/\\bgzip\\b/)) {\n    response.writeHead(200, { 'content-encoding': 'gzip' });\n    raw.pipe(zlib.createGzip()).pipe(response);\n  } else {\n    response.writeHead(200, {});\n    raw.pipe(response);\n  }\n}).listen(1337);
\n", - "miscs": [ - { - "textRaw": "Constants", - "name": "Constants", - "type": "misc", - "desc": "

All of the constants defined in zlib.h are also defined on\nrequire('zlib'). They are described in more detail in the zlib\ndocumentation. See http://zlib.net/manual.html#Constants\nfor more details.\n\n

\n" - }, - { - "textRaw": "Convenience Methods", - "name": "Convenience Methods", - "type": "misc", - "desc": "

All of these take a string or buffer as the first argument, and call the\nsupplied callback with callback(error, result). The\ncompression/decompression engine is created using the default settings\nin all convenience methods. To supply different options, use the\nzlib classes directly.\n\n

\n" - }, - { - "textRaw": "Options", - "name": "Options", - "type": "misc", - "desc": "

Each class takes an options object. All options are optional. (The\nconvenience methods use the default settings for all options.)\n\n

\n

Note that some options are only\nrelevant when compressing, and are ignored by the decompression classes.\n\n

\n
    \n
  • chunkSize (default: 16*1024)
    • \n
  • windowBits
    • \n
  • level (compression only)
    • \n
  • memLevel (compression only)
    • \n
  • strategy (compression only)
    • \n
\n

See the description of deflateInit2 and inflateInit2 at\n

\n

http://zlib.net/manual.html#Advanced for more information on these.\n\n

\n" - }, - { - "textRaw": "Memory Usage Tuning", - "name": "Memory Usage Tuning", - "type": "misc", - "desc": "

From zlib/zconf.h, modified to node's usage:\n\n

\n

The memory requirements for deflate are (in bytes):\n\n

\n
(1 << (windowBits+2)) +  (1 << (memLevel+9))
\n

that is: 128K for windowBits=15 + 128K for memLevel = 8\n(default values) plus a few kilobytes for small objects.\n\n

\n

For example, if you want to reduce\nthe default memory requirements from 256K to 128K, set the options to:\n\n

\n
{ windowBits: 14, memLevel: 7 }
\n

Of course this will generally degrade compression (there's no free lunch).\n\n

\n

The memory requirements for inflate are (in bytes)\n\n

\n
1 << windowBits
\n

that is, 32K for windowBits=15 (default value) plus a few kilobytes\nfor small objects.\n\n

\n

This is in addition to a single internal output slab buffer of size\nchunkSize, which defaults to 16K.\n\n

\n

The speed of zlib compression is affected most dramatically by the\nlevel setting. A higher level will result in better compression, but\nwill take longer to complete. A lower level will result in less\ncompression, but will be much faster.\n\n

\n

In general, greater memory usage options will mean that node has to make\nfewer calls to zlib, since it'll be able to process more data in a\nsingle write operation. So, this is another factor that affects the\nspeed, at the cost of memory usage.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "zlib.createGzip([options])", - "type": "method", - "name": "createGzip", - "desc": "

Returns a new Gzip object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createGunzip([options])", - "type": "method", - "name": "createGunzip", - "desc": "

Returns a new Gunzip object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createDeflate([options])", - "type": "method", - "name": "createDeflate", - "desc": "

Returns a new Deflate object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createInflate([options])", - "type": "method", - "name": "createInflate", - "desc": "

Returns a new Inflate object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createDeflateRaw([options])", - "type": "method", - "name": "createDeflateRaw", - "desc": "

Returns a new DeflateRaw object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createInflateRaw([options])", - "type": "method", - "name": "createInflateRaw", - "desc": "

Returns a new InflateRaw object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createUnzip([options])", - "type": "method", - "name": "createUnzip", - "desc": "

Returns a new Unzip object with an options.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.deflate(buf, callback)", - "type": "method", - "name": "deflate", - "desc": "

Compress a string with Deflate.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.deflateRaw(buf, callback)", - "type": "method", - "name": "deflateRaw", - "desc": "

Compress a string with DeflateRaw.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.gzip(buf, callback)", - "type": "method", - "name": "gzip", - "desc": "

Compress a string with Gzip.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.gunzip(buf, callback)", - "type": "method", - "name": "gunzip", - "desc": "

Decompress a raw Buffer with Gunzip.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.inflate(buf, callback)", - "type": "method", - "name": "inflate", - "desc": "

Decompress a raw Buffer with Inflate.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.inflateRaw(buf, callback)", - "type": "method", - "name": "inflateRaw", - "desc": "

Decompress a raw Buffer with InflateRaw.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.unzip(buf, callback)", - "type": "method", - "name": "unzip", - "desc": "

Decompress a raw Buffer with Unzip.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: zlib.Gzip", - "type": "class", - "name": "zlib.Gzip", - "desc": "

Compress data using gzip.\n\n

\n" - }, - { - "textRaw": "Class: zlib.Gunzip", - "type": "class", - "name": "zlib.Gunzip", - "desc": "

Decompress a gzip stream.\n\n

\n" - }, - { - "textRaw": "Class: zlib.Deflate", - "type": "class", - "name": "zlib.Deflate", - "desc": "

Compress data using deflate.\n\n

\n" - }, - { - "textRaw": "Class: zlib.Inflate", - "type": "class", - "name": "zlib.Inflate", - "desc": "

Decompress a deflate stream.\n\n

\n" - }, - { - "textRaw": "Class: zlib.DeflateRaw", - "type": "class", - "name": "zlib.DeflateRaw", - "desc": "

Compress data using deflate, and do not append a zlib header.\n\n

\n" - }, - { - "textRaw": "Class: zlib.InflateRaw", - "type": "class", - "name": "zlib.InflateRaw", - "desc": "

Decompress a raw deflate stream.\n\n

\n" - }, - { - "textRaw": "Class: zlib.Unzip", - "type": "class", - "name": "zlib.Unzip", - "desc": "

Decompress either a Gzip- or Deflate-compressed stream by auto-detecting\nthe header.\n\n

\n" - } - ], - "type": "module", - "displayName": "Zlib" - }, - { - "textRaw": "os", - "name": "os", - "stability": 4, - "stabilityText": "API Frozen", - "desc": "

Provides a few basic operating-system related utility functions.\n\n

\n

Use require('os') to access this module.\n\n

\n", - "methods": [ - { - "textRaw": "os.hostname()", - "type": "method", - "name": "hostname", - "desc": "

Returns the hostname of the operating system.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.type()", - "type": "method", - "name": "type", - "desc": "

Returns the operating system name.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.platform()", - "type": "method", - "name": "platform", - "desc": "

Returns the operating system platform.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.arch()", - "type": "method", - "name": "arch", - "desc": "

Returns the operating system CPU architecture.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.release()", - "type": "method", - "name": "release", - "desc": "

Returns the operating system release.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.uptime()", - "type": "method", - "name": "uptime", - "desc": "

Returns the system uptime in seconds.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.loadavg()", - "type": "method", - "name": "loadavg", - "desc": "

Returns an array containing the 1, 5, and 15 minute load averages.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.totalmem()", - "type": "method", - "name": "totalmem", - "desc": "

Returns the total amount of system memory in bytes.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.freemem()", - "type": "method", - "name": "freemem", - "desc": "

Returns the amount of free system memory in bytes.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.cpus()", - "type": "method", - "name": "cpus", - "desc": "

Returns an array of objects containing information about each CPU/core installed: model, speed (in MHz), and times (an object containing the number of CPU ticks spent in: user, nice, sys, idle, and irq).\n\n

\n

Example inspection of os.cpus:\n\n

\n
[ { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 252020,\n       nice: 0,\n       sys: 30340,\n       idle: 1070356870,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 306960,\n       nice: 0,\n       sys: 26980,\n       idle: 1071569080,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 248450,\n       nice: 0,\n       sys: 21750,\n       idle: 1070919370,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 256880,\n       nice: 0,\n       sys: 19430,\n       idle: 1070905480,\n       irq: 20 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 511580,\n       nice: 20,\n       sys: 40900,\n       idle: 1070842510,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 291660,\n       nice: 0,\n       sys: 34360,\n       idle: 1070888000,\n       irq: 10 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 308260,\n       nice: 0,\n       sys: 55410,\n       idle: 1071129970,\n       irq: 880 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 266450,\n       nice: 1480,\n       sys: 34920,\n       idle: 1072572010,\n       irq: 30 } } ]
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.networkInterfaces()", - "type": "method", - "name": "networkInterfaces", - "desc": "

Get a list of network interfaces:\n\n

\n
{ lo0: \n   [ { address: '::1', family: 'IPv6', internal: true },\n     { address: 'fe80::1', family: 'IPv6', internal: true },\n     { address: '127.0.0.1', family: 'IPv4', internal: true } ],\n  en1: \n   [ { address: 'fe80::cabc:c8ff:feef:f996', family: 'IPv6',\n       internal: false },\n     { address: '10.0.1.123', family: 'IPv4', internal: false } ],\n  vmnet1: [ { address: '10.99.99.254', family: 'IPv4', internal: false } ],\n  vmnet8: [ { address: '10.88.88.1', family: 'IPv4', internal: false } ],\n  ppp0: [ { address: '10.2.0.231', family: 'IPv4', internal: false } ] }
\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "type": "module", - "displayName": "os" - }, - { - "textRaw": "Cluster", - "name": "cluster", - "stability": 1, - "stabilityText": "Experimental - Drastic changes in future versions", - "desc": "

A single instance of Node runs in a single thread. To take advantage of\nmulti-core systems the user will sometimes want to launch a cluster of Node\nprocesses to handle the load.\n\n

\n

The cluster module allows you to easily create a network of processes that\nall share server ports.\n\n

\n
var cluster = require('cluster');\nvar http = require('http');\nvar numCPUs = require('os').cpus().length;\n\nif (cluster.isMaster) {\n  // Fork workers.\n  for (var i = 0; i < numCPUs; i++) {\n    cluster.fork();\n  }\n\n  cluster.on('death', function(worker) {\n    console.log('worker ' + worker.pid + ' died');\n  });\n} else {\n  // Worker processes have a http server.\n  http.Server(function(req, res) {\n    res.writeHead(200);\n    res.end("hello world\\n");\n  }).listen(8000);\n}
\n

Running node will now share port 8000 between the workers:\n\n

\n
% node server.js\nWorker 2438 online\nWorker 2437 online
\n

The difference between cluster.fork() and child_process.fork() is simply\nthat cluster allows TCP servers to be shared between workers. cluster.fork\nis implemented on top of child_process.fork. The message passing API that\nis available with child_process.fork is available with cluster as well.\nAs an example, here is a cluster which keeps count of the number of requests\nin the master process via message passing:\n\n

\n
var cluster = require('cluster');\nvar http = require('http');\nvar numReqs = 0;\n\nif (cluster.isMaster) {\n  // Fork workers.\n  for (var i = 0; i < 2; i++) {\n    var worker = cluster.fork();\n\n    worker.on('message', function(msg) {\n      if (msg.cmd && msg.cmd == 'notifyRequest') {\n        numReqs++;\n      }\n    });\n  }\n\n  setInterval(function() {\n    console.log("numReqs =", numReqs);\n  }, 1000);\n} else {\n  // Worker processes have a http server.\n  http.Server(function(req, res) {\n    res.writeHead(200);\n    res.end("hello world\\n");\n    // Send message to master process\n    process.send({ cmd: 'notifyRequest' });\n  }).listen(8000);\n}
\n", - "methods": [ - { - "textRaw": "cluster.fork()", - "type": "method", - "name": "fork", - "desc": "

Spawn a new worker process. This can only be called from the master process.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "properties": [ - { - "textRaw": "cluster.isMaster", - "name": "isMaster", - "desc": "

Boolean flags to determine if the current process is a master or a worker\nprocess in a cluster. A process isMaster if process.env.NODE_WORKER_ID\nis undefined.\n\n

\n" - }, - { - "textRaw": "cluster.isWorker", - "name": "isWorker", - "desc": "

Boolean flags to determine if the current process is a master or a worker\nprocess in a cluster. A process isMaster if process.env.NODE_WORKER_ID\nis undefined.\n\n

\n" - } - ], - "events": [ - { - "textRaw": "Event: 'death'", - "type": "event", - "name": "death", - "desc": "

When any of the workers die the cluster module will emit the 'death' event.\nThis can be used to restart the worker by calling fork() again.\n\n

\n
cluster.on('death', function(worker) {\n  console.log('worker ' + worker.pid + ' died. restart...');\n  cluster.fork();\n});
\n

Different techniques can be used to restart the worker depending on the\napplication.\n\n

\n", - "params": [] - } - ], - "type": "module", - "displayName": "Cluster" - }, - { - "textRaw": "Appendix 1 - Third Party Modules", - "name": "appendix_1_-_third_party_modules", - "desc": "

There are many third party modules for Node. At the time of writing, August\n2010, the master repository of modules is\nthe wiki page.\n\n

\n

This appendix is intended as a SMALL guide to new-comers to help them\nquickly find what are considered to be quality modules. It is not intended\nto be a complete list. There may be better more complete modules found\nelsewhere.\n\n

\n\n

Patches to this list are welcome.\n\n

\n", - "type": "module", - "displayName": "Appendix 1 - Third Party Modules" - } - ], - "stability": 3, - "stabilityText": "Stable" -} --- a/doc/api/api/appendix_1.html +++ /dev/null @@ -1,138 +0,0 @@ - - - - - Appendix 1 - Third Party Modules Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- -
-

Table of Contents

- - -
- -
-

Appendix 1 - Third Party Modules#

-

There are many third party modules for Node. At the time of writing, August -2010, the master repository of modules is -the wiki page. - -

-

This appendix is intended as a SMALL guide to new-comers to help them -quickly find what are considered to be quality modules. It is not intended -to be a complete list. There may be better more complete modules found -elsewhere. - -

- -

Patches to this list are welcome. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/appendix_1.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "source": "doc/api/appendix_1.markdown", - "modules": [ - { - "textRaw": "Appendix 1 - Third Party Modules", - "name": "appendix_1_-_third_party_modules", - "desc": "

There are many third party modules for Node. At the time of writing, August\n2010, the master repository of modules is\nthe wiki page.\n\n

\n

This appendix is intended as a SMALL guide to new-comers to help them\nquickly find what are considered to be quality modules. It is not intended\nto be a complete list. There may be better more complete modules found\nelsewhere.\n\n

\n\n

Patches to this list are welcome.\n

\n", - "type": "module", - "displayName": "Appendix 1 - Third Party Modules" - } - ] -} --- a/doc/api/api/assert.html +++ /dev/null @@ -1,186 +0,0 @@ - - - - - Assert Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Assert#

-
Stability: 5 - Locked
-

This module is used for writing unit tests for your applications, you can -access it with require('assert'). - -

-

assert.fail(actual, expected, message, operator)#

-

Throws an exception that displays the values for actual and expected separated by the provided operator. - -

-

assert(value, message), assert.ok(value, [message])#

-

Tests if value is a true value, it is equivalent to assert.equal(true, value, message); - -

-

assert.equal(actual, expected, [message])#

-

Tests shallow, coercive equality with the equal comparison operator ( == ). - -

-

assert.notEqual(actual, expected, [message])#

-

Tests shallow, coercive non-equality with the not equal comparison operator ( != ). - -

-

assert.deepEqual(actual, expected, [message])#

-

Tests for deep equality. - -

-

assert.notDeepEqual(actual, expected, [message])#

-

Tests for any deep inequality. - -

-

assert.strictEqual(actual, expected, [message])#

-

Tests strict equality, as determined by the strict equality operator ( === ) - -

-

assert.notStrictEqual(actual, expected, [message])#

-

Tests strict non-equality, as determined by the strict not equal operator ( !== ) - -

-

assert.throws(block, [error], [message])#

-

Expects block to throw an error. error can be constructor, regexp or -validation function. - -

-

Validate instanceof using constructor: - -

-
assert.throws(
-  function() {
-    throw new Error("Wrong value");
-  },
-  Error
-);
-

Validate error message using RegExp: - -

-
assert.throws(
-  function() {
-    throw new Error("Wrong value");
-  },
-  /value/
-);
-

Custom error validation: - -

-
assert.throws(
-  function() {
-    throw new Error("Wrong value");
-  },
-  function(err) {
-    if ( (err instanceof Error) && /value/.test(err) ) {
-      return true;
-    }
-  },
-  "unexpected error"
-);
-

assert.doesNotThrow(block, [error], [message])#

-

Expects block not to throw an error, see assert.throws for details. - -

-

assert.ifError(value)#

-

Tests if value is not a false value, throws if it is a true value. Useful when -testing the first argument, error in callbacks. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/assert.json +++ /dev/null @@ -1,258 +0,0 @@ -{ - "source": "doc/api/assert.markdown", - "modules": [ - { - "textRaw": "Assert", - "name": "assert", - "stability": 5, - "stabilityText": "Locked", - "desc": "

This module is used for writing unit tests for your applications, you can\naccess it with require('assert').\n\n

\n", - "methods": [ - { - "textRaw": "assert.fail(actual, expected, message, operator)", - "type": "method", - "name": "fail", - "desc": "

Throws an exception that displays the values for actual and expected separated by the provided operator.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message" - }, - { - "name": "operator" - } - ] - } - ] - }, - { - "textRaw": "assert(value, message), assert.ok(value, [message])", - "type": "method", - "name": "ok", - "desc": "

Tests if value is a true value, it is equivalent to assert.equal(true, value, message);\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "value" - }, - { - "name": "message)" - }, - { - "name": "assert.ok(value" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.equal(actual, expected, [message])", - "type": "method", - "name": "equal", - "desc": "

Tests shallow, coercive equality with the equal comparison operator ( == ).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.notEqual(actual, expected, [message])", - "type": "method", - "name": "notEqual", - "desc": "

Tests shallow, coercive non-equality with the not equal comparison operator ( != ).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.deepEqual(actual, expected, [message])", - "type": "method", - "name": "deepEqual", - "desc": "

Tests for deep equality.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.notDeepEqual(actual, expected, [message])", - "type": "method", - "name": "notDeepEqual", - "desc": "

Tests for any deep inequality.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.strictEqual(actual, expected, [message])", - "type": "method", - "name": "strictEqual", - "desc": "

Tests strict equality, as determined by the strict equality operator ( === )\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.notStrictEqual(actual, expected, [message])", - "type": "method", - "name": "notStrictEqual", - "desc": "

Tests strict non-equality, as determined by the strict not equal operator ( !== )\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "actual" - }, - { - "name": "expected" - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.throws(block, [error], [message])", - "type": "method", - "name": "throws", - "desc": "

Expects block to throw an error. error can be constructor, regexp or \nvalidation function.\n\n

\n

Validate instanceof using constructor:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  Error\n);
\n

Validate error message using RegExp:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  /value/\n);
\n

Custom error validation:\n\n

\n
assert.throws(\n  function() {\n    throw new Error("Wrong value");\n  },\n  function(err) {\n    if ( (err instanceof Error) && /value/.test(err) ) {\n      return true;\n    }\n  },\n  "unexpected error"\n);
\n", - "signatures": [ - { - "params": [ - { - "name": "block" - }, - { - "name": "error", - "optional": true - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.doesNotThrow(block, [error], [message])", - "type": "method", - "name": "doesNotThrow", - "desc": "

Expects block not to throw an error, see assert.throws for details.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "block" - }, - { - "name": "error", - "optional": true - }, - { - "name": "message", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "assert.ifError(value)", - "type": "method", - "name": "ifError", - "desc": "

Tests if value is not a false value, throws if it is a true value. Useful when\ntesting the first argument, error in callbacks.\n

\n", - "signatures": [ - { - "params": [ - { - "name": "value" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "Assert" - } - ] -} --- a/doc/api/api/buffer.html +++ /dev/null @@ -1,837 +0,0 @@ - - - - - Buffer Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- -
-

Table of Contents

- - -
- -
-

Buffer#

-
Stability: 3 - Stable
-

Pure Javascript is Unicode friendly but not nice to binary data. When -dealing with TCP streams or the file system, it's necessary to handle octet -streams. Node has several strategies for manipulating, creating, and -consuming octet streams. - -

-

Raw data is stored in instances of the Buffer class. A Buffer is similar -to an array of integers but corresponds to a raw memory allocation outside -the V8 heap. A Buffer cannot be resized. - -

-

The Buffer class is a global, making it very rare that one would need -to ever require('buffer'). - -

-

Converting between Buffers and JavaScript string objects requires an explicit -encoding method. Here are the different string encodings. - -

-
    -

  • 'ascii' - for 7 bit ASCII data only. This encoding method is very fast, and -will strip the high bit if set. -Note that this encoding converts a null character ('\0' or '\u0000') into -0x20 (character code of a space). If you want to convert a null character -into 0x00, you should use 'utf8'.

    -
    • -

  • 'utf8' - Multi byte encoded Unicode characters. Many web pages and other document formats use UTF-8.

    -
    • -

  • 'ucs2' - 2-bytes, little endian encoded Unicode characters. It can encode -only BMP(Basic Multilingual Plane, U+0000 - U+FFFF).

    -
    • -

  • 'base64' - Base64 string encoding.

    -
    • -

  • 'binary' - A way of encoding raw binary data into strings by using only -the first 8 bits of each character. This encoding method is deprecated and -should be avoided in favor of Buffer objects where possible. This encoding -will be removed in future versions of Node.

    -
    • -

  • 'hex' - Encode each byte as two hexidecimal characters.

    -
    • -
-

Class: Buffer#

-

The Buffer class is a global type for dealing with binary data directly. -It can be constructed in a variety of ways. - -

-

new Buffer(size)#

-
    -
  • size Number
    • -
-

Allocates a new buffer of size octets. - -

-

new Buffer(array)#

-
    -
  • array Array
    • -
-

Allocates a new buffer using an array of octets. - -

-

new Buffer(str, [encoding])#

-
    -
  • str String - string to encode.
    • -
  • encoding String - encoding to use, Optional.
    • -
-

Allocates a new buffer containing the given str. -encoding defaults to 'utf8'. - -

-

buf.write(string, [offset], [length], [encoding])#

-
    -
  • string String - data to be written to buffer
    • -
  • offset Number, Optional, Default: 0
    • -
  • length Number, Optional, Default: buffer.length - offset
    • -
  • encoding String, Optional, Default: 'utf8'
    • -
-

Writes string to the buffer at offset using the given encoding. -offset defaults to 0, encoding defaults to 'utf8'. length is -the number of bytes to write. Returns number of octets written. If buffer did -not contain enough space to fit the entire string, it will write a partial -amount of the string. length defaults to buffer.length - offset. -The method will not write partial characters. - -

-
buf = new Buffer(256);
-len = buf.write('\u00bd + \u00bc = \u00be', 0);
-console.log(len + " bytes: " + buf.toString('utf8', 0, len));
-

The number of characters written (which may be different than the number of -bytes written) is set in Buffer._charsWritten and will be overwritten the -next time buf.write() is called. - - -

-

buf.toString([encoding], [start], [end])#

-
    -
  • encoding String, Optional, Default: 'utf8'
    • -
  • start Number, Optional, Default: 0
    • -
  • end Number, Optional, Default: buffer.length
    • -
-

Decodes and returns a string from buffer data encoded with encoding -(defaults to 'utf8') beginning at start (defaults to 0) and ending at -end (defaults to buffer.length). - -

-

See buffer.write() example, above. - - -

-

buf[index]#

- - - -

Get and set the octet at index. The values refer to individual bytes, -so the legal range is between 0x00 and 0xFF hex or 0 and 255. - -

-

Example: copy an ASCII string into a buffer, one byte at a time: - -

-
str = "node.js";
-buf = new Buffer(str.length);
-
-for (var i = 0; i < str.length ; i++) {
-  buf[i] = str.charCodeAt(i);
-}
-
-console.log(buf);
-
-// node.js
-

Class Method: Buffer.isBuffer(obj)#

-
    -
  • obj Object
    • -
  • Return: Boolean
    • -
-

Tests if obj is a Buffer. - -

-

Class Method: Buffer.byteLength(string, [encoding])#

-
    -
  • string String
    • -
  • encoding String, Optional, Default: 'utf8'
    • -
  • Return: Number
    • -
-

Gives the actual byte length of a string. encoding defaults to 'utf8'. -This is not the same as String.prototype.length since that returns the -number of characters in a string. - -

-

Example: - -

-
str = '\u00bd + \u00bc = \u00be';
-
-console.log(str + ": " + str.length + " characters, " +
-  Buffer.byteLength(str, 'utf8') + " bytes");
-
-// ½ + ¼ = ¾: 9 characters, 12 bytes
-

buf.length#

-
    -
  • Number
    • -
-

The size of the buffer in bytes. Note that this is not necessarily the size -of the contents. length refers to the amount of memory allocated for the -buffer object. It does not change when the contents of the buffer are changed. - -

-
buf = new Buffer(1234);
-
-console.log(buf.length);
-buf.write("some string", "ascii", 0);
-console.log(buf.length);
-
-// 1234
-// 1234
-

buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])#

-
    -
  • targetBuffer Buffer object - Buffer to copy into
    • -
  • targetStart Number, Optional, Default: 0
    • -
  • sourceStart Number, Optional, Default: 0
    • -
  • sourceEnd Number, Optional, Default: buffer.length
    • -
-

Does copy between buffers. The source and target regions can be overlapped. -targetStart and sourceStart default to 0. -sourceEnd defaults to buffer.length. - -

-

Example: build two Buffers, then copy buf1 from byte 16 through byte 19 -into buf2, starting at the 8th byte in buf2. - -

-
buf1 = new Buffer(26);
-buf2 = new Buffer(26);
-
-for (var i = 0 ; i < 26 ; i++) {
-  buf1[i] = i + 97; // 97 is ASCII a
-  buf2[i] = 33; // ASCII !
-}
-
-buf1.copy(buf2, 8, 16, 20);
-console.log(buf2.toString('ascii', 0, 25));
-
-// !!!!!!!!qrst!!!!!!!!!!!!!
-

buf.slice([start], [end])#

-
    -
  • start Number, Optional, Default: 0
    • -
  • end Number, Optional, Default: buffer.length
    • -
-

Returns a new buffer which references the same memory as the old, but offset -and cropped by the start (defaults to 0) and end (defaults to -buffer.length) indexes. - -

-

Modifying the new buffer slice will modify memory in the original buffer! - -

-

Example: build a Buffer with the ASCII alphabet, take a slice, then modify one -byte from the original Buffer. - -

-
var buf1 = new Buffer(26);
-
-for (var i = 0 ; i < 26 ; i++) {
-  buf1[i] = i + 97; // 97 is ASCII a
-}
-
-var buf2 = buf1.slice(0, 3);
-console.log(buf2.toString('ascii', 0, buf2.length));
-buf1[0] = 33;
-console.log(buf2.toString('ascii', 0, buf2.length));
-
-// abc
-// !bc
-

buf.readUInt8(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads an unsigned 8 bit integer from the buffer at the specified offset. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-
-buf[0] = 0x3;
-buf[1] = 0x4;
-buf[2] = 0x23;
-buf[3] = 0x42;
-
-for (ii = 0; ii < buf.length; ii++) {
-  console.log(buf.readUInt8(ii));
-}
-
-// 0x3
-// 0x4
-// 0x23
-// 0x42
-

buf.readUInt16LE(offset, [noAssert])#

-

buf.readUInt16BE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads an unsigned 16 bit integer from the buffer at the specified offset with -specified endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-
-buf[0] = 0x3;
-buf[1] = 0x4;
-buf[2] = 0x23;
-buf[3] = 0x42;
-
-console.log(buf.readUInt16BE(0));
-console.log(buf.readUInt16LE(0));
-console.log(buf.readUInt16BE(1));
-console.log(buf.readUInt16LE(1));
-console.log(buf.readUInt16BE(2));
-console.log(buf.readUInt16LE(2));
-
-// 0x0304
-// 0x0403
-// 0x0423
-// 0x2304
-// 0x2342
-// 0x4223
-

buf.readUInt32LE(offset, [noAssert])#

-

buf.readUInt32BE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads an unsigned 32 bit integer from the buffer at the specified offset with -specified endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-
-buf[0] = 0x3;
-buf[1] = 0x4;
-buf[2] = 0x23;
-buf[3] = 0x42;
-
-console.log(buf.readUInt32BE(0));
-console.log(buf.readUInt32LE(0));
-
-// 0x03042342
-// 0x42230403
-

buf.readInt8(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads a signed 8 bit integer from the buffer at the specified offset. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Works as buffer.readUInt8, except buffer contents are treated as two's -complement signed values. - -

-

buf.readInt16LE(offset, [noAssert])#

-

buf.readInt16BE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads a signed 16 bit integer from the buffer at the specified offset with -specified endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Works as buffer.readUInt16*, except buffer contents are treated as two's -complement signed values. - -

-

buf.readInt32LE(offset, [noAssert])#

-

buf.readInt32BE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads a signed 32 bit integer from the buffer at the specified offset with -specified endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Works as buffer.readUInt32*, except buffer contents are treated as two's -complement signed values. - -

-

buf.readFloatLE(offset, [noAssert])#

-

buf.readFloatBE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads a 32 bit float from the buffer at the specified offset with specified -endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-
-buf[0] = 0x00;
-buf[1] = 0x00;
-buf[2] = 0x80;
-buf[3] = 0x3f;
-
-console.log(buf.readFloatLE(0));
-
-// 0x01
-

buf.readDoubleLE(offset, [noAssert])#

-

buf.readDoubleBE(offset, [noAssert])#

-
    -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
  • Return: Number
    • -
-

Reads a 64 bit double from the buffer at the specified offset with specified -endian format. - -

-

Set noAssert to true to skip validation of offset. This means that offset -may be beyond the end of the buffer. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(8);
-
-buf[0] = 0x55;
-buf[1] = 0x55;
-buf[2] = 0x55;
-buf[3] = 0x55;
-buf[4] = 0x55;
-buf[5] = 0x55;
-buf[6] = 0xd5;
-buf[7] = 0x3f;
-
-console.log(buf.readDoubleLE(0));
-
-// 0.3333333333333333
-

buf.writeUInt8(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset. Note, value must be a -valid unsigned 8 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-buf.writeUInt8(0x3, 0);
-buf.writeUInt8(0x4, 1);
-buf.writeUInt8(0x23, 2);
-buf.writeUInt8(0x42, 3);
-
-console.log(buf);
-
-// <Buffer 03 04 23 42>
-

buf.writeUInt16LE(value, offset, [noAssert])#

-

buf.writeUInt16BE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid unsigned 16 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-buf.writeUInt16BE(0xdead, 0);
-buf.writeUInt16BE(0xbeef, 2);
-
-console.log(buf);
-
-buf.writeUInt16LE(0xdead, 0);
-buf.writeUInt16LE(0xbeef, 2);
-
-console.log(buf);
-
-// <Buffer de ad be ef>
-// <Buffer ad de ef be>
-

buf.writeUInt32LE(value, offset, [noAssert])#

-

buf.writeUInt32BE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid unsigned 32 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-buf.writeUInt32BE(0xfeedface, 0);
-
-console.log(buf);
-
-buf.writeUInt32LE(0xfeedface, 0);
-
-console.log(buf);
-
-// <Buffer fe ed fa ce>
-// <Buffer ce fa ed fe>
-

buf.writeInt8(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset. Note, value must be a -valid signed 8 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Works as buffer.writeUInt8, except value is written out as a two's complement -signed integer into buffer. - -

-

buf.writeInt16LE(value, offset, [noAssert])#

-

buf.writeInt16BE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid signed 16 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Works as buffer.writeUInt16*, except value is written out as a two's -complement signed integer into buffer. - -

-

buf.writeInt32LE(value, offset, [noAssert])#

-

buf.writeInt32BE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid signed 32 bit integer. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Works as buffer.writeUInt32*, except value is written out as a two's -complement signed integer into buffer. - -

-

buf.writeFloatLE(value, offset, [noAssert])#

-

buf.writeFloatBE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid 32 bit float. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(4);
-buf.writeFloatBE(0xcafebabe, 0);
-
-console.log(buf);
-
-buf.writeFloatLE(0xcafebabe, 0);
-
-console.log(buf);
-
-// <Buffer 4f 4a fe bb>
-// <Buffer bb fe 4a 4f>
-

buf.writeDoubleLE(value, offset, [noAssert])#

-

buf.writeDoubleBE(value, offset, [noAssert])#

-
    -
  • value Number
    • -
  • offset Number
    • -
  • noAssert Boolean, Optional, Default: false
    • -
-

Writes value to the buffer at the specified offset with specified endian -format. Note, value must be a valid 64 bit double. - -

-

Set noAssert to true to skip validation of value and offset. This means -that value may be too large for the specific function and offset may be -beyond the end of the buffer leading to the values being silently dropped. This -should not be used unless you are certain of correctness. Defaults to false. - -

-

Example: - -

-
var buf = new Buffer(8);
-buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
-
-console.log(buf);
-
-buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
-
-console.log(buf);
-
-// <Buffer 43 eb d5 b7 dd f9 5f d7>
-// <Buffer d7 5f f9 dd b7 d5 eb 43>
-

buf.fill(value, [offset], [end])#

-
    -
  • value
    • -
  • offset Number, Optional
    • -
  • end Number, Optional
    • -
-

Fills the buffer with the specified value. If the offset (defaults to 0) -and end (defaults to buffer.length) are not given it will fill the entire -buffer. - -

-
var b = new Buffer(50);
-b.fill("h");
-

buffer.INSPECT_MAX_BYTES#

-
    -
  • Number, Default: 50
    • -
-

How many bytes will be returned when buffer.inspect() is called. This can -be overridden by user modules. - -

-

Note that this is a property on the buffer module returned by -require('buffer'), not on the Buffer global, or a buffer instance. - -

-

Class: SlowBuffer#

-

This class is primarily for internal use. JavaScript programs should -use Buffer instead of using SlowBuffer. - -

-

In order to avoid the overhead of allocating many C++ Buffer objects for -small blocks of memory in the lifetime of a server, Node allocates memory -in 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it -will be backed by a parent SlowBuffer object. If it is larger than this, -then Node will allocate a SlowBuffer slab for it directly. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/buffer.json +++ /dev/null @@ -1,1704 +0,0 @@ -{ - "source": "doc/api/buffer.markdown", - "modules": [ - { - "textRaw": "Buffer", - "name": "buffer", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Pure Javascript is Unicode friendly but not nice to binary data. When\ndealing with TCP streams or the file system, it's necessary to handle octet\nstreams. Node has several strategies for manipulating, creating, and\nconsuming octet streams.\n\n

\n

Raw data is stored in instances of the Buffer class. A Buffer is similar\nto an array of integers but corresponds to a raw memory allocation outside\nthe V8 heap. A Buffer cannot be resized.\n\n

\n

The Buffer class is a global, making it very rare that one would need\nto ever require('buffer').\n\n

\n

Converting between Buffers and JavaScript string objects requires an explicit\nencoding method. Here are the different string encodings.\n\n

\n
    \n

  • 'ascii' - for 7 bit ASCII data only. This encoding method is very fast, and\nwill strip the high bit if set.\nNote that this encoding converts a null character ('\\0' or '\\u0000') into\n0x20 (character code of a space). If you want to convert a null character\ninto 0x00, you should use 'utf8'.

    \n
    • \n

  • 'utf8' - Multi byte encoded Unicode characters. Many web pages and other document formats use UTF-8.

    \n
    • \n

  • 'ucs2' - 2-bytes, little endian encoded Unicode characters. It can encode\nonly BMP(Basic Multilingual Plane, U+0000 - U+FFFF).

    \n
    • \n

  • 'base64' - Base64 string encoding.

    \n
    • \n

  • 'binary' - A way of encoding raw binary data into strings by using only\nthe first 8 bits of each character. This encoding method is deprecated and\nshould be avoided in favor of Buffer objects where possible. This encoding\nwill be removed in future versions of Node.

    \n
    • \n

  • 'hex' - Encode each byte as two hexidecimal characters.

    \n
    • \n
\n", - "classes": [ - { - "textRaw": "Class: Buffer", - "type": "class", - "name": "Buffer", - "desc": "

The Buffer class is a global type for dealing with binary data directly.\nIt can be constructed in a variety of ways.\n\n

\n", - "methods": [ - { - "textRaw": "buf.write(string, [offset], [length], [encoding])", - "type": "method", - "name": "write", - "signatures": [ - { - "params": [ - { - "textRaw": "`string` String - data to be written to buffer ", - "name": "string", - "desc": "String - data to be written to buffer" - }, - { - "textRaw": "`offset` Number, Optional, Default: 0 ", - "name": "offset", - "desc": "Number, Optional, Default: 0", - "optional": true - }, - { - "textRaw": "`length` Number, Optional, Default: `buffer.length - offset` ", - "name": "length", - "desc": "Number, Optional, Default: `buffer.length - offset`", - "optional": true - }, - { - "textRaw": "`encoding` String, Optional, Default: 'utf8' ", - "name": "encoding", - "desc": "String, Optional, Default: 'utf8'", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "string" - }, - { - "name": "offset", - "optional": true - }, - { - "name": "length", - "optional": true - }, - { - "name": "encoding", - "optional": true - } - ] - } - ], - "desc": "

Writes string to the buffer at offset using the given encoding.\noffset defaults to 0, encoding defaults to 'utf8'. length is\nthe number of bytes to write. Returns number of octets written. If buffer did\nnot contain enough space to fit the entire string, it will write a partial\namount of the string. length defaults to buffer.length - offset.\nThe method will not write partial characters.\n\n

\n
buf = new Buffer(256);\nlen = buf.write('\\u00bd + \\u00bc = \\u00be', 0);\nconsole.log(len + " bytes: " + buf.toString('utf8', 0, len));
\n

The number of characters written (which may be different than the number of\nbytes written) is set in Buffer._charsWritten and will be overwritten the\nnext time buf.write() is called.\n\n\n

\n" - }, - { - "textRaw": "buf.toString([encoding], [start], [end])", - "type": "method", - "name": "toString", - "signatures": [ - { - "params": [ - { - "textRaw": "`encoding` String, Optional, Default: 'utf8' ", - "name": "encoding", - "desc": "String, Optional, Default: 'utf8'", - "optional": true - }, - { - "textRaw": "`start` Number, Optional, Default: 0 ", - "name": "start", - "desc": "Number, Optional, Default: 0", - "optional": true - }, - { - "textRaw": "`end` Number, Optional, Default: `buffer.length` ", - "name": "end", - "desc": "Number, Optional, Default: `buffer.length`", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "encoding", - "optional": true - }, - { - "name": "start", - "optional": true - }, - { - "name": "end", - "optional": true - } - ] - } - ], - "desc": "

Decodes and returns a string from buffer data encoded with encoding\n(defaults to 'utf8') beginning at start (defaults to 0) and ending at\nend (defaults to buffer.length).\n\n

\n

See buffer.write() example, above.\n\n\n

\n" - }, - { - "textRaw": "buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])", - "type": "method", - "name": "copy", - "signatures": [ - { - "params": [ - { - "textRaw": "`targetBuffer` Buffer object - Buffer to copy into ", - "name": "targetBuffer", - "desc": "Buffer object - Buffer to copy into" - }, - { - "textRaw": "`targetStart` Number, Optional, Default: 0 ", - "name": "targetStart", - "desc": "Number, Optional, Default: 0", - "optional": true - }, - { - "textRaw": "`sourceStart` Number, Optional, Default: 0 ", - "name": "sourceStart", - "desc": "Number, Optional, Default: 0", - "optional": true - }, - { - "textRaw": "`sourceEnd` Number, Optional, Default: `buffer.length` ", - "name": "sourceEnd", - "desc": "Number, Optional, Default: `buffer.length`", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "targetBuffer" - }, - { - "name": "targetStart", - "optional": true - }, - { - "name": "sourceStart", - "optional": true - }, - { - "name": "sourceEnd", - "optional": true - } - ] - } - ], - "desc": "

Does copy between buffers. The source and target regions can be overlapped.\ntargetStart and sourceStart default to 0.\nsourceEnd defaults to buffer.length.\n\n

\n

Example: build two Buffers, then copy buf1 from byte 16 through byte 19\ninto buf2, starting at the 8th byte in buf2.\n\n

\n
buf1 = new Buffer(26);\nbuf2 = new Buffer(26);\n\nfor (var i = 0 ; i < 26 ; i++) {\n  buf1[i] = i + 97; // 97 is ASCII a\n  buf2[i] = 33; // ASCII !\n}\n\nbuf1.copy(buf2, 8, 16, 20);\nconsole.log(buf2.toString('ascii', 0, 25));\n\n// !!!!!!!!qrst!!!!!!!!!!!!!
\n" - }, - { - "textRaw": "buf.slice([start], [end])", - "type": "method", - "name": "slice", - "signatures": [ - { - "params": [ - { - "textRaw": "`start` Number, Optional, Default: 0 ", - "name": "start", - "desc": "Number, Optional, Default: 0", - "optional": true - }, - { - "textRaw": "`end` Number, Optional, Default: `buffer.length` ", - "name": "end", - "desc": "Number, Optional, Default: `buffer.length`", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "start", - "optional": true - }, - { - "name": "end", - "optional": true - } - ] - } - ], - "desc": "

Returns a new buffer which references the same memory as the old, but offset\nand cropped by the start (defaults to 0) and end (defaults to\nbuffer.length) indexes.\n\n

\n

Modifying the new buffer slice will modify memory in the original buffer!\n\n

\n

Example: build a Buffer with the ASCII alphabet, take a slice, then modify one\nbyte from the original Buffer.\n\n

\n
var buf1 = new Buffer(26);\n\nfor (var i = 0 ; i < 26 ; i++) {\n  buf1[i] = i + 97; // 97 is ASCII a\n}\n\nvar buf2 = buf1.slice(0, 3);\nconsole.log(buf2.toString('ascii', 0, buf2.length));\nbuf1[0] = 33;\nconsole.log(buf2.toString('ascii', 0, buf2.length));\n\n// abc\n// !bc
\n" - }, - { - "textRaw": "buf.readUInt8(offset, [noAssert])", - "type": "method", - "name": "readUInt8", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads an unsigned 8 bit integer from the buffer at the specified offset.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nfor (ii = 0; ii < buf.length; ii++) {\n  console.log(buf.readUInt8(ii));\n}\n\n// 0x3\n// 0x4\n// 0x23\n// 0x42
\n" - }, - { - "textRaw": "buf.readUInt16LE(offset, [noAssert])", - "type": "method", - "name": "readUInt16LE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads an unsigned 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt16BE(0));\nconsole.log(buf.readUInt16LE(0));\nconsole.log(buf.readUInt16BE(1));\nconsole.log(buf.readUInt16LE(1));\nconsole.log(buf.readUInt16BE(2));\nconsole.log(buf.readUInt16LE(2));\n\n// 0x0304\n// 0x0403\n// 0x0423\n// 0x2304\n// 0x2342\n// 0x4223
\n" - }, - { - "textRaw": "buf.readUInt16BE(offset, [noAssert])", - "type": "method", - "name": "readUInt16BE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads an unsigned 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt16BE(0));\nconsole.log(buf.readUInt16LE(0));\nconsole.log(buf.readUInt16BE(1));\nconsole.log(buf.readUInt16LE(1));\nconsole.log(buf.readUInt16BE(2));\nconsole.log(buf.readUInt16LE(2));\n\n// 0x0304\n// 0x0403\n// 0x0423\n// 0x2304\n// 0x2342\n// 0x4223
\n" - }, - { - "textRaw": "buf.readUInt32LE(offset, [noAssert])", - "type": "method", - "name": "readUInt32LE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads an unsigned 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt32BE(0));\nconsole.log(buf.readUInt32LE(0));\n\n// 0x03042342\n// 0x42230403
\n" - }, - { - "textRaw": "buf.readUInt32BE(offset, [noAssert])", - "type": "method", - "name": "readUInt32BE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads an unsigned 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x3;\nbuf[1] = 0x4;\nbuf[2] = 0x23;\nbuf[3] = 0x42;\n\nconsole.log(buf.readUInt32BE(0));\nconsole.log(buf.readUInt32LE(0));\n\n// 0x03042342\n// 0x42230403
\n" - }, - { - "textRaw": "buf.readInt8(offset, [noAssert])", - "type": "method", - "name": "readInt8", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a signed 8 bit integer from the buffer at the specified offset.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt8, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" - }, - { - "textRaw": "buf.readInt16LE(offset, [noAssert])", - "type": "method", - "name": "readInt16LE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a signed 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt16*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" - }, - { - "textRaw": "buf.readInt16BE(offset, [noAssert])", - "type": "method", - "name": "readInt16BE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a signed 16 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt16*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" - }, - { - "textRaw": "buf.readInt32LE(offset, [noAssert])", - "type": "method", - "name": "readInt32LE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a signed 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt32*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" - }, - { - "textRaw": "buf.readInt32BE(offset, [noAssert])", - "type": "method", - "name": "readInt32BE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a signed 32 bit integer from the buffer at the specified offset with\nspecified endian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Works as buffer.readUInt32*, except buffer contents are treated as two's\ncomplement signed values.\n\n

\n" - }, - { - "textRaw": "buf.readFloatLE(offset, [noAssert])", - "type": "method", - "name": "readFloatLE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a 32 bit float from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x00;\nbuf[1] = 0x00;\nbuf[2] = 0x80;\nbuf[3] = 0x3f;\n\nconsole.log(buf.readFloatLE(0));\n\n// 0x01
\n" - }, - { - "textRaw": "buf.readFloatBE(offset, [noAssert])", - "type": "method", - "name": "readFloatBE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a 32 bit float from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\n\nbuf[0] = 0x00;\nbuf[1] = 0x00;\nbuf[2] = 0x80;\nbuf[3] = 0x3f;\n\nconsole.log(buf.readFloatLE(0));\n\n// 0x01
\n" - }, - { - "textRaw": "buf.readDoubleLE(offset, [noAssert])", - "type": "method", - "name": "readDoubleLE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a 64 bit double from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\n\nbuf[0] = 0x55;\nbuf[1] = 0x55;\nbuf[2] = 0x55;\nbuf[3] = 0x55;\nbuf[4] = 0x55;\nbuf[5] = 0x55;\nbuf[6] = 0xd5;\nbuf[7] = 0x3f;\n\nconsole.log(buf.readDoubleLE(0));\n\n// 0.3333333333333333
\n" - }, - { - "textRaw": "buf.readDoubleBE(offset, [noAssert])", - "type": "method", - "name": "readDoubleBE", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Reads a 64 bit double from the buffer at the specified offset with specified\nendian format.\n\n

\n

Set noAssert to true to skip validation of offset. This means that offset\nmay be beyond the end of the buffer. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\n\nbuf[0] = 0x55;\nbuf[1] = 0x55;\nbuf[2] = 0x55;\nbuf[3] = 0x55;\nbuf[4] = 0x55;\nbuf[5] = 0x55;\nbuf[6] = 0xd5;\nbuf[7] = 0x3f;\n\nconsole.log(buf.readDoubleLE(0));\n\n// 0.3333333333333333
\n" - }, - { - "textRaw": "buf.writeUInt8(value, offset, [noAssert])", - "type": "method", - "name": "writeUInt8", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset. Note, value must be a\nvalid unsigned 8 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt8(0x3, 0);\nbuf.writeUInt8(0x4, 1);\nbuf.writeUInt8(0x23, 2);\nbuf.writeUInt8(0x42, 3);\n\nconsole.log(buf);\n\n// <Buffer 03 04 23 42>
\n" - }, - { - "textRaw": "buf.writeUInt16LE(value, offset, [noAssert])", - "type": "method", - "name": "writeUInt16LE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt16BE(0xdead, 0);\nbuf.writeUInt16BE(0xbeef, 2);\n\nconsole.log(buf);\n\nbuf.writeUInt16LE(0xdead, 0);\nbuf.writeUInt16LE(0xbeef, 2);\n\nconsole.log(buf);\n\n// <Buffer de ad be ef>\n// <Buffer ad de ef be>
\n" - }, - { - "textRaw": "buf.writeUInt16BE(value, offset, [noAssert])", - "type": "method", - "name": "writeUInt16BE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt16BE(0xdead, 0);\nbuf.writeUInt16BE(0xbeef, 2);\n\nconsole.log(buf);\n\nbuf.writeUInt16LE(0xdead, 0);\nbuf.writeUInt16LE(0xbeef, 2);\n\nconsole.log(buf);\n\n// <Buffer de ad be ef>\n// <Buffer ad de ef be>
\n" - }, - { - "textRaw": "buf.writeUInt32LE(value, offset, [noAssert])", - "type": "method", - "name": "writeUInt32LE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt32BE(0xfeedface, 0);\n\nconsole.log(buf);\n\nbuf.writeUInt32LE(0xfeedface, 0);\n\nconsole.log(buf);\n\n// <Buffer fe ed fa ce>\n// <Buffer ce fa ed fe>
\n" - }, - { - "textRaw": "buf.writeUInt32BE(value, offset, [noAssert])", - "type": "method", - "name": "writeUInt32BE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid unsigned 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeUInt32BE(0xfeedface, 0);\n\nconsole.log(buf);\n\nbuf.writeUInt32LE(0xfeedface, 0);\n\nconsole.log(buf);\n\n// <Buffer fe ed fa ce>\n// <Buffer ce fa ed fe>
\n" - }, - { - "textRaw": "buf.writeInt8(value, offset, [noAssert])", - "type": "method", - "name": "writeInt8", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset. Note, value must be a\nvalid signed 8 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt8, except value is written out as a two's complement\nsigned integer into buffer.\n\n

\n" - }, - { - "textRaw": "buf.writeInt16LE(value, offset, [noAssert])", - "type": "method", - "name": "writeInt16LE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt16*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" - }, - { - "textRaw": "buf.writeInt16BE(value, offset, [noAssert])", - "type": "method", - "name": "writeInt16BE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 16 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt16*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" - }, - { - "textRaw": "buf.writeInt32LE(value, offset, [noAssert])", - "type": "method", - "name": "writeInt32LE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt32*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" - }, - { - "textRaw": "buf.writeInt32BE(value, offset, [noAssert])", - "type": "method", - "name": "writeInt32BE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid signed 32 bit integer.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Works as buffer.writeUInt32*, except value is written out as a two's\ncomplement signed integer into buffer.\n\n

\n" - }, - { - "textRaw": "buf.writeFloatLE(value, offset, [noAssert])", - "type": "method", - "name": "writeFloatLE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 32 bit float.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeFloatBE(0xcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeFloatLE(0xcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 4f 4a fe bb>\n// <Buffer bb fe 4a 4f>
\n" - }, - { - "textRaw": "buf.writeFloatBE(value, offset, [noAssert])", - "type": "method", - "name": "writeFloatBE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 32 bit float.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(4);\nbuf.writeFloatBE(0xcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeFloatLE(0xcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 4f 4a fe bb>\n// <Buffer bb fe 4a 4f>
\n" - }, - { - "textRaw": "buf.writeDoubleLE(value, offset, [noAssert])", - "type": "method", - "name": "writeDoubleLE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 64 bit double.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\nbuf.writeDoubleBE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeDoubleLE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 43 eb d5 b7 dd f9 5f d7>\n// <Buffer d7 5f f9 dd b7 d5 eb 43>
\n" - }, - { - "textRaw": "buf.writeDoubleBE(value, offset, [noAssert])", - "type": "method", - "name": "writeDoubleBE", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` Number ", - "name": "value", - "desc": "Number" - }, - { - "textRaw": "`offset` Number ", - "name": "offset", - "desc": "Number" - }, - { - "textRaw": "`noAssert` Boolean, Optional, Default: false ", - "name": "noAssert", - "desc": "Boolean, Optional, Default: false", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset" - }, - { - "name": "noAssert", - "optional": true - } - ] - } - ], - "desc": "

Writes value to the buffer at the specified offset with specified endian\nformat. Note, value must be a valid 64 bit double.\n\n

\n

Set noAssert to true to skip validation of value and offset. This means\nthat value may be too large for the specific function and offset may be\nbeyond the end of the buffer leading to the values being silently dropped. This\nshould not be used unless you are certain of correctness. Defaults to false.\n\n

\n

Example:\n\n

\n
var buf = new Buffer(8);\nbuf.writeDoubleBE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\nbuf.writeDoubleLE(0xdeadbeefcafebabe, 0);\n\nconsole.log(buf);\n\n// <Buffer 43 eb d5 b7 dd f9 5f d7>\n// <Buffer d7 5f f9 dd b7 d5 eb 43>
\n" - }, - { - "textRaw": "buf.fill(value, [offset], [end])", - "type": "method", - "name": "fill", - "signatures": [ - { - "params": [ - { - "textRaw": "`value` ", - "name": "value" - }, - { - "textRaw": "`offset` Number, Optional ", - "name": "offset", - "optional": true, - "desc": "Number" - }, - { - "textRaw": "`end` Number, Optional ", - "name": "end", - "optional": true, - "desc": "Number" - } - ] - }, - { - "params": [ - { - "name": "value" - }, - { - "name": "offset", - "optional": true - }, - { - "name": "end", - "optional": true - } - ] - } - ], - "desc": "

Fills the buffer with the specified value. If the offset (defaults to 0)\nand end (defaults to buffer.length) are not given it will fill the entire\nbuffer.\n\n

\n
var b = new Buffer(50);\nb.fill("h");
\n" - } - ], - "properties": [ - { - "textRaw": "buf[index]", - "name": "[index]", - "desc": "

Get and set the octet at index. The values refer to individual bytes,\nso the legal range is between 0x00 and 0xFF hex or 0 and 255.\n\n

\n

Example: copy an ASCII string into a buffer, one byte at a time:\n\n

\n
str = "node.js";\nbuf = new Buffer(str.length);\n\nfor (var i = 0; i < str.length ; i++) {\n  buf[i] = str.charCodeAt(i);\n}\n\nconsole.log(buf);\n\n// node.js
\n" - }, - { - "textRaw": "`length` Number ", - "name": "length", - "desc": "

The size of the buffer in bytes. Note that this is not necessarily the size\nof the contents. length refers to the amount of memory allocated for the\nbuffer object. It does not change when the contents of the buffer are changed.\n\n

\n
buf = new Buffer(1234);\n\nconsole.log(buf.length);\nbuf.write("some string", "ascii", 0);\nconsole.log(buf.length);\n\n// 1234\n// 1234
\n", - "shortDesc": "Number" - } - ], - "classMethods": [ - { - "textRaw": "Class Method: Buffer.isBuffer(obj)", - "type": "classMethod", - "name": "isBuffer", - "signatures": [ - { - "return": { - "textRaw": "Return: Boolean ", - "name": "return", - "desc": "Boolean" - }, - "params": [ - { - "textRaw": "`obj` Object ", - "name": "obj", - "desc": "Object" - } - ] - }, - { - "params": [ - { - "name": "obj" - } - ] - } - ], - "desc": "

Tests if obj is a Buffer.\n\n

\n" - }, - { - "textRaw": "Class Method: Buffer.byteLength(string, [encoding])", - "type": "classMethod", - "name": "byteLength", - "signatures": [ - { - "return": { - "textRaw": "Return: Number ", - "name": "return", - "desc": "Number" - }, - "params": [ - { - "textRaw": "`string` String ", - "name": "string", - "desc": "String" - }, - { - "textRaw": "`encoding` String, Optional, Default: 'utf8' ", - "name": "encoding", - "desc": "String, Optional, Default: 'utf8'", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "string" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ], - "desc": "

Gives the actual byte length of a string. encoding defaults to 'utf8'.\nThis is not the same as String.prototype.length since that returns the\nnumber of characters in a string.\n\n

\n

Example:\n\n

\n
str = '\\u00bd + \\u00bc = \\u00be';\n\nconsole.log(str + ": " + str.length + " characters, " +\n  Buffer.byteLength(str, 'utf8') + " bytes");\n\n// ½ + ¼ = ¾: 9 characters, 12 bytes
\n" - } - ], - "signatures": [ - { - "params": [ - { - "textRaw": "`size` Number ", - "name": "size", - "desc": "Number" - } - ], - "desc": "

Allocates a new buffer of size octets.\n\n

\n" - }, - { - "params": [ - { - "name": "size" - } - ], - "desc": "

Allocates a new buffer of size octets.\n\n

\n" - }, - { - "params": [ - { - "textRaw": "`array` Array ", - "name": "array", - "desc": "Array" - } - ], - "desc": "

Allocates a new buffer using an array of octets.\n\n

\n" - }, - { - "params": [ - { - "name": "array" - } - ], - "desc": "

Allocates a new buffer using an array of octets.\n\n

\n" - }, - { - "params": [ - { - "textRaw": "`str` String - string to encode. ", - "name": "str", - "desc": "String - string to encode." - }, - { - "textRaw": "`encoding` String - encoding to use, Optional. ", - "name": "encoding", - "desc": "String - encoding to use, Optional.", - "optional": true - } - ], - "desc": "

Allocates a new buffer containing the given str.\nencoding defaults to 'utf8'.\n\n

\n" - }, - { - "params": [ - { - "name": "str" - }, - { - "name": "encoding", - "optional": true - } - ], - "desc": "

Allocates a new buffer containing the given str.\nencoding defaults to 'utf8'.\n\n

\n" - } - ] - }, - { - "textRaw": "Class: SlowBuffer", - "type": "class", - "name": "SlowBuffer", - "desc": "

This class is primarily for internal use. JavaScript programs should\nuse Buffer instead of using SlowBuffer.\n\n

\n

In order to avoid the overhead of allocating many C++ Buffer objects for\nsmall blocks of memory in the lifetime of a server, Node allocates memory\nin 8Kb (8192 byte) chunks. If a buffer is smaller than this size, then it\nwill be backed by a parent SlowBuffer object. If it is larger than this,\nthen Node will allocate a SlowBuffer slab for it directly.\n

\n" - } - ], - "properties": [ - { - "textRaw": "`INSPECT_MAX_BYTES` Number, Default: 50 ", - "name": "INSPECT_MAX_BYTES", - "desc": "

How many bytes will be returned when buffer.inspect() is called. This can\nbe overridden by user modules.\n\n

\n

Note that this is a property on the buffer module returned by\nrequire('buffer'), not on the Buffer global, or a buffer instance.\n\n

\n", - "shortDesc": "Number, Default: 50" - } - ], - "type": "module", - "displayName": "Buffer" - } - ] -} --- a/doc/api/api/child_process.html +++ /dev/null @@ -1,515 +0,0 @@ - - - - - Child Process Node.js v0.6.19 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.19 Manual & Documentation

- -
-
- - - -
-

Child Process#

-
Stability: 3 - Stable
-

Node provides a tri-directional popen(3) facility through the -child_process module. - -

-

It is possible to stream data through a child's stdin, stdout, and -stderr in a fully non-blocking way. - -

-

To create a child process use require('child_process').spawn() or -require('child_process').fork(). The semantics of each are slightly -different, and explained below. - -

-

Class: ChildProcess#

-

ChildProcess is an EventEmitter. - -

-

Child processes always have three streams associated with them. child.stdin, -child.stdout, and child.stderr. These may be shared with the stdio -streams of the parent process, or they may be separate stream objects -which can be piped to and from. - -

-

The ChildProcess class is not intended to be used directly. Use the -spawn() or fork() methods to create a Child Process instance. - -

-

Event: 'exit'#

-
    -
  • code Number the exit code, if it exited normally.
    • -
  • signal String the signal passed to kill the child process, if it -was killed by the parent.
    • -
-

This event is emitted after the child process ends. If the process terminated -normally, code is the final exit code of the process, otherwise null. If -the process terminated due to receipt of a signal, signal is the string name -of the signal, otherwise null. - -

-

See waitpid(2). - -

-

child.stdin#

-
    -
  • Stream object
    • -
-

A Writable Stream that represents the child process's stdin. -Closing this stream via end() often causes the child process to terminate. - -

-

If the child stdio streams are shared with the parent, then this will -not be set. - -

-

child.stdout#

-
    -
  • Stream object
    • -
-

A Readable Stream that represents the child process's stdout. - -

-

If the child stdio streams are shared with the parent, then this will -not be set. - -

-

child.stderr#

-
    -
  • Stream object
    • -
-

A Readable Stream that represents the child process's stderr. - -

-

If the child stdio streams are shared with the parent, then this will -not be set. - -

-

child.pid#

-
    -
  • Integer
    • -
-

The PID of the child process. - -

-

Example: - -

-
var spawn = require('child_process').spawn,
-    grep  = spawn('grep', ['ssh']);
-
-console.log('Spawned child pid: ' + grep.pid);
-grep.stdin.end();
-

child.kill([signal])#

-
    -
  • signal String
    • -
-

Send a signal to the child process. If no argument is given, the process will -be sent 'SIGTERM'. See signal(7) for a list of available signals. - -

-
var spawn = require('child_process').spawn,
-    grep  = spawn('grep', ['ssh']);
-
-grep.on('exit', function (code, signal) {
-  console.log('child process terminated due to receipt of signal '+signal);
-});
-
-// send SIGHUP to process
-grep.kill('SIGHUP');
-

Note that while the function is called kill, the signal delivered to the child -process may not actually kill it. kill really just sends a signal to a process. - -

-

See kill(2) - -

-

child.send(message, [sendHandle])#

-
    -
  • message Object
    • -
  • sendHandle Handle object
    • -
-

Send a message (and, optionally, a handle object) to a child process. - -

-

See child_process.fork() for details. - -

-

child_process.spawn(command, [args], [options])#

-
    -
  • command String The command to run
    • -
  • args Array List of string arguments
    • -
  • options Object
      -
    • cwd String Current working directory of the child process
      • -
    • customFds Array Deprecated File descriptors for the child to use -for stdio. (See below)
      • -
    • env Object Environment key-value pairs
      • -
    -
    • -
  • return: ChildProcess object
    • -
-

Launches a new process with the given command, with command line arguments in args. -If omitted, args defaults to an empty Array. - -

-

The third argument is used to specify additional options, which defaults to: - -

-
{ cwd: undefined,
-  env: process.env
-}
-

cwd allows you to specify the working directory from which the process is spawned. -Use env to specify environment variables that will be visible to the new process. - -

-

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code: - -

-
var util  = require('util'),
-    spawn = require('child_process').spawn,
-    ls    = spawn('ls', ['-lh', '/usr']);
-
-ls.stdout.on('data', function (data) {
-  console.log('stdout: ' + data);
-});
-
-ls.stderr.on('data', function (data) {
-  console.log('stderr: ' + data);
-});
-
-ls.on('exit', function (code) {
-  console.log('child process exited with code ' + code);
-});
-

Example: A very elaborate way to run 'ps ax | grep ssh' - -

-
var util  = require('util'),
-    spawn = require('child_process').spawn,
-    ps    = spawn('ps', ['ax']),
-    grep  = spawn('grep', ['ssh']);
-
-ps.stdout.on('data', function (data) {
-  grep.stdin.write(data);
-});
-
-ps.stderr.on('data', function (data) {
-  console.log('ps stderr: ' + data);
-});
-
-ps.on('exit', function (code) {
-  if (code !== 0) {
-    console.log('ps process exited with code ' + code);
-  }
-  grep.stdin.end();
-});
-
-grep.stdout.on('data', function (data) {
-  console.log(data);
-});
-
-grep.stderr.on('data', function (data) {
-  console.log('grep stderr: ' + data);
-});
-
-grep.on('exit', function (code) {
-  if (code !== 0) {
-    console.log('grep process exited with code ' + code);
-  }
-});
-

Example of checking for failed exec: - -

-
var spawn = require('child_process').spawn,
-    child = spawn('bad_command');
-
-child.stderr.setEncoding('utf8');
-child.stderr.on('data', function (data) {
-  if (/^execvp\(\)/.test(data)) {
-    console.log('Failed to start child process.');
-  }
-});
-

Note that if spawn receives an empty options object, it will result in -spawning the process with an empty environment rather than using -process.env. This due to backwards compatibility issues with a deprecated -API. - -

-

There is a deprecated option called customFds which allows one to specify -specific file descriptors for the stdio of the child process. This API was -not portable to all platforms and therefore removed. -With customFds it was possible to hook up the new process' [stdin, stdout, -stderr] to existing streams; -1 meant that a new stream should be created. -Use at your own risk. - -

-

There are several internal options. In particular stdinStream, -stdoutStream, stderrStream. They are for INTERNAL USE ONLY. As with all -undocumented APIs in Node, they should not be used. - -

-

See also: child_process.exec() and child_process.fork() - -

-

child_process.exec(command, [options], callback)#

-
    -
  • command String The command to run, with space-separated arguments
    • -
  • options Object
      -
    • cwd String Current working directory of the child process
      • -
    • customFds Array Deprecated File descriptors for the child to use -for stdio. (See below)
      • -
    • env Object Environment key-value pairs
      • -
    • encoding String (Default: 'utf8')
      • -
    • timeout Number (Default: 0)
      • -
    • maxBuffer Number (Default: 200*1024)
      • -
    • killSignal String (Default: 'SIGTERM')
      • -
    -
    • -
  • callback Function called with the output when process terminates
      -
    • error Error
      • -
    • stdout Buffer
      • -
    • stderr Buffer
      • -
    -
    • -
  • Return: ChildProcess object
    • -
-

Runs a command in a shell and buffers the output. - -

-
var util = require('util'),
-    exec = require('child_process').exec,
-    child;
-
-child = exec('cat *.js bad_file | wc -l',
-  function (error, stdout, stderr) {
-    console.log('stdout: ' + stdout);
-    console.log('stderr: ' + stderr);
-    if (error !== null) {
-      console.log('exec error: ' + error);
-    }
-});
-

The callback gets the arguments (error, stdout, stderr). On success, error -will be null. On error, error will be an instance of Error and err.code -will be the exit code of the child process, and err.signal will be set to the -signal that terminated the process. - -

-

There is a second optional argument to specify several options. The -default options are - -

-
{ encoding: 'utf8',
-  timeout: 0,
-  maxBuffer: 200*1024,
-  killSignal: 'SIGTERM',
-  cwd: null,
-  env: null }
-

If timeout is greater than 0, then it will kill the child process -if it runs longer than timeout milliseconds. The child process is killed with -killSignal (default: 'SIGTERM'). maxBuffer specifies the largest -amount of data allowed on stdout or stderr - if this value is exceeded then -the child process is killed. - - -

-

child_process.execFile(file, args, options, callback)#

-
    -
  • file String The filename of the program to run
    • -
  • args Array List of string arguments
    • -
  • options Object
      -
    • cwd String Current working directory of the child process
      • -
    • customFds Array Deprecated File descriptors for the child to use -for stdio. (See below)
      • -
    • env Object Environment key-value pairs
      • -
    • encoding String (Default: 'utf8')
      • -
    • timeout Number (Default: 0)
      • -
    • maxBuffer Number (Default: 200*1024)
      • -
    • killSignal String (Default: 'SIGTERM')
      • -
    -
    • -
  • callback Function called with the output when process terminates
      -
    • error Error
      • -
    • stdout Buffer
      • -
    • stderr Buffer
      • -
    -
    • -
  • Return: ChildProcess object
    • -
-

This is similar to child_process.exec() except it does not execute a -subshell but rather the specified file directly. This makes it slightly -leaner than child_process.exec. It has the same options. - - -

-

child_process.fork(modulePath, [args], [options])#

-
    -
  • modulePath String The module to run in the child
    • -
  • args Array List of string arguments
    • -
  • options Object
      -
    • cwd String Current working directory of the child process
      • -
    • customFds Array Deprecated File descriptors for the child to use -for stdio. (See below)
      • -
    • env Object Environment key-value pairs
      • -
    • encoding String (Default: 'utf8')
      • -
    • timeout Number (Default: 0)
      • -
    -
    • -
  • Return: ChildProcess object
    • -
-

This is a special case of the spawn() functionality for spawning Node -processes. In addition to having all the methods in a normal ChildProcess -instance, the returned object has a communication channel built-in. The -channel is written to with child.send(message, [sendHandle]) and messages -are received by a 'message' event on the child. - -

-

For example: - -

-
var cp = require('child_process');
-
-var n = cp.fork(__dirname + '/sub.js');
-
-n.on('message', function(m) {
-  console.log('PARENT got message:', m);
-});
-
-n.send({ hello: 'world' });
-

And then the child script, 'sub.js' might look like this: - -

-
process.on('message', function(m) {
-  console.log('CHILD got message:', m);
-});
-
-process.send({ foo: 'bar' });
-

In the child the process object will have a send() method, and process -will emit objects each time it receives a message on its channel. - -

-

By default the spawned Node process will have the stdin, stdout, stderr -associated with the parent's. - -

-

These child Nodes are still whole new instances of V8. Assume at least 30ms -startup and 10mb memory for each new Node. That is, you cannot create many -thousands of them. - -

-

The sendHandle option to child.send() is for sending a handle object to -another process. Child will receive the handle as as second argument to the -message event. Here is an example of sending a handle: - -

-
var server = require('net').createServer();
-var child = require('child_process').fork(__dirname + '/child.js');
-// Open up the server object and send the handle.
-server.listen(1337, function() {
-  child.send({ server: true }, server._handle);
-});
-

Here is an example of receiving the server handle and sharing it between -processes: - -

-
process.on('message', function(m, serverHandle) {
-  if (serverHandle) {
-    var server = require('net').createServer();
-    server.listen(serverHandle);
-  }
-});
- -
-
-
- - - - - - - - - - --- a/doc/api/api/child_process.json +++ /dev/null @@ -1,498 +0,0 @@ -{ - "source": "doc/api/child_process.markdown", - "modules": [ - { - "textRaw": "Child Process", - "name": "child_process", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Node provides a tri-directional popen(3) facility through the\nchild_process module.\n\n

\n

It is possible to stream data through a child's stdin, stdout, and\nstderr in a fully non-blocking way.\n\n

\n

To create a child process use require('child_process').spawn() or\nrequire('child_process').fork(). The semantics of each are slightly\ndifferent, and explained below.\n\n

\n", - "classes": [ - { - "textRaw": "Class: ChildProcess", - "type": "class", - "name": "ChildProcess", - "desc": "

ChildProcess is an EventEmitter.\n\n

\n

Child processes always have three streams associated with them. child.stdin,\nchild.stdout, and child.stderr. These may be shared with the stdio\nstreams of the parent process, or they may be separate stream objects\nwhich can be piped to and from.\n\n

\n

The ChildProcess class is not intended to be used directly. Use the\nspawn() or fork() methods to create a Child Process instance.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'exit'", - "type": "event", - "name": "exit", - "params": [], - "desc": "

This event is emitted after the child process ends. If the process terminated\nnormally, code is the final exit code of the process, otherwise null. If\nthe process terminated due to receipt of a signal, signal is the string name\nof the signal, otherwise null.\n\n

\n

See waitpid(2).\n\n

\n" - } - ], - "properties": [ - { - "textRaw": "`stdin` {Stream object} ", - "name": "stdin", - "desc": "

A Writable Stream that represents the child process's stdin.\nClosing this stream via end() often causes the child process to terminate.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" - }, - { - "textRaw": "`stdout` {Stream object} ", - "name": "stdout", - "desc": "

A Readable Stream that represents the child process's stdout.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" - }, - { - "textRaw": "`stderr` {Stream object} ", - "name": "stderr", - "desc": "

A Readable Stream that represents the child process's stderr.\n\n

\n

If the child stdio streams are shared with the parent, then this will\nnot be set.\n\n

\n" - }, - { - "textRaw": "`pid` {Integer} ", - "name": "pid", - "desc": "

The PID of the child process.\n\n

\n

Example:\n\n

\n
var spawn = require('child_process').spawn,\n    grep  = spawn('grep', ['ssh']);\n\nconsole.log('Spawned child pid: ' + grep.pid);\ngrep.stdin.end();
\n" - } - ], - "methods": [ - { - "textRaw": "child.kill([signal])", - "type": "method", - "name": "kill", - "signatures": [ - { - "params": [ - { - "textRaw": "`signal` {String} ", - "name": "signal", - "type": "String", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "signal", - "optional": true - } - ] - } - ], - "desc": "

Send a signal to the child process. If no argument is given, the process will\nbe sent 'SIGTERM'. See signal(7) for a list of available signals.\n\n

\n
var spawn = require('child_process').spawn,\n    grep  = spawn('grep', ['ssh']);\n\ngrep.on('exit', function (code, signal) {\n  console.log('child process terminated due to receipt of signal '+signal);\n});\n\n// send SIGHUP to process\ngrep.kill('SIGHUP');
\n

Note that while the function is called kill, the signal delivered to the child\nprocess may not actually kill it. kill really just sends a signal to a process.\n\n

\n

See kill(2)\n\n

\n" - }, - { - "textRaw": "child.send(message, [sendHandle])", - "type": "method", - "name": "send", - "signatures": [ - { - "params": [ - { - "textRaw": "`message` {Object} ", - "name": "message", - "type": "Object" - }, - { - "textRaw": "`sendHandle` {Handle object} ", - "name": "sendHandle", - "type": "Handle object", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "message" - }, - { - "name": "sendHandle", - "optional": true - } - ] - } - ], - "desc": "

Send a message (and, optionally, a handle object) to a child process.\n\n

\n

See child_process.fork() for details.\n\n

\n" - } - ] - } - ], - "methods": [ - { - "textRaw": "child_process.spawn(command, [args], [options])", - "type": "method", - "name": "spawn", - "signatures": [ - { - "return": { - "textRaw": "return: {ChildProcess object} ", - "name": "return", - "type": "ChildProcess object" - }, - "params": [ - { - "textRaw": "`command` {String} The command to run ", - "name": "command", - "type": "String", - "desc": "The command to run" - }, - { - "textRaw": "`args` {Array} List of string arguments ", - "name": "args", - "type": "Array", - "desc": "List of string arguments", - "optional": true - }, - { - "textRaw": "`options` {Object} ", - "options": [ - { - "textRaw": "`cwd` {String} Current working directory of the child process ", - "name": "cwd", - "type": "String", - "desc": "Current working directory of the child process" - }, - { - "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", - "name": "customFds", - "type": "Array", - "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" - }, - { - "textRaw": "`env` {Object} Environment key-value pairs ", - "name": "env", - "type": "Object", - "desc": "Environment key-value pairs" - } - ], - "name": "options", - "type": "Object", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "command" - }, - { - "name": "args", - "optional": true - }, - { - "name": "options", - "optional": true - } - ] - } - ], - "desc": "

Launches a new process with the given command, with command line arguments in args.\nIf omitted, args defaults to an empty Array.\n\n

\n

The third argument is used to specify additional options, which defaults to:\n\n

\n
{ cwd: undefined,\n  env: process.env\n}
\n

cwd allows you to specify the working directory from which the process is spawned.\nUse env to specify environment variables that will be visible to the new process.\n\n

\n

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:\n\n

\n
var util  = require('util'),\n    spawn = require('child_process').spawn,\n    ls    = spawn('ls', ['-lh', '/usr']);\n\nls.stdout.on('data', function (data) {\n  console.log('stdout: ' + data);\n});\n\nls.stderr.on('data', function (data) {\n  console.log('stderr: ' + data);\n});\n\nls.on('exit', function (code) {\n  console.log('child process exited with code ' + code);\n});
\n

Example: A very elaborate way to run 'ps ax | grep ssh'\n\n

\n
var util  = require('util'),\n    spawn = require('child_process').spawn,\n    ps    = spawn('ps', ['ax']),\n    grep  = spawn('grep', ['ssh']);\n\nps.stdout.on('data', function (data) {\n  grep.stdin.write(data);\n});\n\nps.stderr.on('data', function (data) {\n  console.log('ps stderr: ' + data);\n});\n\nps.on('exit', function (code) {\n  if (code !== 0) {\n    console.log('ps process exited with code ' + code);\n  }\n  grep.stdin.end();\n});\n\ngrep.stdout.on('data', function (data) {\n  console.log(data);\n});\n\ngrep.stderr.on('data', function (data) {\n  console.log('grep stderr: ' + data);\n});\n\ngrep.on('exit', function (code) {\n  if (code !== 0) {\n    console.log('grep process exited with code ' + code);\n  }\n});
\n

Example of checking for failed exec:\n\n

\n
var spawn = require('child_process').spawn,\n    child = spawn('bad_command');\n\nchild.stderr.setEncoding('utf8');\nchild.stderr.on('data', function (data) {\n  if (/^execvp\\(\\)/.test(data)) {\n    console.log('Failed to start child process.');\n  }\n});
\n

Note that if spawn receives an empty options object, it will result in\nspawning the process with an empty environment rather than using\nprocess.env. This due to backwards compatibility issues with a deprecated\nAPI.\n\n

\n

There is a deprecated option called customFds which allows one to specify\nspecific file descriptors for the stdio of the child process. This API was\nnot portable to all platforms and therefore removed.\nWith customFds it was possible to hook up the new process' [stdin, stdout,\nstderr] to existing streams; -1 meant that a new stream should be created.\nUse at your own risk.\n\n

\n

There are several internal options. In particular stdinStream,\nstdoutStream, stderrStream. They are for INTERNAL USE ONLY. As with all\nundocumented APIs in Node, they should not be used.\n\n

\n

See also: child_process.exec() and child_process.fork()\n\n

\n" - }, - { - "textRaw": "child_process.exec(command, [options], callback)", - "type": "method", - "name": "exec", - "signatures": [ - { - "return": { - "textRaw": "Return: ChildProcess object ", - "name": "return", - "desc": "ChildProcess object" - }, - "params": [ - { - "textRaw": "`command` {String} The command to run, with space-separated arguments ", - "name": "command", - "type": "String", - "desc": "The command to run, with space-separated arguments" - }, - { - "textRaw": "`options` {Object} ", - "options": [ - { - "textRaw": "`cwd` {String} Current working directory of the child process ", - "name": "cwd", - "type": "String", - "desc": "Current working directory of the child process" - }, - { - "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", - "name": "customFds", - "type": "Array", - "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" - }, - { - "textRaw": "`env` {Object} Environment key-value pairs ", - "name": "env", - "type": "Object", - "desc": "Environment key-value pairs" - }, - { - "textRaw": "`encoding` {String} (Default: 'utf8') ", - "name": "encoding", - "default": "utf8", - "type": "String" - }, - { - "textRaw": "`timeout` {Number} (Default: 0) ", - "name": "timeout", - "default": "0", - "type": "Number" - }, - { - "textRaw": "`maxBuffer` {Number} (Default: 200*1024) ", - "name": "maxBuffer", - "default": "200*1024", - "type": "Number" - }, - { - "textRaw": "`killSignal` {String} (Default: 'SIGTERM') ", - "name": "killSignal", - "default": "SIGTERM", - "type": "String" - } - ], - "name": "options", - "type": "Object", - "optional": true - }, - { - "textRaw": "`callback` {Function} called with the output when process terminates ", - "options": [ - { - "textRaw": "`error` {Error} ", - "name": "error", - "type": "Error" - }, - { - "textRaw": "`stdout` {Buffer} ", - "name": "stdout", - "type": "Buffer" - }, - { - "textRaw": "`stderr` {Buffer} ", - "name": "stderr", - "type": "Buffer" - } - ], - "name": "callback", - "type": "Function", - "desc": "called with the output when process terminates" - } - ] - }, - { - "params": [ - { - "name": "command" - }, - { - "name": "options", - "optional": true - }, - { - "name": "callback" - } - ] - } - ], - "desc": "

Runs a command in a shell and buffers the output.\n\n

\n
var util = require('util'),\n    exec = require('child_process').exec,\n    child;\n\nchild = exec('cat *.js bad_file | wc -l',\n  function (error, stdout, stderr) {\n    console.log('stdout: ' + stdout);\n    console.log('stderr: ' + stderr);\n    if (error !== null) {\n      console.log('exec error: ' + error);\n    }\n});
\n

The callback gets the arguments (error, stdout, stderr). On success, error\nwill be null. On error, error will be an instance of Error and err.code\nwill be the exit code of the child process, and err.signal will be set to the\nsignal that terminated the process.\n\n

\n

There is a second optional argument to specify several options. The\ndefault options are\n\n

\n
{ encoding: 'utf8',\n  timeout: 0,\n  maxBuffer: 200*1024,\n  killSignal: 'SIGTERM',\n  cwd: null,\n  env: null }
\n

If timeout is greater than 0, then it will kill the child process\nif it runs longer than timeout milliseconds. The child process is killed with\nkillSignal (default: 'SIGTERM'). maxBuffer specifies the largest\namount of data allowed on stdout or stderr - if this value is exceeded then\nthe child process is killed.\n\n\n

\n" - }, - { - "textRaw": "child_process.execFile(file, args, options, callback)", - "type": "method", - "name": "execFile", - "signatures": [ - { - "return": { - "textRaw": "Return: ChildProcess object ", - "name": "return", - "desc": "ChildProcess object" - }, - "params": [ - { - "textRaw": "`file` {String} The filename of the program to run ", - "name": "file", - "type": "String", - "desc": "The filename of the program to run" - }, - { - "textRaw": "`args` {Array} List of string arguments ", - "name": "args", - "type": "Array", - "desc": "List of string arguments" - }, - { - "textRaw": "`options` {Object} ", - "options": [ - { - "textRaw": "`cwd` {String} Current working directory of the child process ", - "name": "cwd", - "type": "String", - "desc": "Current working directory of the child process" - }, - { - "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", - "name": "customFds", - "type": "Array", - "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" - }, - { - "textRaw": "`env` {Object} Environment key-value pairs ", - "name": "env", - "type": "Object", - "desc": "Environment key-value pairs" - }, - { - "textRaw": "`encoding` {String} (Default: 'utf8') ", - "name": "encoding", - "default": "utf8", - "type": "String" - }, - { - "textRaw": "`timeout` {Number} (Default: 0) ", - "name": "timeout", - "default": "0", - "type": "Number" - }, - { - "textRaw": "`maxBuffer` {Number} (Default: 200*1024) ", - "name": "maxBuffer", - "default": "200*1024", - "type": "Number" - }, - { - "textRaw": "`killSignal` {String} (Default: 'SIGTERM') ", - "name": "killSignal", - "default": "SIGTERM", - "type": "String" - } - ], - "name": "options", - "type": "Object" - }, - { - "textRaw": "`callback` {Function} called with the output when process terminates ", - "options": [ - { - "textRaw": "`error` {Error} ", - "name": "error", - "type": "Error" - }, - { - "textRaw": "`stdout` {Buffer} ", - "name": "stdout", - "type": "Buffer" - }, - { - "textRaw": "`stderr` {Buffer} ", - "name": "stderr", - "type": "Buffer" - } - ], - "name": "callback", - "type": "Function", - "desc": "called with the output when process terminates" - } - ] - }, - { - "params": [ - { - "name": "file" - }, - { - "name": "args" - }, - { - "name": "options" - }, - { - "name": "callback" - } - ] - } - ], - "desc": "

This is similar to child_process.exec() except it does not execute a\nsubshell but rather the specified file directly. This makes it slightly\nleaner than child_process.exec. It has the same options.\n\n\n

\n" - }, - { - "textRaw": "child_process.fork(modulePath, [args], [options])", - "type": "method", - "name": "fork", - "signatures": [ - { - "return": { - "textRaw": "Return: ChildProcess object ", - "name": "return", - "desc": "ChildProcess object" - }, - "params": [ - { - "textRaw": "`modulePath` {String} The module to run in the child ", - "name": "modulePath", - "type": "String", - "desc": "The module to run in the child" - }, - { - "textRaw": "`args` {Array} List of string arguments ", - "name": "args", - "type": "Array", - "desc": "List of string arguments", - "optional": true - }, - { - "textRaw": "`options` {Object} ", - "options": [ - { - "textRaw": "`cwd` {String} Current working directory of the child process ", - "name": "cwd", - "type": "String", - "desc": "Current working directory of the child process" - }, - { - "textRaw": "`customFds` {Array} **Deprecated** File descriptors for the child to use for stdio. (See below) ", - "name": "customFds", - "type": "Array", - "desc": "**Deprecated** File descriptors for the child to use for stdio. (See below)" - }, - { - "textRaw": "`env` {Object} Environment key-value pairs ", - "name": "env", - "type": "Object", - "desc": "Environment key-value pairs" - }, - { - "textRaw": "`encoding` {String} (Default: 'utf8') ", - "name": "encoding", - "default": "utf8", - "type": "String" - }, - { - "textRaw": "`timeout` {Number} (Default: 0) ", - "name": "timeout", - "default": "0", - "type": "Number" - } - ], - "name": "options", - "type": "Object", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "modulePath" - }, - { - "name": "args", - "optional": true - }, - { - "name": "options", - "optional": true - } - ] - } - ], - "desc": "

This is a special case of the spawn() functionality for spawning Node\nprocesses. In addition to having all the methods in a normal ChildProcess\ninstance, the returned object has a communication channel built-in. The\nchannel is written to with child.send(message, [sendHandle]) and messages\nare received by a 'message' event on the child.\n\n

\n

For example:\n\n

\n
var cp = require('child_process');\n\nvar n = cp.fork(__dirname + '/sub.js');\n\nn.on('message', function(m) {\n  console.log('PARENT got message:', m);\n});\n\nn.send({ hello: 'world' });
\n

And then the child script, 'sub.js' might look like this:\n\n

\n
process.on('message', function(m) {\n  console.log('CHILD got message:', m);\n});\n\nprocess.send({ foo: 'bar' });
\n

In the child the process object will have a send() method, and process\nwill emit objects each time it receives a message on its channel.\n\n

\n

By default the spawned Node process will have the stdin, stdout, stderr\nassociated with the parent's.\n\n

\n

These child Nodes are still whole new instances of V8. Assume at least 30ms\nstartup and 10mb memory for each new Node. That is, you cannot create many\nthousands of them.\n\n

\n

The sendHandle option to child.send() is for sending a handle object to\nanother process. Child will receive the handle as as second argument to the\nmessage event. Here is an example of sending a handle:\n\n

\n
var server = require('net').createServer();\nvar child = require('child_process').fork(__dirname + '/child.js');\n// Open up the server object and send the handle.\nserver.listen(1337, function() {\n  child.send({ server: true }, server._handle);\n});
\n

Here is an example of receiving the server handle and sharing it between\nprocesses:\n\n

\n
process.on('message', function(m, serverHandle) {\n  if (serverHandle) {\n    var server = require('net').createServer();\n    server.listen(serverHandle);\n  }\n});
\n" - } - ], - "type": "module", - "displayName": "Child Process" - } - ] -} --- a/doc/api/api/cluster.html +++ /dev/null @@ -1,192 +0,0 @@ - - - - - Cluster Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Cluster#

-
Stability: 1 Experimental - Drastic changes in future versions
-

A single instance of Node runs in a single thread. To take advantage of -multi-core systems the user will sometimes want to launch a cluster of Node -processes to handle the load. - -

-

The cluster module allows you to easily create a network of processes that -all share server ports. - -

-
var cluster = require('cluster');
-var http = require('http');
-var numCPUs = require('os').cpus().length;
-
-if (cluster.isMaster) {
-  // Fork workers.
-  for (var i = 0; i < numCPUs; i++) {
-    cluster.fork();
-  }
-
-  cluster.on('death', function(worker) {
-    console.log('worker ' + worker.pid + ' died');
-  });
-} else {
-  // Worker processes have a http server.
-  http.Server(function(req, res) {
-    res.writeHead(200);
-    res.end("hello world\n");
-  }).listen(8000);
-}
-

Running node will now share port 8000 between the workers: - -

-
% node server.js
-Worker 2438 online
-Worker 2437 online
-

The difference between cluster.fork() and child_process.fork() is simply -that cluster allows TCP servers to be shared between workers. cluster.fork -is implemented on top of child_process.fork. The message passing API that -is available with child_process.fork is available with cluster as well. -As an example, here is a cluster which keeps count of the number of requests -in the master process via message passing: - -

-
var cluster = require('cluster');
-var http = require('http');
-var numReqs = 0;
-
-if (cluster.isMaster) {
-  // Fork workers.
-  for (var i = 0; i < 2; i++) {
-    var worker = cluster.fork();
-
-    worker.on('message', function(msg) {
-      if (msg.cmd && msg.cmd == 'notifyRequest') {
-        numReqs++;
-      }
-    });
-  }
-
-  setInterval(function() {
-    console.log("numReqs =", numReqs);
-  }, 1000);
-} else {
-  // Worker processes have a http server.
-  http.Server(function(req, res) {
-    res.writeHead(200);
-    res.end("hello world\n");
-    // Send message to master process
-    process.send({ cmd: 'notifyRequest' });
-  }).listen(8000);
-}
-

cluster.fork()#

-

Spawn a new worker process. This can only be called from the master process. - -

-

cluster.isMaster#

-

cluster.isWorker#

-

Boolean flags to determine if the current process is a master or a worker -process in a cluster. A process isMaster if process.env.NODE_WORKER_ID -is undefined. - -

-

Event: 'death'#

-

When any of the workers die the cluster module will emit the 'death' event. -This can be used to restart the worker by calling fork() again. - -

-
cluster.on('death', function(worker) {
-  console.log('worker ' + worker.pid + ' died. restart...');
-  cluster.fork();
-});
-

Different techniques can be used to restart the worker depending on the -application. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/cluster.json +++ /dev/null @@ -1,48 +0,0 @@ -{ - "source": "doc/api/cluster.markdown", - "modules": [ - { - "textRaw": "Cluster", - "name": "cluster", - "stability": 1, - "stabilityText": "Experimental - Drastic changes in future versions", - "desc": "

A single instance of Node runs in a single thread. To take advantage of\nmulti-core systems the user will sometimes want to launch a cluster of Node\nprocesses to handle the load.\n\n

\n

The cluster module allows you to easily create a network of processes that\nall share server ports.\n\n

\n
var cluster = require('cluster');\nvar http = require('http');\nvar numCPUs = require('os').cpus().length;\n\nif (cluster.isMaster) {\n  // Fork workers.\n  for (var i = 0; i < numCPUs; i++) {\n    cluster.fork();\n  }\n\n  cluster.on('death', function(worker) {\n    console.log('worker ' + worker.pid + ' died');\n  });\n} else {\n  // Worker processes have a http server.\n  http.Server(function(req, res) {\n    res.writeHead(200);\n    res.end("hello world\\n");\n  }).listen(8000);\n}
\n

Running node will now share port 8000 between the workers:\n\n

\n
% node server.js\nWorker 2438 online\nWorker 2437 online
\n

The difference between cluster.fork() and child_process.fork() is simply\nthat cluster allows TCP servers to be shared between workers. cluster.fork\nis implemented on top of child_process.fork. The message passing API that\nis available with child_process.fork is available with cluster as well.\nAs an example, here is a cluster which keeps count of the number of requests\nin the master process via message passing:\n\n

\n
var cluster = require('cluster');\nvar http = require('http');\nvar numReqs = 0;\n\nif (cluster.isMaster) {\n  // Fork workers.\n  for (var i = 0; i < 2; i++) {\n    var worker = cluster.fork();\n\n    worker.on('message', function(msg) {\n      if (msg.cmd && msg.cmd == 'notifyRequest') {\n        numReqs++;\n      }\n    });\n  }\n\n  setInterval(function() {\n    console.log("numReqs =", numReqs);\n  }, 1000);\n} else {\n  // Worker processes have a http server.\n  http.Server(function(req, res) {\n    res.writeHead(200);\n    res.end("hello world\\n");\n    // Send message to master process\n    process.send({ cmd: 'notifyRequest' });\n  }).listen(8000);\n}
\n", - "methods": [ - { - "textRaw": "cluster.fork()", - "type": "method", - "name": "fork", - "desc": "

Spawn a new worker process. This can only be called from the master process.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "properties": [ - { - "textRaw": "cluster.isMaster", - "name": "isMaster", - "desc": "

Boolean flags to determine if the current process is a master or a worker\nprocess in a cluster. A process isMaster if process.env.NODE_WORKER_ID\nis undefined.\n\n

\n" - }, - { - "textRaw": "cluster.isWorker", - "name": "isWorker", - "desc": "

Boolean flags to determine if the current process is a master or a worker\nprocess in a cluster. A process isMaster if process.env.NODE_WORKER_ID\nis undefined.\n\n

\n" - } - ], - "events": [ - { - "textRaw": "Event: 'death'", - "type": "event", - "name": "death", - "desc": "

When any of the workers die the cluster module will emit the 'death' event.\nThis can be used to restart the worker by calling fork() again.\n\n

\n
cluster.on('death', function(worker) {\n  console.log('worker ' + worker.pid + ' died. restart...');\n  cluster.fork();\n});
\n

Different techniques can be used to restart the worker depending on the\napplication.\n

\n", - "params": [] - } - ], - "type": "module", - "displayName": "Cluster" - } - ] -} --- a/doc/api/api/crypto.html +++ /dev/null @@ -1,494 +0,0 @@ - - - - - Crypto Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- -
-

Table of Contents

- - -
- -
-

Crypto#

-
Stability: 3 - Stable
-

Use require('crypto') to access this module. - -

-

The crypto module requires OpenSSL to be available on the underlying platform. -It offers a way of encapsulating secure credentials to be used as part -of a secure HTTPS net or http connection. - -

-

It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods. - -

-

crypto.createCredentials(details)#

-

Creates a credentials object, with the optional details being a dictionary with keys: - -

-
    -
  • pfx : A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
    • -
  • key : a string holding the PEM encoded private key
    • -
  • cert : a string holding the PEM encoded certificate
    • -
  • passphrase : A string of passphrase for the private key or pfx
    • -
  • ca : either a string or list of strings of PEM encoded CA certificates to trust.
    • -
  • ciphers: a string describing the ciphers to use or exclude. Consult -http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details -on the format.
    • -
-

If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in -

-

http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt. - - -

-

crypto.createHash(algorithm)#

-

Creates and returns a hash object, a cryptographic hash with the given algorithm -which can be used to generate hash digests. - -

-

algorithm is dependent on the available algorithms supported by the version -of OpenSSL on the platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', etc. -On recent releases, openssl list-message-digest-algorithms will display the available digest algorithms. - -

-

Example: this program that takes the sha1 sum of a file - -

-
var filename = process.argv[2];
-var crypto = require('crypto');
-var fs = require('fs');
-
-var shasum = crypto.createHash('sha1');
-
-var s = fs.ReadStream(filename);
-s.on('data', function(d) {
-  shasum.update(d);
-});
-
-s.on('end', function() {
-  var d = shasum.digest('hex');
-  console.log(d + '  ' + filename);
-});
-

Class: Hash#

-

The class for creating hash digests of data. - -

-

Returned by crypto.createHash. - -

-

hash.update(data, [input_encoding])#

-

Updates the hash content with the given data, the encoding of which is given -in input_encoding and can be 'utf8', 'ascii' or 'binary'. -Defaults to 'binary'. -This can be called many times with new data as it is streamed. - -

-

hash.digest([encoding])#

-

Calculates the digest of all of the passed data to be hashed. -The encoding can be 'hex', 'binary' or 'base64'. -Defaults to 'binary'. - -

-

Note: hash object can not be used after digest() method been called. - - -

-

crypto.createHmac(algorithm, key)#

-

Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key. - -

-

algorithm is dependent on the available algorithms supported by OpenSSL - see createHash above. -key is the hmac key to be used. - -

-

Class: Hmac#

-

Class for creating cryptographic hmac content. - -

-

Returned by crypto.createHmac. - -

-

hmac.update(data)#

-

Update the hmac content with the given data. -This can be called many times with new data as it is streamed. - -

-

hmac.digest([encoding])#

-

Calculates the digest of all of the passed data to the hmac. -The encoding can be 'hex', 'binary' or 'base64'. -Defaults to 'binary'. - -

-

Note: hmac object can not be used after digest() method been called. - - -

-

crypto.createCipher(algorithm, password)#

-

Creates and returns a cipher object, with the given algorithm and password. - -

-

algorithm is dependent on OpenSSL, examples are 'aes192', etc. -On recent releases, openssl list-cipher-algorithms will display the -available cipher algorithms. -password is used to derive key and IV, which must be 'binary' encoded -string (See the Buffer section for more information). - -

-

crypto.createCipheriv(algorithm, key, iv)#

-

Creates and returns a cipher object, with the given algorithm, key and iv. - -

-

algorithm is the same as the createCipher(). key is a raw key used in -algorithm. iv is an Initialization vector. key and iv must be 'binary' -encoded string (See the Buffer section for more information). - -

-

Class: Cipher#

-

Class for encrypting data. - -

-

Returned by crypto.createCipher and crypto.createCipheriv. - -

-

cipher.update(data, [input_encoding], [output_encoding])#

-

Updates the cipher with data, the encoding of which is given in -input_encoding and can be 'utf8', 'ascii' or 'binary'. -Defaults to 'binary'. - -

-

The output_encoding specifies the output format of the enciphered data, -and can be 'binary', 'base64' or 'hex'. Defaults to 'binary'. - -

-

Returns the enciphered contents, and can be called many times with new data as it is streamed. - -

-

cipher.final([output_encoding])#

-

Returns any remaining enciphered contents, with output_encoding being one of: -'binary', 'base64' or 'hex'. Defaults to 'binary'. - -

-

Note: cipher object can not be used after final() method been called. - - -

-

crypto.createDecipher(algorithm, password)#

-

Creates and returns a decipher object, with the given algorithm and key. -This is the mirror of the createCipher() above. - -

-

crypto.createDecipheriv(algorithm, key, iv)#

-

Creates and returns a decipher object, with the given algorithm, key and iv. -This is the mirror of the createCipheriv() above. - -

-

Class: Decipher#

-

Class for decrypting data. - -

-

Returned by crypto.createDecipher and crypto.createDecipheriv. - -

-

decipher.update(data, [input_encoding], [output_encoding])#

-

Updates the decipher with data, which is encoded in 'binary', 'base64' -or 'hex'. Defaults to 'binary'. - -

-

The output_decoding specifies in what format to return the deciphered -plaintext: 'binary', 'ascii' or 'utf8'. Defaults to 'binary'. - -

-

decipher.final([output_encoding])#

-

Returns any remaining plaintext which is deciphered, -with output_encoding being one of: 'binary', 'ascii' or 'utf8'. -Defaults to 'binary'. - -

-

Note: decipher object can not be used after final() method been called. - - -

-

crypto.createSign(algorithm)#

-

Creates and returns a signing object, with the given algorithm. -On recent OpenSSL releases, openssl list-public-key-algorithms will display -the available signing algorithms. Examples are 'RSA-SHA256'. - -

-

Class: Signer#

-

Class for generating signatures. - -

-

Returned by crypto.createSign. - -

-

signer.update(data)#

-

Updates the signer object with data. -This can be called many times with new data as it is streamed. - -

-

signer.sign(private_key, [output_format])#

-

Calculates the signature on all the updated data passed through the signer. -private_key is a string containing the PEM encoded private key for signing. - -

-

Returns the signature in output_format which can be 'binary', 'hex' or -'base64'. Defaults to 'binary'. - -

-

Note: signer object can not be used after sign() method been called. - -

-

crypto.createVerify(algorithm)#

-

Creates and returns a verification object, with the given algorithm. -This is the mirror of the signing object above. - -

-

Class: Verify#

-

Class for verifying signatures. - -

-

Returned by crypto.createVerify. - -

-

verifier.update(data)#

-

Updates the verifier object with data. -This can be called many times with new data as it is streamed. - -

-

verifier.verify(object, signature, [signature_format])#

-

Verifies the signed data by using the object and signature. object is a -string containing a PEM encoded object, which can be one of RSA public key, -DSA public key, or X.509 certificate. signature is the previously calculated -signature for the data, in the signature_format which can be 'binary', -'hex' or 'base64'. Defaults to 'binary'. - -

-

Returns true or false depending on the validity of the signature for the data and public key. - -

-

Note: verifier object can not be used after verify() method been called. - -

-

crypto.createDiffieHellman(prime_length)#

-

Creates a Diffie-Hellman key exchange object and generates a prime of the -given bit length. The generator used is 2. - -

-

crypto.createDiffieHellman(prime, [encoding])#

-

Creates a Diffie-Hellman key exchange object using the supplied prime. The -generator used is 2. Encoding can be 'binary', 'hex', or 'base64'. -Defaults to 'binary'. - -

-

Class: DiffieHellman#

-

The class for creating Diffie-Hellman key exchanges. - -

-

Returned by crypto.createDiffieHellman. - -

-

diffieHellman.generateKeys([encoding])#

-

Generates private and public Diffie-Hellman key values, and returns the -public key in the specified encoding. This key should be transferred to the -other party. Encoding can be 'binary', 'hex', or 'base64'. -Defaults to 'binary'. - -

-

diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])#

-

Computes the shared secret using other_public_key as the other party's -public key and returns the computed shared secret. Supplied key is -interpreted using specified input_encoding, and secret is encoded using -specified output_encoding. Encodings can be 'binary', 'hex', or -'base64'. The input encoding defaults to 'binary'. -If no output encoding is given, the input encoding is used as output encoding. - -

-

diffieHellman.getPrime([encoding])#

-

Returns the Diffie-Hellman prime in the specified encoding, which can be -'binary', 'hex', or 'base64'. Defaults to 'binary'. - -

-

diffieHellman.getGenerator([encoding])#

-

Returns the Diffie-Hellman prime in the specified encoding, which can be -'binary', 'hex', or 'base64'. Defaults to 'binary'. - -

-

diffieHellman.getPublicKey([encoding])#

-

Returns the Diffie-Hellman public key in the specified encoding, which can -be 'binary', 'hex', or 'base64'. Defaults to 'binary'. - -

-

diffieHellman.getPrivateKey([encoding])#

-

Returns the Diffie-Hellman private key in the specified encoding, which can -be 'binary', 'hex', or 'base64'. Defaults to 'binary'. - -

-

diffieHellman.setPublicKey(public_key, [encoding])#

-

Sets the Diffie-Hellman public key. Key encoding can be 'binary', 'hex', -or 'base64'. Defaults to 'binary'. - -

-

diffieHellman.setPrivateKey(public_key, [encoding])#

-

Sets the Diffie-Hellman private key. Key encoding can be 'binary', 'hex', -or 'base64'. Defaults to 'binary'. - -

-

crypto.pbkdf2(password, salt, iterations, keylen, callback)#

-

Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive -a key of given length from the given password, salt and iterations. -The callback gets two arguments (err, derivedKey). - -

-

crypto.randomBytes(size, [callback])#

-

Generates cryptographically strong pseudo-random data. Usage: - -

-
// async
-crypto.randomBytes(256, function(ex, buf) {
-  if (ex) throw ex;
-  console.log('Have %d bytes of random data: %s', buf.length, buf);
-});
-
-// sync
-try {
-  var buf = crypto.randomBytes(256);
-  console.log('Have %d bytes of random data: %s', buf.length, buf);
-} catch (ex) {
-  // handle error
-}
- -
-
-
- - - - - - - - - - --- a/doc/api/api/crypto.json +++ /dev/null @@ -1,666 +0,0 @@ -{ - "source": "doc/api/crypto.markdown", - "modules": [ - { - "textRaw": "Crypto", - "name": "crypto", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Use require('crypto') to access this module.\n\n

\n

The crypto module requires OpenSSL to be available on the underlying platform.\nIt offers a way of encapsulating secure credentials to be used as part\nof a secure HTTPS net or http connection.\n\n

\n

It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods.\n\n

\n", - "methods": [ - { - "textRaw": "crypto.createCredentials(details)", - "type": "method", - "name": "createCredentials", - "desc": "

Creates a credentials object, with the optional details being a dictionary with keys:\n\n

\n
    \n
  • pfx : A string or buffer holding the PFX or PKCS12 encoded private key, certificate and CA certificates
    • \n
  • key : a string holding the PEM encoded private key
    • \n
  • cert : a string holding the PEM encoded certificate
    • \n
  • passphrase : A string of passphrase for the private key or pfx
    • \n
  • ca : either a string or list of strings of PEM encoded CA certificates to trust.
    • \n
  • ciphers: a string describing the ciphers to use or exclude. Consult\nhttp://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for details\non the format.
    • \n
\n

If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in\n

\n

http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "details" - } - ] - } - ] - }, - { - "textRaw": "crypto.createHash(algorithm)", - "type": "method", - "name": "createHash", - "desc": "

Creates and returns a hash object, a cryptographic hash with the given algorithm\nwhich can be used to generate hash digests.\n\n

\n

algorithm is dependent on the available algorithms supported by the version\nof OpenSSL on the platform. Examples are 'sha1', 'md5', 'sha256', 'sha512', etc.\nOn recent releases, openssl list-message-digest-algorithms will display the available digest algorithms.\n\n

\n

Example: this program that takes the sha1 sum of a file\n\n

\n
var filename = process.argv[2];\nvar crypto = require('crypto');\nvar fs = require('fs');\n\nvar shasum = crypto.createHash('sha1');\n\nvar s = fs.ReadStream(filename);\ns.on('data', function(d) {\n  shasum.update(d);\n});\n\ns.on('end', function() {\n  var d = shasum.digest('hex');\n  console.log(d + '  ' + filename);\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - } - ] - } - ] - }, - { - "textRaw": "crypto.createHmac(algorithm, key)", - "type": "method", - "name": "createHmac", - "desc": "

Creates and returns a hmac object, a cryptographic hmac with the given algorithm and key.\n\n

\n

algorithm is dependent on the available algorithms supported by OpenSSL - see createHash above.\nkey is the hmac key to be used.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - }, - { - "name": "key" - } - ] - } - ] - }, - { - "textRaw": "crypto.createCipher(algorithm, password)", - "type": "method", - "name": "createCipher", - "desc": "

Creates and returns a cipher object, with the given algorithm and password.\n\n

\n

algorithm is dependent on OpenSSL, examples are 'aes192', etc.\nOn recent releases, openssl list-cipher-algorithms will display the\navailable cipher algorithms.\npassword is used to derive key and IV, which must be 'binary' encoded\nstring (See the Buffer section for more information).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - }, - { - "name": "password" - } - ] - } - ] - }, - { - "textRaw": "crypto.createCipheriv(algorithm, key, iv)", - "type": "method", - "name": "createCipheriv", - "desc": "

Creates and returns a cipher object, with the given algorithm, key and iv.\n\n

\n

algorithm is the same as the createCipher(). key is a raw key used in\nalgorithm. iv is an Initialization vector. key and iv must be 'binary'\nencoded string (See the Buffer section for more information).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - }, - { - "name": "key" - }, - { - "name": "iv" - } - ] - } - ] - }, - { - "textRaw": "crypto.createDecipher(algorithm, password)", - "type": "method", - "name": "createDecipher", - "desc": "

Creates and returns a decipher object, with the given algorithm and key.\nThis is the mirror of the createCipher() above.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - }, - { - "name": "password" - } - ] - } - ] - }, - { - "textRaw": "crypto.createDecipheriv(algorithm, key, iv)", - "type": "method", - "name": "createDecipheriv", - "desc": "

Creates and returns a decipher object, with the given algorithm, key and iv.\nThis is the mirror of the createCipheriv() above.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - }, - { - "name": "key" - }, - { - "name": "iv" - } - ] - } - ] - }, - { - "textRaw": "crypto.createSign(algorithm)", - "type": "method", - "name": "createSign", - "desc": "

Creates and returns a signing object, with the given algorithm.\nOn recent OpenSSL releases, openssl list-public-key-algorithms will display\nthe available signing algorithms. Examples are 'RSA-SHA256'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - } - ] - } - ] - }, - { - "textRaw": "crypto.createVerify(algorithm)", - "type": "method", - "name": "createVerify", - "desc": "

Creates and returns a verification object, with the given algorithm.\nThis is the mirror of the signing object above.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "algorithm" - } - ] - } - ] - }, - { - "textRaw": "crypto.createDiffieHellman(prime_length)", - "type": "method", - "name": "createDiffieHellman", - "desc": "

Creates a Diffie-Hellman key exchange object and generates a prime of the\ngiven bit length. The generator used is 2.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "prime_length" - } - ] - } - ] - }, - { - "textRaw": "crypto.createDiffieHellman(prime, [encoding])", - "type": "method", - "name": "createDiffieHellman", - "desc": "

Creates a Diffie-Hellman key exchange object using the supplied prime. The\ngenerator used is 2. Encoding can be 'binary', 'hex', or 'base64'.\nDefaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "prime" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "crypto.pbkdf2(password, salt, iterations, keylen, callback)", - "type": "method", - "name": "pbkdf2", - "desc": "

Asynchronous PBKDF2 applies pseudorandom function HMAC-SHA1 to derive\na key of given length from the given password, salt and iterations.\nThe callback gets two arguments (err, derivedKey).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "password" - }, - { - "name": "salt" - }, - { - "name": "iterations" - }, - { - "name": "keylen" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "crypto.randomBytes(size, [callback])", - "type": "method", - "name": "randomBytes", - "desc": "

Generates cryptographically strong pseudo-random data. Usage:\n\n

\n
// async\ncrypto.randomBytes(256, function(ex, buf) {\n  if (ex) throw ex;\n  console.log('Have %d bytes of random data: %s', buf.length, buf);\n});\n\n// sync\ntry {\n  var buf = crypto.randomBytes(256);\n  console.log('Have %d bytes of random data: %s', buf.length, buf);\n} catch (ex) {\n  // handle error\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "size" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: Hash", - "type": "class", - "name": "Hash", - "desc": "

The class for creating hash digests of data.\n\n

\n

Returned by crypto.createHash.\n\n

\n", - "methods": [ - { - "textRaw": "hash.update(data, [input_encoding])", - "type": "method", - "name": "update", - "desc": "

Updates the hash content with the given data, the encoding of which is given\nin input_encoding and can be 'utf8', 'ascii' or 'binary'.\nDefaults to 'binary'.\nThis can be called many times with new data as it is streamed.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - }, - { - "name": "input_encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "hash.digest([encoding])", - "type": "method", - "name": "digest", - "desc": "

Calculates the digest of all of the passed data to be hashed.\nThe encoding can be 'hex', 'binary' or 'base64'.\nDefaults to 'binary'.\n\n

\n

Note: hash object can not be used after digest() method been called.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: Hmac", - "type": "class", - "name": "Hmac", - "desc": "

Class for creating cryptographic hmac content.\n\n

\n

Returned by crypto.createHmac.\n\n

\n", - "methods": [ - { - "textRaw": "hmac.update(data)", - "type": "method", - "name": "update", - "desc": "

Update the hmac content with the given data.\nThis can be called many times with new data as it is streamed.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - } - ] - } - ] - }, - { - "textRaw": "hmac.digest([encoding])", - "type": "method", - "name": "digest", - "desc": "

Calculates the digest of all of the passed data to the hmac.\nThe encoding can be 'hex', 'binary' or 'base64'.\nDefaults to 'binary'.\n\n

\n

Note: hmac object can not be used after digest() method been called.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: Cipher", - "type": "class", - "name": "Cipher", - "desc": "

Class for encrypting data.\n\n

\n

Returned by crypto.createCipher and crypto.createCipheriv.\n\n

\n", - "methods": [ - { - "textRaw": "cipher.update(data, [input_encoding], [output_encoding])", - "type": "method", - "name": "update", - "desc": "

Updates the cipher with data, the encoding of which is given in\ninput_encoding and can be 'utf8', 'ascii' or 'binary'.\nDefaults to 'binary'.\n\n

\n

The output_encoding specifies the output format of the enciphered data,\nand can be 'binary', 'base64' or 'hex'. Defaults to 'binary'.\n\n

\n

Returns the enciphered contents, and can be called many times with new data as it is streamed.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - }, - { - "name": "input_encoding", - "optional": true - }, - { - "name": "output_encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "cipher.final([output_encoding])", - "type": "method", - "name": "final", - "desc": "

Returns any remaining enciphered contents, with output_encoding being one of:\n'binary', 'base64' or 'hex'. Defaults to 'binary'.\n\n

\n

Note: cipher object can not be used after final() method been called.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "output_encoding", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: Decipher", - "type": "class", - "name": "Decipher", - "desc": "

Class for decrypting data.\n\n

\n

Returned by crypto.createDecipher and crypto.createDecipheriv.\n\n

\n", - "methods": [ - { - "textRaw": "decipher.update(data, [input_encoding], [output_encoding])", - "type": "method", - "name": "update", - "desc": "

Updates the decipher with data, which is encoded in 'binary', 'base64'\nor 'hex'. Defaults to 'binary'.\n\n

\n

The output_decoding specifies in what format to return the deciphered\nplaintext: 'binary', 'ascii' or 'utf8'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - }, - { - "name": "input_encoding", - "optional": true - }, - { - "name": "output_encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "decipher.final([output_encoding])", - "type": "method", - "name": "final", - "desc": "

Returns any remaining plaintext which is deciphered,\nwith output_encoding being one of: 'binary', 'ascii' or 'utf8'.\nDefaults to 'binary'.\n\n

\n

Note: decipher object can not be used after final() method been called.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "output_encoding", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: Signer", - "type": "class", - "name": "Signer", - "desc": "

Class for generating signatures.\n\n

\n

Returned by crypto.createSign.\n\n

\n", - "methods": [ - { - "textRaw": "signer.update(data)", - "type": "method", - "name": "update", - "desc": "

Updates the signer object with data.\nThis can be called many times with new data as it is streamed.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - } - ] - } - ] - }, - { - "textRaw": "signer.sign(private_key, [output_format])", - "type": "method", - "name": "sign", - "desc": "

Calculates the signature on all the updated data passed through the signer.\nprivate_key is a string containing the PEM encoded private key for signing.\n\n

\n

Returns the signature in output_format which can be 'binary', 'hex' or\n'base64'. Defaults to 'binary'.\n\n

\n

Note: signer object can not be used after sign() method been called.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "private_key" - }, - { - "name": "output_format", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: Verify", - "type": "class", - "name": "Verify", - "desc": "

Class for verifying signatures.\n\n

\n

Returned by crypto.createVerify.\n\n

\n", - "methods": [ - { - "textRaw": "verifier.update(data)", - "type": "method", - "name": "update", - "desc": "

Updates the verifier object with data.\nThis can be called many times with new data as it is streamed.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - } - ] - } - ] - }, - { - "textRaw": "verifier.verify(object, signature, [signature_format])", - "type": "method", - "name": "verify", - "desc": "

Verifies the signed data by using the object and signature. object is a\nstring containing a PEM encoded object, which can be one of RSA public key,\nDSA public key, or X.509 certificate. signature is the previously calculated\nsignature for the data, in the signature_format which can be 'binary',\n'hex' or 'base64'. Defaults to 'binary'.\n\n

\n

Returns true or false depending on the validity of the signature for the data and public key.\n\n

\n

Note: verifier object can not be used after verify() method been called.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "object" - }, - { - "name": "signature" - }, - { - "name": "signature_format", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Class: DiffieHellman", - "type": "class", - "name": "DiffieHellman", - "desc": "

The class for creating Diffie-Hellman key exchanges.\n\n

\n

Returned by crypto.createDiffieHellman.\n\n

\n", - "methods": [ - { - "textRaw": "diffieHellman.generateKeys([encoding])", - "type": "method", - "name": "generateKeys", - "desc": "

Generates private and public Diffie-Hellman key values, and returns the\npublic key in the specified encoding. This key should be transferred to the\nother party. Encoding can be 'binary', 'hex', or 'base64'.\nDefaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.computeSecret(other_public_key, [input_encoding], [output_encoding])", - "type": "method", - "name": "computeSecret", - "desc": "

Computes the shared secret using other_public_key as the other party's\npublic key and returns the computed shared secret. Supplied key is\ninterpreted using specified input_encoding, and secret is encoded using\nspecified output_encoding. Encodings can be 'binary', 'hex', or\n'base64'. The input encoding defaults to 'binary'.\nIf no output encoding is given, the input encoding is used as output encoding.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "other_public_key" - }, - { - "name": "input_encoding", - "optional": true - }, - { - "name": "output_encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.getPrime([encoding])", - "type": "method", - "name": "getPrime", - "desc": "

Returns the Diffie-Hellman prime in the specified encoding, which can be\n'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.getGenerator([encoding])", - "type": "method", - "name": "getGenerator", - "desc": "

Returns the Diffie-Hellman prime in the specified encoding, which can be\n'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.getPublicKey([encoding])", - "type": "method", - "name": "getPublicKey", - "desc": "

Returns the Diffie-Hellman public key in the specified encoding, which can\nbe 'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.getPrivateKey([encoding])", - "type": "method", - "name": "getPrivateKey", - "desc": "

Returns the Diffie-Hellman private key in the specified encoding, which can\nbe 'binary', 'hex', or 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.setPublicKey(public_key, [encoding])", - "type": "method", - "name": "setPublicKey", - "desc": "

Sets the Diffie-Hellman public key. Key encoding can be 'binary', 'hex',\nor 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "public_key" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "diffieHellman.setPrivateKey(public_key, [encoding])", - "type": "method", - "name": "setPrivateKey", - "desc": "

Sets the Diffie-Hellman private key. Key encoding can be 'binary', 'hex',\nor 'base64'. Defaults to 'binary'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "public_key" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - } - ] - } - ], - "type": "module", - "displayName": "Crypto" - } - ] -} --- a/doc/api/api/debugger.html +++ /dev/null @@ -1,237 +0,0 @@ - - - - - Debugger Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Debugger#

-
Stability: 3 - Stable
- - -

V8 comes with an extensive debugger which is accessible out-of-process via a -simple TCP protocol. -Node has a built-in client for this debugger. To use this, start Node with the -debug argument; a prompt will appear: - -

-
% node debug myscript.js
-< debugger listening on port 5858
-connecting... ok
-break in /home/indutny/Code/git/indutny/myscript.js:1
-  1 x = 5;
-  2 setTimeout(function () {
-  3   debugger;
-debug>
-

Node's debugger client doesn't support the full range of commands, but -simple step and inspection is possible. By putting the statement debugger; -into the source code of your script, you will enable a breakpoint. - -

-

For example, suppose myscript.js looked like this: - -

-
// myscript.js
-x = 5;
-setTimeout(function () {
-  debugger;
-  console.log("world");
-}, 1000);
-console.log("hello");
-

Then once the debugger is run, it will break on line 4. - -

-
% node debug myscript.js
-< debugger listening on port 5858
-connecting... ok
-break in /home/indutny/Code/git/indutny/myscript.js:1
-  1 x = 5;
-  2 setTimeout(function () {
-  3   debugger;
-debug> cont
-< hello
-break in /home/indutny/Code/git/indutny/myscript.js:3
-  1 x = 5;
-  2 setTimeout(function () {
-  3   debugger;
-  4   console.log("world");
-  5 }, 1000);
-debug> next
-break in /home/indutny/Code/git/indutny/myscript.js:4
-  2 setTimeout(function () {
-  3   debugger;
-  4   console.log("world");
-  5 }, 1000);
-  6 console.log("hello");
-debug> repl
-Press Ctrl + C to leave debug repl
-> x
-5
-> 2+2
-4
-debug> next
-< world
-break in /home/indutny/Code/git/indutny/myscript.js:5
-  3   debugger;
-  4   console.log("world");
-  5 }, 1000);
-  6 console.log("hello");
-  7
-debug> quit
-%
-

The repl command allows you to evaluate code remotely. The next command -steps over to the next line. There are a few other commands available and more -to come. Type help to see others. - -

-

Watchers#

-

You can watch expression and variable values while debugging your code. -On every breakpoint each expression from the watchers list will be evaluated -in the current context and displayed just before the breakpoint's source code -listing. - -

-

To start watching an expression, type watch("my_expression"). watchers -prints the active watchers. To remove a watcher, type -unwatch("my_expression"). - -

-

Commands reference#

-

Stepping#

-
    -
  • cont, c - Continue execution
    • -
  • next, n - Step next
    • -
  • step, s - Step in
    • -
  • out, o - Step out
    • -
-

Breakpoints#

-
    -
  • setBreakpoint(), sb() - Set breakpoint on current line
    • -
  • setBreakpoint('fn()'), sb(...) - Set breakpoint on a first statement in -functions body
    • -
  • setBreakpoint('script.js', 1), sb(...) - Set breakpoint on first line of -script.js
    • -
  • clearBreakpoint, cb(...) - Clear breakpoint
    • -
-

Info#

-
    -
  • backtrace, bt - Print backtrace of current execution frame
    • -
  • list(5) - List scripts source code with 5 line context (5 lines before and -after)
    • -
  • watch(expr) - Add expression to watch list
    • -
  • unwatch(expr) - Remove expression from watch list
    • -
  • watchers - List all watchers and their values (automatically listed on each -breakpoint)
    • -
  • repl - Open debugger's repl for evaluation in debugging script's context
    • -
-

Execution control#

-
    -
  • run - Run script (automatically runs on debugger's start)
    • -
  • restart - Restart script
    • -
  • kill - Kill script
    • -
-

Various#

-
    -
  • scripts - List all loaded scripts
    • -
  • version - Display v8's version
    • -
-

Advanced Usage#

-

The V8 debugger can be enabled and accessed either by starting Node with -the --debug command-line flag or by signaling an existing Node process -with SIGUSR1. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/debugger.json +++ /dev/null @@ -1,51 +0,0 @@ -{ - "source": "doc/api/debugger.markdown", - "stability": 3, - "stabilityText": "Stable", - "miscs": [ - { - "textRaw": "Debugger", - "name": "Debugger", - "stability": 3, - "stabilityText": "Stable", - "type": "misc", - "desc": "

V8 comes with an extensive debugger which is accessible out-of-process via a\nsimple TCP protocol.\nNode has a built-in client for this debugger. To use this, start Node with the\ndebug argument; a prompt will appear:\n\n

\n
% node debug myscript.js\n< debugger listening on port 5858\nconnecting... ok\nbreak in /home/indutny/Code/git/indutny/myscript.js:1\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\ndebug>
\n

Node's debugger client doesn't support the full range of commands, but\nsimple step and inspection is possible. By putting the statement debugger;\ninto the source code of your script, you will enable a breakpoint.\n\n

\n

For example, suppose myscript.js looked like this:\n\n

\n
// myscript.js\nx = 5;\nsetTimeout(function () {\n  debugger;\n  console.log("world");\n}, 1000);\nconsole.log("hello");
\n

Then once the debugger is run, it will break on line 4.\n\n

\n
% node debug myscript.js\n< debugger listening on port 5858\nconnecting... ok\nbreak in /home/indutny/Code/git/indutny/myscript.js:1\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\ndebug> cont\n< hello\nbreak in /home/indutny/Code/git/indutny/myscript.js:3\n  1 x = 5;\n  2 setTimeout(function () {\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\ndebug> next\nbreak in /home/indutny/Code/git/indutny/myscript.js:4\n  2 setTimeout(function () {\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\n  6 console.log("hello");\ndebug> repl\nPress Ctrl + C to leave debug repl\n> x\n5\n> 2+2\n4\ndebug> next\n< world\nbreak in /home/indutny/Code/git/indutny/myscript.js:5\n  3   debugger;\n  4   console.log("world");\n  5 }, 1000);\n  6 console.log("hello");\n  7\ndebug> quit\n%
\n

The repl command allows you to evaluate code remotely. The next command\nsteps over to the next line. There are a few other commands available and more\nto come. Type help to see others.\n\n

\n", - "miscs": [ - { - "textRaw": "Watchers", - "name": "watchers", - "desc": "

You can watch expression and variable values while debugging your code.\nOn every breakpoint each expression from the watchers list will be evaluated\nin the current context and displayed just before the breakpoint's source code\nlisting.\n\n

\n

To start watching an expression, type watch("my_expression"). watchers\nprints the active watchers. To remove a watcher, type\nunwatch("my_expression").\n\n

\n", - "type": "misc", - "displayName": "Watchers" - }, - { - "textRaw": "Commands reference", - "name": "commands_reference", - "modules": [ - { - "textRaw": "Execution control", - "name": "Execution control", - "type": "module", - "displayName": "Various" - }, - { - "textRaw": "Various", - "name": "various", - "type": "module", - "displayName": "Various" - } - ], - "type": "misc", - "displayName": "Commands reference" - }, - { - "textRaw": "Advanced Usage", - "name": "advanced_usage", - "desc": "

The V8 debugger can be enabled and accessed either by starting Node with\nthe --debug command-line flag or by signaling an existing Node process\nwith SIGUSR1.\n

\n", - "type": "misc", - "displayName": "Advanced Usage" - } - ] - } - ] -} --- a/doc/api/api/dgram.html +++ /dev/null @@ -1,339 +0,0 @@ - - - - - UDP / Datagram Sockets Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

UDP / Datagram Sockets#

-
Stability: 3 - Stable
- - -

Datagram sockets are available through require('dgram'). - -

-

dgram.createSocket(type, [callback])#

-
    -
  • type String. Either 'udp4' or 'udp6'
    • -
  • callback Function. Attached as a listener to message events. -Optional
    • -
  • Returns: Socket object
    • -
-

Creates a datagram Socket of the specified types. Valid types are udp4 -and udp6. - -

-

Takes an optional callback which is added as a listener for message events. - -

-

Call socket.bind if you want to receive datagrams. socket.bind() will bind -to the "all interfaces" address on a random port (it does the right thing for -both udp4 and udp6 sockets). You can then retrieve the address and port -with socket.address().address and socket.address().port. - -

-

Class: Socket#

-

The dgram Socket class encapsulates the datagram functionality. It -should be created via dgram.createSocket(type, [callback]). - -

-

Event: 'message'#

-
    -
  • msg Buffer object. The message
    • -
  • rinfo Object. Remote address information
    • -
-

Emitted when a new datagram is available on a socket. msg is a Buffer and rinfo is -an object with the sender's address information and the number of bytes in the datagram. - -

-

Event: 'listening'#

-

Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets -are created. - -

-

Event: 'close'#

-

Emitted when a socket is closed with close(). No new message events will be emitted -on this socket. - -

-

Event: 'error'#

-
    -
  • exception Error object
    • -
-

Emitted when an error occurs. - -

-

dgram.send(buf, offset, length, port, address, [callback])#

-
    -
  • buf Buffer object. Message to be sent
    • -
  • offset Integer. Offset in the buffer where the message starts.
    • -
  • length Integer. Number of bytes in the message.
    • -
  • port Integer. destination port
    • -
  • address String. destination IP
    • -
  • callback Function. Callback when message is done being delivered. -Optional.
    • -
-

For UDP sockets, the destination port and IP address must be specified. A string -may be supplied for the address parameter, and it will be resolved with DNS. An -optional callback may be specified to detect any DNS errors and when buf may be -re-used. Note that DNS lookups will delay the time that a send takes place, at -least until the next tick. The only way to know for sure that a send has taken place -is to use the callback. - -

-

If the socket has not been previously bound with a call to bind, it's -assigned a random port number and bound to the "all interfaces" address -(0.0.0.0 for udp4 sockets, ::0 for udp6 sockets). - -

-

Example of sending a UDP packet to a random port on localhost; - -

-
var dgram = require('dgram');
-var message = new Buffer("Some bytes");
-var client = dgram.createSocket("udp4");
-client.send(message, 0, message.length, 41234, "localhost", function(err, bytes) {
-  client.close();
-});
-

A Note about UDP datagram size - -

-

The maximum size of an IPv4/v6 datagram depends on the MTU (Maximum Transmission Unit) -and on the Payload Length field size. - -

-
    -

  • The Payload Length field is 16 bits wide, which means that a normal payload -cannot be larger than 64K octets including internet header and data -(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header); -this is generally true for loopback interfaces, but such long datagrams -are impractical for most hosts and networks.

    -
    • -

  • The MTU is the largest size a given link layer technology can support for datagrams. -For any link, IPv4 mandates a minimum MTU of 68 octets, while the recommended MTU -for IPv4 is 576 (typically recommended as the MTU for dial-up type applications), -whether they arrive whole or in fragments.

    -

    For IPv6, the minimum MTU is 1280 octets, however, the mandatory minimum -fragment reassembly buffer size is 1500 octets. -The value of 68 octets is very small, since most current link layer technologies have -a minimum MTU of 1500 (like Ethernet).

    -
    • -
-

Note that it's impossible to know in advance the MTU of each link through which -a packet might travel, and that generally sending a datagram greater than -the (receiver) MTU won't work (the packet gets silently dropped, without -informing the source that the data did not reach its intended recipient). - -

-

dgram.bind(port, [address])#

-
    -
  • port Integer
    • -
  • address String, Optional
    • -
-

For UDP sockets, listen for datagrams on a named port and optional address. If -address is not specified, the OS will try to listen on all addresses. - -

-

Example of a UDP server listening on port 41234: - -

-
var dgram = require("dgram");
-
-var server = dgram.createSocket("udp4");
-
-server.on("message", function (msg, rinfo) {
-  console.log("server got: " + msg + " from " +
-    rinfo.address + ":" + rinfo.port);
-});
-
-server.on("listening", function () {
-  var address = server.address();
-  console.log("server listening " +
-      address.address + ":" + address.port);
-});
-
-server.bind(41234);
-// server listening 0.0.0.0:41234
-

dgram.close()#

-

Close the underlying socket and stop listening for data on it. - -

-

dgram.address()#

-

Returns an object containing the address information for a socket. For UDP sockets, -this object will contain address and port. - -

-

dgram.setBroadcast(flag)#

-
    -
  • flag Boolean
    • -
-

Sets or clears the SO_BROADCAST socket option. When this option is set, UDP packets -may be sent to a local interface's broadcast address. - -

-

dgram.setTTL(ttl)#

-
    -
  • ttl Integer
    • -
-

Sets the IP_TTL socket option. TTL stands for "Time to Live," but in this context it -specifies the number of IP hops that a packet is allowed to go through. Each router or -gateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a -router, it will not be forwarded. Changing TTL values is typically done for network -probes or when multicasting. - -

-

The argument to setTTL() is a number of hops between 1 and 255. The default on most -systems is 64. - -

-

dgram.setMulticastTTL(ttl)#

-
    -
  • ttl Integer
    • -
-

Sets the IP_MULTICAST_TTL socket option. TTL stands for "Time to Live," but in this -context it specifies the number of IP hops that a packet is allowed to go through, -specifically for multicast traffic. Each router or gateway that forwards a packet -decrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded. - -

-

The argument to setMulticastTTL() is a number of hops between 0 and 255. The default on most -systems is 64. - -

-

dgram.setMulticastLoopback(flag)#

-
    -
  • flag Boolean
    • -
-

Sets or clears the IP_MULTICAST_LOOP socket option. When this option is set, multicast -packets will also be received on the local interface. - -

-

dgram.addMembership(multicastAddress, [multicastInterface])#

-
    -
  • multicastAddress String
    • -
  • multicastInterface String, Optional
    • -
-

Tells the kernel to join a multicast group with IP_ADD_MEMBERSHIP socket option. - -

-

If multicastInterface is not specified, the OS will try to add membership to all valid -interfaces. - -

-

dgram.dropMembership(multicastAddress, [multicastInterface])#

-
    -
  • multicastAddress String
    • -
  • multicastInterface String, Optional
    • -
-

Opposite of addMembership - tells the kernel to leave a multicast group with -IP_DROP_MEMBERSHIP socket option. This is automatically called by the kernel -when the socket is closed or process terminates, so most apps will never need to call -this. - -

-

If multicastInterface is not specified, the OS will try to drop membership to all valid -interfaces. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/dgram.json +++ /dev/null @@ -1,381 +0,0 @@ -{ - "source": "doc/api/dgram.markdown", - "modules": [ - { - "textRaw": "UDP / Datagram Sockets", - "name": "dgram", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Datagram sockets are available through require('dgram').\n\n

\n", - "methods": [ - { - "textRaw": "dgram.createSocket(type, [callback])", - "type": "method", - "name": "createSocket", - "signatures": [ - { - "return": { - "textRaw": "Returns: Socket object ", - "name": "return", - "desc": "Socket object" - }, - "params": [ - { - "textRaw": "`type` String. Either 'udp4' or 'udp6' ", - "name": "type", - "desc": "String. Either 'udp4' or 'udp6'" - }, - { - "textRaw": "`callback` Function. Attached as a listener to `message` events. Optional ", - "name": "callback", - "optional": true, - "desc": "Function. Attached as a listener to `message` events." - } - ] - }, - { - "params": [ - { - "name": "type" - }, - { - "name": "callback", - "optional": true - } - ] - } - ], - "desc": "

Creates a datagram Socket of the specified types. Valid types are udp4\nand udp6.\n\n

\n

Takes an optional callback which is added as a listener for message events.\n\n

\n

Call socket.bind if you want to receive datagrams. socket.bind() will bind\nto the "all interfaces" address on a random port (it does the right thing for\nboth udp4 and udp6 sockets). You can then retrieve the address and port\nwith socket.address().address and socket.address().port.\n\n

\n" - } - ], - "classes": [ - { - "textRaw": "Class: Socket", - "type": "class", - "name": "Socket", - "desc": "

The dgram Socket class encapsulates the datagram functionality. It\nshould be created via dgram.createSocket(type, [callback]).\n\n

\n", - "events": [ - { - "textRaw": "Event: 'message'", - "type": "event", - "name": "message", - "params": [], - "desc": "

Emitted when a new datagram is available on a socket. msg is a Buffer and rinfo is\nan object with the sender's address information and the number of bytes in the datagram.\n\n

\n" - }, - { - "textRaw": "Event: 'listening'", - "type": "event", - "name": "listening", - "desc": "

Emitted when a socket starts listening for datagrams. This happens as soon as UDP sockets\nare created.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

Emitted when a socket is closed with close(). No new message events will be emitted\non this socket.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "params": [], - "desc": "

Emitted when an error occurs.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "dgram.send(buf, offset, length, port, address, [callback])", - "type": "method", - "name": "send", - "signatures": [ - { - "params": [ - { - "textRaw": "`buf` Buffer object. Message to be sent ", - "name": "buf", - "desc": "Buffer object. Message to be sent" - }, - { - "textRaw": "`offset` Integer. Offset in the buffer where the message starts. ", - "name": "offset", - "desc": "Integer. Offset in the buffer where the message starts." - }, - { - "textRaw": "`length` Integer. Number of bytes in the message. ", - "name": "length", - "desc": "Integer. Number of bytes in the message." - }, - { - "textRaw": "`port` Integer. destination port ", - "name": "port", - "desc": "Integer. destination port" - }, - { - "textRaw": "`address` String. destination IP ", - "name": "address", - "desc": "String. destination IP" - }, - { - "textRaw": "`callback` Function. Callback when message is done being delivered. Optional. ", - "name": "callback", - "desc": "Function. Callback when message is done being delivered. Optional.", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "buf" - }, - { - "name": "offset" - }, - { - "name": "length" - }, - { - "name": "port" - }, - { - "name": "address" - }, - { - "name": "callback", - "optional": true - } - ] - } - ], - "desc": "

For UDP sockets, the destination port and IP address must be specified. A string\nmay be supplied for the address parameter, and it will be resolved with DNS. An\noptional callback may be specified to detect any DNS errors and when buf may be\nre-used. Note that DNS lookups will delay the time that a send takes place, at\nleast until the next tick. The only way to know for sure that a send has taken place\nis to use the callback.\n\n

\n

If the socket has not been previously bound with a call to bind, it's\nassigned a random port number and bound to the "all interfaces" address\n(0.0.0.0 for udp4 sockets, ::0 for udp6 sockets).\n\n

\n

Example of sending a UDP packet to a random port on localhost;\n\n

\n
var dgram = require('dgram');\nvar message = new Buffer("Some bytes");\nvar client = dgram.createSocket("udp4");\nclient.send(message, 0, message.length, 41234, "localhost", function(err, bytes) {\n  client.close();\n});
\n

A Note about UDP datagram size\n\n

\n

The maximum size of an IPv4/v6 datagram depends on the MTU (Maximum Transmission Unit)\nand on the Payload Length field size.\n\n

\n
    \n

  • The Payload Length field is 16 bits wide, which means that a normal payload\ncannot be larger than 64K octets including internet header and data\n(65,507 bytes = 65,535 − 8 bytes UDP header − 20 bytes IP header);\nthis is generally true for loopback interfaces, but such long datagrams\nare impractical for most hosts and networks.

    \n
    • \n

  • The MTU is the largest size a given link layer technology can support for datagrams.\nFor any link, IPv4 mandates a minimum MTU of 68 octets, while the recommended MTU\nfor IPv4 is 576 (typically recommended as the MTU for dial-up type applications),\nwhether they arrive whole or in fragments.

    \n

    For IPv6, the minimum MTU is 1280 octets, however, the mandatory minimum\nfragment reassembly buffer size is 1500 octets.\nThe value of 68 octets is very small, since most current link layer technologies have\na minimum MTU of 1500 (like Ethernet).

    \n
    • \n
\n

Note that it's impossible to know in advance the MTU of each link through which\na packet might travel, and that generally sending a datagram greater than\nthe (receiver) MTU won't work (the packet gets silently dropped, without\ninforming the source that the data did not reach its intended recipient).\n\n

\n" - }, - { - "textRaw": "dgram.bind(port, [address])", - "type": "method", - "name": "bind", - "signatures": [ - { - "params": [ - { - "textRaw": "`port` Integer ", - "name": "port", - "desc": "Integer" - }, - { - "textRaw": "`address` String, Optional ", - "name": "address", - "optional": true, - "desc": "String" - } - ] - }, - { - "params": [ - { - "name": "port" - }, - { - "name": "address", - "optional": true - } - ] - } - ], - "desc": "

For UDP sockets, listen for datagrams on a named port and optional address. If\naddress is not specified, the OS will try to listen on all addresses.\n\n

\n

Example of a UDP server listening on port 41234:\n\n

\n
var dgram = require("dgram");\n\nvar server = dgram.createSocket("udp4");\n\nserver.on("message", function (msg, rinfo) {\n  console.log("server got: " + msg + " from " +\n    rinfo.address + ":" + rinfo.port);\n});\n\nserver.on("listening", function () {\n  var address = server.address();\n  console.log("server listening " +\n      address.address + ":" + address.port);\n});\n\nserver.bind(41234);\n// server listening 0.0.0.0:41234
\n" - }, - { - "textRaw": "dgram.close()", - "type": "method", - "name": "close", - "desc": "

Close the underlying socket and stop listening for data on it.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "dgram.address()", - "type": "method", - "name": "address", - "desc": "

Returns an object containing the address information for a socket. For UDP sockets,\nthis object will contain address and port.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "dgram.setBroadcast(flag)", - "type": "method", - "name": "setBroadcast", - "signatures": [ - { - "params": [ - { - "textRaw": "`flag` Boolean ", - "name": "flag", - "desc": "Boolean" - } - ] - }, - { - "params": [ - { - "name": "flag" - } - ] - } - ], - "desc": "

Sets or clears the SO_BROADCAST socket option. When this option is set, UDP packets\nmay be sent to a local interface's broadcast address.\n\n

\n" - }, - { - "textRaw": "dgram.setTTL(ttl)", - "type": "method", - "name": "setTTL", - "signatures": [ - { - "params": [ - { - "textRaw": "`ttl` Integer ", - "name": "ttl", - "desc": "Integer" - } - ] - }, - { - "params": [ - { - "name": "ttl" - } - ] - } - ], - "desc": "

Sets the IP_TTL socket option. TTL stands for "Time to Live," but in this context it\nspecifies the number of IP hops that a packet is allowed to go through. Each router or\ngateway that forwards a packet decrements the TTL. If the TTL is decremented to 0 by a\nrouter, it will not be forwarded. Changing TTL values is typically done for network\nprobes or when multicasting.\n\n

\n

The argument to setTTL() is a number of hops between 1 and 255. The default on most\nsystems is 64.\n\n

\n" - }, - { - "textRaw": "dgram.setMulticastTTL(ttl)", - "type": "method", - "name": "setMulticastTTL", - "signatures": [ - { - "params": [ - { - "textRaw": "`ttl` Integer ", - "name": "ttl", - "desc": "Integer" - } - ] - }, - { - "params": [ - { - "name": "ttl" - } - ] - } - ], - "desc": "

Sets the IP_MULTICAST_TTL socket option. TTL stands for "Time to Live," but in this\ncontext it specifies the number of IP hops that a packet is allowed to go through,\nspecifically for multicast traffic. Each router or gateway that forwards a packet\ndecrements the TTL. If the TTL is decremented to 0 by a router, it will not be forwarded.\n\n

\n

The argument to setMulticastTTL() is a number of hops between 0 and 255. The default on most\nsystems is 64.\n\n

\n" - }, - { - "textRaw": "dgram.setMulticastLoopback(flag)", - "type": "method", - "name": "setMulticastLoopback", - "signatures": [ - { - "params": [ - { - "textRaw": "`flag` Boolean ", - "name": "flag", - "desc": "Boolean" - } - ] - }, - { - "params": [ - { - "name": "flag" - } - ] - } - ], - "desc": "

Sets or clears the IP_MULTICAST_LOOP socket option. When this option is set, multicast\npackets will also be received on the local interface.\n\n

\n" - }, - { - "textRaw": "dgram.addMembership(multicastAddress, [multicastInterface])", - "type": "method", - "name": "addMembership", - "signatures": [ - { - "params": [ - { - "textRaw": "`multicastAddress` String ", - "name": "multicastAddress", - "desc": "String" - }, - { - "textRaw": "`multicastInterface` String, Optional ", - "name": "multicastInterface", - "optional": true, - "desc": "String" - } - ] - }, - { - "params": [ - { - "name": "multicastAddress" - }, - { - "name": "multicastInterface", - "optional": true - } - ] - } - ], - "desc": "

Tells the kernel to join a multicast group with IP_ADD_MEMBERSHIP socket option.\n\n

\n

If multicastInterface is not specified, the OS will try to add membership to all valid\ninterfaces.\n\n

\n" - }, - { - "textRaw": "dgram.dropMembership(multicastAddress, [multicastInterface])", - "type": "method", - "name": "dropMembership", - "signatures": [ - { - "params": [ - { - "textRaw": "`multicastAddress` String ", - "name": "multicastAddress", - "desc": "String" - }, - { - "textRaw": "`multicastInterface` String, Optional ", - "name": "multicastInterface", - "optional": true, - "desc": "String" - } - ] - }, - { - "params": [ - { - "name": "multicastAddress" - }, - { - "name": "multicastInterface", - "optional": true - } - ] - } - ], - "desc": "

Opposite of addMembership - tells the kernel to leave a multicast group with\nIP_DROP_MEMBERSHIP socket option. This is automatically called by the kernel\nwhen the socket is closed or process terminates, so most apps will never need to call\nthis.\n\n

\n

If multicastInterface is not specified, the OS will try to drop membership to all valid\ninterfaces.\n

\n" - } - ] - } - ], - "type": "module", - "displayName": "dgram" - } - ] -} --- a/doc/api/api/dns.html +++ /dev/null @@ -1,235 +0,0 @@ - - - - - DNS Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

DNS#

-
Stability: 3 - Stable
-

Use require('dns') to access this module. All methods in the dns module -use C-Ares except for dns.lookup which uses getaddrinfo(3) in a thread -pool. C-Ares is much faster than getaddrinfo but the system resolver is -more constant with how other programs operate. When a user does -net.connect(80, 'google.com') or http.get({ host: 'google.com' }) the -dns.lookup method is used. Users who need to do a large number of look ups -quickly should use the methods that go through C-Ares. - -

-

Here is an example which resolves 'www.google.com' then reverse -resolves the IP addresses which are returned. - -

-
var dns = require('dns');
-
-dns.resolve4('www.google.com', function (err, addresses) {
-  if (err) throw err;
-
-  console.log('addresses: ' + JSON.stringify(addresses));
-
-  addresses.forEach(function (a) {
-    dns.reverse(a, function (err, domains) {
-      if (err) {
-        console.log('reverse for ' + a + ' failed: ' +
-          err.message);
-      } else {
-        console.log('reverse for ' + a + ': ' +
-          JSON.stringify(domains));
-      }
-    });
-  });
-});
-

dns.lookup(domain, [family], callback)#

-

Resolves a domain (e.g. 'google.com') into the first found A (IPv4) or -AAAA (IPv6) record. -The family can be the integer 4 or 6. Defaults to null that indicates -both Ip v4 and v6 address family. - -

-

The callback has arguments (err, address, family). The address argument -is a string representation of a IP v4 or v6 address. The family argument -is either the integer 4 or 6 and denotes the family of address (not -necessarily the value initially passed to lookup). - - -

-

dns.resolve(domain, [rrtype], callback)#

-

Resolves a domain (e.g. 'google.com') into an array of the record types -specified by rrtype. Valid rrtypes are 'A' (IPV4 addresses, default), -'AAAA' (IPV6 addresses), 'MX' (mail exchange records), 'TXT' (text -records), 'SRV' (SRV records), 'PTR' (used for reverse IP lookups), -'NS' (name server records) and 'CNAME' (canonical name records). - -

-

The callback has arguments (err, addresses). The type of each item -in addresses is determined by the record type, and described in the -documentation for the corresponding lookup methods below. - -

-

On error, err would be an instanceof Error object, where err.errno is -one of the error codes listed below and err.message is a string describing -the error in English. - - -

-

dns.resolve4(domain, callback)#

-

The same as dns.resolve(), but only for IPv4 queries (A records). -addresses is an array of IPv4 addresses (e.g. -['74.125.79.104', '74.125.79.105', '74.125.79.106']). - -

-

dns.resolve6(domain, callback)#

-

The same as dns.resolve4() except for IPv6 queries (an AAAA query). - - -

-

dns.resolveMx(domain, callback)#

-

The same as dns.resolve(), but only for mail exchange queries (MX records). - -

-

addresses is an array of MX records, each with a priority and an exchange -attribute (e.g. [{'priority': 10, 'exchange': 'mx.example.com'},...]). - -

-

dns.resolveTxt(domain, callback)#

-

The same as dns.resolve(), but only for text queries (TXT records). -addresses is an array of the text records available for domain (e.g., -['v=spf1 ip4:0.0.0.0 ~all']). - -

-

dns.resolveSrv(domain, callback)#

-

The same as dns.resolve(), but only for service records (SRV records). -addresses is an array of the SRV records available for domain. Properties -of SRV records are priority, weight, port, and name (e.g., -[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]). - -

-

dns.reverse(ip, callback)#

-

Reverse resolves an ip address to an array of domain names. - -

-

The callback has arguments (err, domains). - -

-

dns.resolveNs(domain, callback)#

-

The same as dns.resolve(), but only for name server records (NS records). -addresses is an array of the name server records available for domain -(e.g., ['ns1.example.com', 'ns2.example.com']). - -

-

dns.resolveCname(domain, callback)#

-

The same as dns.resolve(), but only for canonical name records (CNAME -records). addresses is an array of the canonical name records available for -domain (e.g., ['bar.example.com']). - -

-

If there an an error, err will be non-null and an instanceof the Error -object. - -

-

Each DNS query can return an error code. - -

-
    -
  • dns.TEMPFAIL: timeout, SERVFAIL or similar.
    • -
  • dns.PROTOCOL: got garbled reply.
    • -
  • dns.NXDOMAIN: domain does not exists.
    • -
  • dns.NODATA: domain exists but no data of reqd type.
    • -
  • dns.NOMEM: out of memory while processing.
    • -
  • dns.BADQUERY: the query is malformed.
    • -
- -
-
-
- - - - - - - - - - --- a/doc/api/api/dns.json +++ /dev/null @@ -1,204 +0,0 @@ -{ - "source": "doc/api/dns.markdown", - "modules": [ - { - "textRaw": "DNS", - "name": "dns", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Use require('dns') to access this module. All methods in the dns module\nuse C-Ares except for dns.lookup which uses getaddrinfo(3) in a thread\npool. C-Ares is much faster than getaddrinfo but the system resolver is\nmore constant with how other programs operate. When a user does\nnet.connect(80, 'google.com') or http.get({ host: 'google.com' }) the\ndns.lookup method is used. Users who need to do a large number of look ups\nquickly should use the methods that go through C-Ares.\n\n

\n

Here is an example which resolves 'www.google.com' then reverse\nresolves the IP addresses which are returned.\n\n

\n
var dns = require('dns');\n\ndns.resolve4('www.google.com', function (err, addresses) {\n  if (err) throw err;\n\n  console.log('addresses: ' + JSON.stringify(addresses));\n\n  addresses.forEach(function (a) {\n    dns.reverse(a, function (err, domains) {\n      if (err) {\n        console.log('reverse for ' + a + ' failed: ' +\n          err.message);\n      } else {\n        console.log('reverse for ' + a + ': ' +\n          JSON.stringify(domains));\n      }\n    });\n  });\n});
\n", - "methods": [ - { - "textRaw": "dns.lookup(domain, [family], callback)", - "type": "method", - "name": "lookup", - "desc": "

Resolves a domain (e.g. 'google.com') into the first found A (IPv4) or\nAAAA (IPv6) record.\nThe family can be the integer 4 or 6. Defaults to null that indicates\nboth Ip v4 and v6 address family.\n\n

\n

The callback has arguments (err, address, family). The address argument\nis a string representation of a IP v4 or v6 address. The family argument\nis either the integer 4 or 6 and denotes the family of address (not\nnecessarily the value initially passed to lookup).\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "family", - "optional": true - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolve(domain, [rrtype], callback)", - "type": "method", - "name": "resolve", - "desc": "

Resolves a domain (e.g. 'google.com') into an array of the record types\nspecified by rrtype. Valid rrtypes are 'A' (IPV4 addresses, default),\n'AAAA' (IPV6 addresses), 'MX' (mail exchange records), 'TXT' (text\nrecords), 'SRV' (SRV records), 'PTR' (used for reverse IP lookups),\n'NS' (name server records) and 'CNAME' (canonical name records).\n\n

\n

The callback has arguments (err, addresses). The type of each item\nin addresses is determined by the record type, and described in the\ndocumentation for the corresponding lookup methods below.\n\n

\n

On error, err would be an instanceof Error object, where err.errno is\none of the error codes listed below and err.message is a string describing\nthe error in English.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "rrtype", - "optional": true - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolve4(domain, callback)", - "type": "method", - "name": "resolve4", - "desc": "

The same as dns.resolve(), but only for IPv4 queries (A records).\naddresses is an array of IPv4 addresses (e.g.\n['74.125.79.104', '74.125.79.105', '74.125.79.106']).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolve6(domain, callback)", - "type": "method", - "name": "resolve6", - "desc": "

The same as dns.resolve4() except for IPv6 queries (an AAAA query).\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolveMx(domain, callback)", - "type": "method", - "name": "resolveMx", - "desc": "

The same as dns.resolve(), but only for mail exchange queries (MX records).\n\n

\n

addresses is an array of MX records, each with a priority and an exchange\nattribute (e.g. [{'priority': 10, 'exchange': 'mx.example.com'},...]).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolveTxt(domain, callback)", - "type": "method", - "name": "resolveTxt", - "desc": "

The same as dns.resolve(), but only for text queries (TXT records).\naddresses is an array of the text records available for domain (e.g.,\n['v=spf1 ip4:0.0.0.0 ~all']).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolveSrv(domain, callback)", - "type": "method", - "name": "resolveSrv", - "desc": "

The same as dns.resolve(), but only for service records (SRV records).\naddresses is an array of the SRV records available for domain. Properties\nof SRV records are priority, weight, port, and name (e.g.,\n[{'priority': 10, {'weight': 5, 'port': 21223, 'name': 'service.example.com'}, ...]).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.reverse(ip, callback)", - "type": "method", - "name": "reverse", - "desc": "

Reverse resolves an ip address to an array of domain names.\n\n

\n

The callback has arguments (err, domains).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "ip" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolveNs(domain, callback)", - "type": "method", - "name": "resolveNs", - "desc": "

The same as dns.resolve(), but only for name server records (NS records).\naddresses is an array of the name server records available for domain\n(e.g., ['ns1.example.com', 'ns2.example.com']).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "dns.resolveCname(domain, callback)", - "type": "method", - "name": "resolveCname", - "desc": "

The same as dns.resolve(), but only for canonical name records (CNAME\nrecords). addresses is an array of the canonical name records available for\ndomain (e.g., ['bar.example.com']).\n\n

\n

If there an an error, err will be non-null and an instanceof the Error\nobject.\n\n

\n

Each DNS query can return an error code.\n\n

\n
    \n
  • dns.TEMPFAIL: timeout, SERVFAIL or similar.
    • \n
  • dns.PROTOCOL: got garbled reply.
    • \n
  • dns.NXDOMAIN: domain does not exists.
    • \n
  • dns.NODATA: domain exists but no data of reqd type.
    • \n
  • dns.NOMEM: out of memory while processing.
    • \n
  • dns.BADQUERY: the query is malformed.
    • \n
\n", - "signatures": [ - { - "params": [ - { - "name": "domain" - }, - { - "name": "callback" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "DNS" - } - ] -} --- a/doc/api/api/documentation.html +++ /dev/null @@ -1,172 +0,0 @@ - - - - - About this Documentation Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- -
-

Table of Contents

- - -
- -
-

About this Documentation#

- - -

The goal of this documentation is to comprehensively explain the Node.js -API, both from a reference as well as a conceptual point of view. Each -section describes a built-in module or high-level concept. - -

-

Where appropriate, property types, method arguments, and the arguments -provided to event handlers are detailed in a list underneath the topic -heading. - -

-

Every .html document has a corresponding .json document presenting -the same information in a structured manner. This feature is -experimental, and added for the benefit of IDEs and other utilities that -wish to do programmatic things with the documentation. - -

-

Every .html and .json file is generated based on the corresponding -.markdown file in the doc/api/ folder in node's source tree. The -documentation is generated using the tools/doc/generate.js program. -The HTML template is located at doc/template.html. - -

-

Stability Index#

- - -

Throughout the documentation, you will see indications of a section's -stability. The Node.js API is still somewhat changing, and as it -matures, certain parts are more reliable than others. Some are so -proven, and so relied upon, that they are unlikely to ever change at -all. Others are brand new and experimental, or known to be hazardous -and in the process of being redesigned. - -

-

The notices look like this: - -

-
Stability: 1 Experimental
-

The stability indices are as follows: - -

-
    -
  • 0 - Deprecated This feature is known to be problematic, and changes are -planned. Do not rely on it. Use of the feature may cause warnings. Backwards -compatibility should not be expected.
    • -
-
    -
  • 1 - Experimental This feature was introduced recently, and may change -or be removed in future versions. Please try it out and provide feedback. -If it addresses a use-case that is important to you, tell the node core team.
    • -
-
    -
  • 2 - Unstable The API is in the process of settling, but has not yet had -sufficient real-world testing to be considered stable. Backwards-compatibility -will be maintained if reasonable.
    • -
-
    -
  • 3 - Stable The API has proven satisfactory, but cleanup in the underlying -code may cause minor changes. Backwards-compatibility is guaranteed.
    • -
-
    -
  • 4 - API Frozen This API has been tested extensively in production and is -unlikely to ever have to change.
    • -
-
    -
  • 5 - Locked Unless serious bugs are found, this code will not ever -change. Please do not suggest changes in this area; they will be refused.
    • -
-

JSON Output#

-
Stability: 1 - Experimental
-

Every HTML file in the markdown has a corresponding JSON file with the -same data. - -

-

This feature is new as of node v0.6.12. It is experimental. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/documentation.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "source": "doc/api/documentation.markdown", - "miscs": [ - { - "textRaw": "About this Documentation", - "name": "About this Documentation", - "type": "misc", - "desc": "

The goal of this documentation is to comprehensively explain the Node.js\nAPI, both from a reference as well as a conceptual point of view. Each\nsection describes a built-in module or high-level concept.\n\n

\n

Where appropriate, property types, method arguments, and the arguments\nprovided to event handlers are detailed in a list underneath the topic\nheading.\n\n

\n

Every .html document has a corresponding .json document presenting\nthe same information in a structured manner. This feature is\nexperimental, and added for the benefit of IDEs and other utilities that\nwish to do programmatic things with the documentation.\n\n

\n

Every .html and .json file is generated based on the corresponding\n.markdown file in the doc/api/ folder in node's source tree. The\ndocumentation is generated using the tools/doc/generate.js program.\nThe HTML template is located at doc/template.html.\n\n

\n", - "miscs": [ - { - "textRaw": "Stability Index", - "name": "Stability Index", - "type": "misc", - "desc": "

Throughout the documentation, you will see indications of a section's\nstability. The Node.js API is still somewhat changing, and as it\nmatures, certain parts are more reliable than others. Some are so\nproven, and so relied upon, that they are unlikely to ever change at\nall. Others are brand new and experimental, or known to be hazardous\nand in the process of being redesigned.\n\n

\n

The notices look like this:\n\n

\n
Stability: 1 Experimental
\n

The stability indices are as follows:\n\n

\n
    \n
  • 0 - Deprecated This feature is known to be problematic, and changes are\nplanned. Do not rely on it. Use of the feature may cause warnings. Backwards\ncompatibility should not be expected.
    • \n
\n
    \n
  • 1 - Experimental This feature was introduced recently, and may change\nor be removed in future versions. Please try it out and provide feedback.\nIf it addresses a use-case that is important to you, tell the node core team.
    • \n
\n
    \n
  • 2 - Unstable The API is in the process of settling, but has not yet had\nsufficient real-world testing to be considered stable. Backwards-compatibility\nwill be maintained if reasonable.
    • \n
\n
    \n
  • 3 - Stable The API has proven satisfactory, but cleanup in the underlying\ncode may cause minor changes. Backwards-compatibility is guaranteed.
    • \n
\n
    \n
  • 4 - API Frozen This API has been tested extensively in production and is\nunlikely to ever have to change.
    • \n
\n
    \n
  • 5 - Locked Unless serious bugs are found, this code will not ever\nchange. Please do not suggest changes in this area; they will be refused.
    • \n
\n" - }, - { - "textRaw": "JSON Output", - "name": "json_output", - "stability": 1, - "stabilityText": "Experimental", - "desc": "

Every HTML file in the markdown has a corresponding JSON file with the\nsame data.\n\n

\n

This feature is new as of node v0.6.12. It is experimental.\n

\n", - "type": "misc", - "displayName": "JSON Output" - } - ] - } - ] -} --- a/doc/api/api/events.html +++ /dev/null @@ -1,198 +0,0 @@ - - - - - Events Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Events#

-
Stability: 4 - API Frozen
- - -

Many objects in Node emit events: a net.Server emits an event each time -a peer connects to it, a fs.readStream emits an event when the file is -opened. All objects which emit events are instances of events.EventEmitter. -You can access this module by doing: require("events"); - -

-

Typically, event names are represented by a camel-cased string, however, -there aren't any strict restrictions on that, as any string will be accepted. - -

-

Functions can then be attached to objects, to be executed when an event -is emitted. These functions are called listeners. - - -

-

Class: events.EventEmitter#

-

To access the EventEmitter class, require('events').EventEmitter. - -

-

When an EventEmitter instance experiences an error, the typical action is -to emit an 'error' event. Error events are treated as a special case in node. -If there is no listener for it, then the default action is to print a stack -trace and exit the program. - -

-

All EventEmitters emit the event 'newListener' when new listeners are -added. - -

-

emitter.addListener(event, listener)#

-

emitter.on(event, listener)#

-

Adds a listener to the end of the listeners array for the specified event. - -

-
server.on('connection', function (stream) {
-  console.log('someone connected!');
-});
-

emitter.once(event, listener)#

-

Adds a one time listener for the event. This listener is -invoked only the next time the event is fired, after which -it is removed. - -

-
server.once('connection', function (stream) {
-  console.log('Ah, we have our first user!');
-});
-

emitter.removeListener(event, listener)#

-

Remove a listener from the listener array for the specified event. -Caution: changes array indices in the listener array behind the listener. - -

-
var callback = function(stream) {
-  console.log('someone connected!');
-};
-server.on('connection', callback);
-// ...
-server.removeListener('connection', callback);
-

emitter.removeAllListeners([event])#

-

Removes all listeners, or those of the specified event. - - -

-

emitter.setMaxListeners(n)#

-

By default EventEmitters will print a warning if more than 10 listeners are -added for a particular event. This is a useful default which helps finding memory leaks. -Obviously not all Emitters should be limited to 10. This function allows -that to be increased. Set to zero for unlimited. - - -

-

emitter.listeners(event)#

-

Returns an array of listeners for the specified event. This array can be -manipulated, e.g. to remove listeners. - -

-
server.on('connection', function (stream) {
-  console.log('someone connected!');
-});
-console.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
-

emitter.emit(event, [arg1], [arg2], [...])#

-

Execute each of the listeners in order with the supplied arguments. - -

-

Event: 'newListener'#

-
    -
  • event String The event name
    • -
  • listener Function The event handler function
    • -
-

This event is emitted any time someone adds a new listener. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/events.json +++ /dev/null @@ -1,187 +0,0 @@ -{ - "source": "doc/api/events.markdown", - "modules": [ - { - "textRaw": "Events", - "name": "Events", - "stability": 4, - "stabilityText": "API Frozen", - "type": "module", - "desc": "

Many objects in Node emit events: a net.Server emits an event each time\na peer connects to it, a fs.readStream emits an event when the file is\nopened. All objects which emit events are instances of events.EventEmitter.\nYou can access this module by doing: require("events");\n\n

\n

Typically, event names are represented by a camel-cased string, however,\nthere aren't any strict restrictions on that, as any string will be accepted.\n\n

\n

Functions can then be attached to objects, to be executed when an event\nis emitted. These functions are called listeners.\n\n\n

\n", - "classes": [ - { - "textRaw": "Class: events.EventEmitter", - "type": "class", - "name": "events.EventEmitter", - "desc": "

To access the EventEmitter class, require('events').EventEmitter.\n\n

\n

When an EventEmitter instance experiences an error, the typical action is\nto emit an 'error' event. Error events are treated as a special case in node.\nIf there is no listener for it, then the default action is to print a stack\ntrace and exit the program.\n\n

\n

All EventEmitters emit the event 'newListener' when new listeners are\nadded.\n\n

\n", - "methods": [ - { - "textRaw": "emitter.addListener(event, listener)", - "type": "method", - "name": "addListener", - "desc": "

Adds a listener to the end of the listeners array for the specified event.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "event" - }, - { - "name": "listener" - } - ] - }, - { - "params": [ - { - "name": "event" - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "emitter.on(event, listener)", - "type": "method", - "name": "on", - "desc": "

Adds a listener to the end of the listeners array for the specified event.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "event" - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "emitter.once(event, listener)", - "type": "method", - "name": "once", - "desc": "

Adds a one time listener for the event. This listener is\ninvoked only the next time the event is fired, after which\nit is removed.\n\n

\n
server.once('connection', function (stream) {\n  console.log('Ah, we have our first user!');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "event" - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "emitter.removeListener(event, listener)", - "type": "method", - "name": "removeListener", - "desc": "

Remove a listener from the listener array for the specified event.\nCaution: changes array indices in the listener array behind the listener.\n\n

\n
var callback = function(stream) {\n  console.log('someone connected!');\n};\nserver.on('connection', callback);\n// ...\nserver.removeListener('connection', callback);
\n", - "signatures": [ - { - "params": [ - { - "name": "event" - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "emitter.removeAllListeners([event])", - "type": "method", - "name": "removeAllListeners", - "desc": "

Removes all listeners, or those of the specified event.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "event", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "emitter.setMaxListeners(n)", - "type": "method", - "name": "setMaxListeners", - "desc": "

By default EventEmitters will print a warning if more than 10 listeners are\nadded for a particular event. This is a useful default which helps finding memory leaks.\nObviously not all Emitters should be limited to 10. This function allows\nthat to be increased. Set to zero for unlimited.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "n" - } - ] - } - ] - }, - { - "textRaw": "emitter.listeners(event)", - "type": "method", - "name": "listeners", - "desc": "

Returns an array of listeners for the specified event. This array can be\nmanipulated, e.g. to remove listeners.\n\n

\n
server.on('connection', function (stream) {\n  console.log('someone connected!');\n});\nconsole.log(util.inspect(server.listeners('connection'))); // [ [Function] ]
\n", - "signatures": [ - { - "params": [ - { - "name": "event" - } - ] - } - ] - }, - { - "textRaw": "emitter.emit(event, [arg1], [arg2], [...])", - "type": "method", - "name": "emit", - "desc": "

Execute each of the listeners in order with the supplied arguments.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "event" - }, - { - "name": "arg1", - "optional": true - }, - { - "name": "arg2", - "optional": true - }, - { - "name": "...", - "optional": true - } - ] - } - ] - } - ], - "events": [ - { - "textRaw": "Event: 'newListener'", - "type": "event", - "name": "newListener", - "params": [], - "desc": "

This event is emitted any time someone adds a new listener.\n

\n" - } - ] - } - ] - } - ] -} --- a/doc/api/api/fs.html +++ /dev/null @@ -1,815 +0,0 @@ - - - - - File System Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- -
-

Table of Contents

- - -
- -
-

File System#

-
Stability: 3 - Stable
- - -

File I/O is provided by simple wrappers around standard POSIX functions. To -use this module do require('fs'). All the methods have asynchronous and -synchronous forms. - -

-

The asynchronous form always take a completion callback as its last argument. -The arguments passed to the completion callback depend on the method, but the -first argument is always reserved for an exception. If the operation was -completed successfully, then the first argument will be null or undefined. - -

-

When using the synchronous form any exceptions are immediately thrown. -You can use try/catch to handle exceptions or allow them to bubble up. - -

-

Here is an example of the asynchronous version: - -

-
var fs = require('fs');
-
-fs.unlink('/tmp/hello', function (err) {
-  if (err) throw err;
-  console.log('successfully deleted /tmp/hello');
-});
-

Here is the synchronous version: - -

-
var fs = require('fs');
-
-fs.unlinkSync('/tmp/hello')
-console.log('successfully deleted /tmp/hello');
-

With the asynchronous methods there is no guaranteed ordering. So the -following is prone to error: - -

-
fs.rename('/tmp/hello', '/tmp/world', function (err) {
-  if (err) throw err;
-  console.log('renamed complete');
-});
-fs.stat('/tmp/world', function (err, stats) {
-  if (err) throw err;
-  console.log('stats: ' + JSON.stringify(stats));
-});
-

It could be that fs.stat is executed before fs.rename. -The correct way to do this is to chain the callbacks. - -

-
fs.rename('/tmp/hello', '/tmp/world', function (err) {
-  if (err) throw err;
-  fs.stat('/tmp/world', function (err, stats) {
-    if (err) throw err;
-    console.log('stats: ' + JSON.stringify(stats));
-  });
-});
-

In busy processes, the programmer is strongly encouraged to use the -asynchronous versions of these calls. The synchronous versions will block -the entire process until they complete--halting all connections. - -

-

Relative path to filename can be used, remember however that this path will be relative -to process.cwd(). - -

-

fs.rename(path1, path2, [callback])#

-

Asynchronous rename(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.renameSync(path1, path2)#

-

Synchronous rename(2). - -

-

fs.truncate(fd, len, [callback])#

-

Asynchronous ftruncate(2). No arguments other than a possible exception are -given to the completion callback. - -

-

fs.truncateSync(fd, len)#

-

Synchronous ftruncate(2). - -

-

fs.chown(path, uid, gid, [callback])#

-

Asynchronous chown(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.chownSync(path, uid, gid)#

-

Synchronous chown(2). - -

-

fs.fchown(fd, uid, gid, [callback])#

-

Asynchronous fchown(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.fchownSync(fd, uid, gid)#

-

Synchronous fchown(2). - -

-

fs.lchown(path, uid, gid, [callback])#

-

Asynchronous lchown(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.lchownSync(path, uid, gid)#

-

Synchronous lchown(2). - -

-

fs.chmod(path, mode, [callback])#

-

Asynchronous chmod(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.chmodSync(path, mode)#

-

Synchronous chmod(2). - -

-

fs.fchmod(fd, mode, [callback])#

-

Asynchronous fchmod(2). No arguments other than a possible exception -are given to the completion callback. - -

-

fs.fchmodSync(fd, mode)#

-

Synchronous fchmod(2). - -

-

fs.lchmod(path, mode, [callback])#

-

Asynchronous lchmod(2). No arguments other than a possible exception -are given to the completion callback. - -

-

fs.lchmodSync(path, mode)#

-

Synchronous lchmod(2). - -

-

fs.stat(path, [callback])#

-

Asynchronous stat(2). The callback gets two arguments (err, stats) where -stats is a fs.Stats object. See the fs.Stats -section below for more information. - -

-

fs.lstat(path, [callback])#

-

Asynchronous lstat(2). The callback gets two arguments (err, stats) where -stats is a fs.Stats object. lstat() is identical to stat(), except that if -path is a symbolic link, then the link itself is stat-ed, not the file that it -refers to. - -

-

fs.fstat(fd, [callback])#

-

Asynchronous fstat(2). The callback gets two arguments (err, stats) where -stats is a fs.Stats object. fstat() is identical to stat(), except that -the file to be stat-ed is specified by the file descriptor fd. - -

-

fs.statSync(path)#

-

Synchronous stat(2). Returns an instance of fs.Stats. - -

-

fs.lstatSync(path)#

-

Synchronous lstat(2). Returns an instance of fs.Stats. - -

-

fs.fstatSync(fd)#

-

Synchronous fstat(2). Returns an instance of fs.Stats. - -

-

fs.link(srcpath, dstpath, [callback])#

-

Asynchronous link(2). No arguments other than a possible exception are given to -the completion callback. - -

-

fs.linkSync(srcpath, dstpath)#

-

Synchronous link(2). - -

-

fs.symlink(linkdata, path, [type], [callback])#

-

Asynchronous symlink(2). No arguments other than a possible exception are given -to the completion callback. -type argument can be either 'dir' or 'file' (default is 'file'). It is only -used on Windows (ignored on other platforms). - -

-

fs.symlinkSync(linkdata, path, [type])#

-

Synchronous symlink(2). - -

-

fs.readlink(path, [callback])#

-

Asynchronous readlink(2). The callback gets two arguments (err, -linkString). - -

-

fs.readlinkSync(path)#

-

Synchronous readlink(2). Returns the symbolic link's string value. - -

-

fs.realpath(path, [callback])#

-

Asynchronous realpath(2). The callback gets two arguments (err, -resolvedPath). May use process.cwd to resolve relative paths. - -

-

fs.realpathSync(path)#

-

Synchronous realpath(2). Returns the resolved path. - -

-

fs.unlink(path, [callback])#

-

Asynchronous unlink(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.unlinkSync(path)#

-

Synchronous unlink(2). - -

-

fs.rmdir(path, [callback])#

-

Asynchronous rmdir(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.rmdirSync(path)#

-

Synchronous rmdir(2). - -

-

fs.mkdir(path, [mode], [callback])#

-

Asynchronous mkdir(2). No arguments other than a possible exception are given -to the completion callback. mode defaults to 0777. - -

-

fs.mkdirSync(path, [mode])#

-

Synchronous mkdir(2). - -

-

fs.readdir(path, [callback])#

-

Asynchronous readdir(3). Reads the contents of a directory. -The callback gets two arguments (err, files) where files is an array of -the names of the files in the directory excluding '.' and '..'. - -

-

fs.readdirSync(path)#

-

Synchronous readdir(3). Returns an array of filenames excluding '.' and -'..'. - -

-

fs.close(fd, [callback])#

-

Asynchronous close(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.closeSync(fd)#

-

Synchronous close(2). - -

-

fs.open(path, flags, [mode], [callback])#

-

Asynchronous file open. See open(2). flags can be: - -

-
    -

  • 'r' - Open file for reading. -An exception occurs if the file does not exist.

    -
    • -

  • 'r+' - Open file for reading and writing. -An exception occurs if the file does not exist.

    -
    • -

  • 'w' - Open file for writing. -The file is created (if it does not exist) or truncated (if it exists).

    -
    • -

  • 'w+' - Open file for reading and writing. -The file is created (if it does not exist) or truncated (if it exists).

    -
    • -

  • 'a' - Open file for appending. -The file is created if it does not exist.

    -
    • -

  • 'a+' - Open file for reading and appending. -The file is created if it does not exist.

    -
    • -
-

mode defaults to 0666. The callback gets two arguments (err, fd). - -

-

fs.openSync(path, flags, [mode])#

-

Synchronous open(2). - -

-

fs.utimes(path, atime, mtime, [callback])#

-

fs.utimesSync(path, atime, mtime)#

-

Change file timestamps of the file referenced by the supplied path. - -

-

fs.futimes(fd, atime, mtime, [callback])#

-

fs.futimesSync(fd, atime, mtime)#

-

Change the file timestamps of a file referenced by the supplied file -descriptor. - -

-

fs.fsync(fd, [callback])#

-

Asynchronous fsync(2). No arguments other than a possible exception are given -to the completion callback. - -

-

fs.fsyncSync(fd)#

-

Synchronous fsync(2). - -

-

fs.write(fd, buffer, offset, length, position, [callback])#

-

Write buffer to the file specified by fd. - -

-

offset and length determine the part of the buffer to be written. - -

-

position refers to the offset from the beginning of the file where this data -should be written. If position is null, the data will be written at the -current position. -See pwrite(2). - -

-

The callback will be given three arguments (err, written, buffer) where written -specifies how many bytes were written from buffer. - -

-

Note that it is unsafe to use fs.write multiple times on the same file -without waiting for the callback. For this scenario, -fs.createWriteStream is strongly recommended. - -

-

fs.writeSync(fd, buffer, offset, length, position)#

-

Synchronous version of buffer-based fs.write(). Returns the number of bytes -written. - -

-

fs.writeSync(fd, str, position, [encoding])#

-

Synchronous version of string-based fs.write(). encoding defaults to -'utf8'. Returns the number of bytes written. - -

-

fs.read(fd, buffer, offset, length, position, [callback])#

-

Read data from the file specified by fd. - -

-

buffer is the buffer that the data will be written to. - -

-

offset is offset within the buffer where writing will start. - -

-

length is an integer specifying the number of bytes to read. - -

-

position is an integer specifying where to begin reading from in the file. -If position is null, data will be read from the current file position. - -

-

The callback is given the three arguments, (err, bytesRead, buffer). - -

-

fs.readSync(fd, buffer, offset, length, position)#

-

Synchronous version of buffer-based fs.read. Returns the number of -bytesRead. - -

-

fs.readSync(fd, length, position, encoding)#

-

Synchronous version of string-based fs.read. Returns the number of -bytesRead. - -

-

fs.readFile(filename, [encoding], [callback])#

-

Asynchronously reads the entire contents of a file. Example: - -

-
fs.readFile('/etc/passwd', function (err, data) {
-  if (err) throw err;
-  console.log(data);
-});
-

The callback is passed two arguments (err, data), where data is the -contents of the file. - -

-

If no encoding is specified, then the raw buffer is returned. - - -

-

fs.readFileSync(filename, [encoding])#

-

Synchronous version of fs.readFile. Returns the contents of the filename. - -

-

If encoding is specified then this function returns a string. Otherwise it -returns a buffer. - - -

-

fs.writeFile(filename, data, [encoding], [callback])#

-

Asynchronously writes data to a file, replacing the file if it already exists. -data can be a string or a buffer. The encoding argument is ignored if -data is a buffer. It defaults to 'utf8'. - -

-

Example: - -

-
fs.writeFile('message.txt', 'Hello Node', function (err) {
-  if (err) throw err;
-  console.log('It\'s saved!');
-});
-

fs.writeFileSync(filename, data, [encoding])#

-

The synchronous version of fs.writeFile. - -

-

fs.watchFile(filename, [options], listener)#

-
Stability: 2 - Unstable.  Use fs.watch instead, if available.
-

Watch for changes on filename. The callback listener will be called each -time the file is accessed. - -

-

The second argument is optional. The options if provided should be an object -containing two members a boolean, persistent, and interval. persistent -indicates whether the process should continue to run as long as files are -being watched. interval indicates how often the target should be polled, -in milliseconds. (On Linux systems with inotify, interval is ignored.) The -default is { persistent: true, interval: 0 }. - -

-

The listener gets two arguments the current stat object and the previous -stat object: - -

-
fs.watchFile('message.text', function (curr, prev) {
-  console.log('the current mtime is: ' + curr.mtime);
-  console.log('the previous mtime was: ' + prev.mtime);
-});
-

These stat objects are instances of fs.Stat. - -

-

If you want to be notified when the file was modified, not just accessed -you need to compare curr.mtime and prev.mtime. - - -

-

fs.unwatchFile(filename)#

-
Stability: 2 - Unstable.  Use fs.watch instead, if available.
-

Stop watching for changes on filename. - -

-

fs.watch(filename, [options], listener)#

-
Stability: 2 - Unstable.  Not available on all platforms.
-

Watch for changes on filename, where filename is either a file or a -directory. The returned object is a fs.FSWatcher. - -

-

The second argument is optional. The options if provided should be an object -containing a boolean member persistent, which indicates whether the process -should continue to run as long as files are being watched. The default is -{ persistent: true }. - -

-

The listener callback gets two arguments (event, filename). event is either -'rename' or 'change', and filename is the name of the file which triggered -the event. - -

-

Caveats#

- - -

The fs.watch API is not 100% consistent across platforms, and is -unavailable in some situations. - -

-

Availability#

- - -

This feature depends on the underlying operating system providing a way -to be notified of filesystem changes. - -

-
    -
  • On Linux systems, this uses inotify.
    • -
  • On BSD systems (including OS X), this uses kqueue.
    • -
  • On SunOS systems (including Solaris and SmartOS), this uses event ports.
    • -
  • On Windows systems, this feature depends on ReadDirectoryChangesW.
    • -
-

If the underlying functionality is not available for some reason, then -fs.watch will not be able to function. You can still use -fs.watchFile, which uses stat polling, but it is slower and less -reliable. - -

-

Filename Argument#

- - -

Providing filename argument in the callback is not supported -on every platform (currently it's only supported on Linux and Windows). Even -on supported platforms filename is not always guaranteed to be provided. -Therefore, don't assume that filename argument is always provided in the -callback, and have some fallback logic if it is null. - -

-
fs.watch('somedir', function (event, filename) {
-  console.log('event is: ' + event);
-  if (filename) {
-    console.log('filename provided: ' + filename);
-  } else {
-    console.log('filename not provided');
-  }
-});
-

Class: fs.Stats#

-

Objects returned from fs.stat(), fs.lstat() and fs.fstat() and their -synchronous counterparts are of this type. - -

-
    -
  • stats.isFile()
    • -
  • stats.isDirectory()
    • -
  • stats.isBlockDevice()
    • -
  • stats.isCharacterDevice()
    • -
  • stats.isSymbolicLink() (only valid with fs.lstat())
    • -
  • stats.isFIFO()
    • -
  • stats.isSocket()
    • -
-

For a regular file util.inspect(stats) would return a string very -similar to this: - -

-
{ dev: 2114,
-  ino: 48064969,
-  mode: 33188,
-  nlink: 1,
-  uid: 85,
-  gid: 100,
-  rdev: 0,
-  size: 527,
-  blksize: 4096,
-  blocks: 8,
-  atime: Mon, 10 Oct 2011 23:24:11 GMT,
-  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
-  ctime: Mon, 10 Oct 2011 23:24:11 GMT }
-

Please note that atime, mtime and ctime are instances -of Date object and to compare the values of -these objects you should use appropriate methods. For most -general uses getTime() will return -the number of milliseconds elapsed since 1 January 1970 -00:00:00 UTC and this integer should be sufficient for -any comparison, however there additional methods which can -be used for displaying fuzzy information. More details can -be found in the MDN JavaScript Reference page. - -

-

fs.createReadStream(path, [options])#

-

Returns a new ReadStream object (See Readable Stream). - -

-

options is an object with the following defaults: - -

-
{ flags: 'r',
-  encoding: null,
-  fd: null,
-  mode: 0666,
-  bufferSize: 64 * 1024
-}
-

options can include start and end values to read a range of bytes from -the file instead of the entire file. Both start and end are inclusive and -start at 0. - -

-

An example to read the last 10 bytes of a file which is 100 bytes long: - -

-
fs.createReadStream('sample.txt', {start: 90, end: 99});
-

Class: fs.ReadStream#

-

ReadStream is a Readable Stream. - -

-

Event: 'open'#

-
    -
  • fd Integer file descriptor used by the ReadStream.
    • -
-

Emitted when the ReadStream's file is opened. - - -

-

fs.createWriteStream(path, [options])#

-

Returns a new WriteStream object (See Writable Stream). - -

-

options is an object with the following defaults: - -

-
{ flags: 'w',
-  encoding: null,
-  mode: 0666 }
-

options may also include a start option to allow writing data at -some position past the beginning of the file. Modifying a file rather -than replacing it may require a flags mode of r+ rather than the -default mode w. - -

-

fs.WriteStream#

-

WriteStream is a Writable Stream. - -

-

Event: 'open'#

-
    -
  • fd Integer file descriptor used by the ReadStream.
    • -
-

Emitted when the WriteStream's file is opened. - -

-

file.bytesWritten#

-

The number of bytes written so far. Does not include data that is still queued -for writing. - -

-

Class: fs.FSWatcher#

-

Objects returned from fs.watch() are of this type. - -

-

watcher.close()#

-

Stop watching for changes on the given fs.FSWatcher. - -

-

Event: 'change'#

-
    -
  • event String The type of fs change
    • -
  • filename String The filename that changed (if relevant/available)
    • -
-

Emitted when something changes in a watched directory or file. -See more details in fs.watch. - -

-

Event: 'error'#

-
    -
  • error Error object
    • -
-

Emitted when an error occurs. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/fs.json +++ /dev/null @@ -1,1451 +0,0 @@ -{ - "source": "doc/api/fs.markdown", - "modules": [ - { - "textRaw": "File System", - "name": "fs", - "stability": 3, - "stabilityText": "Stable", - "desc": "

File I/O is provided by simple wrappers around standard POSIX functions. To\nuse this module do require('fs'). All the methods have asynchronous and\nsynchronous forms.\n\n

\n

The asynchronous form always take a completion callback as its last argument.\nThe arguments passed to the completion callback depend on the method, but the\nfirst argument is always reserved for an exception. If the operation was\ncompleted successfully, then the first argument will be null or undefined.\n\n

\n

When using the synchronous form any exceptions are immediately thrown.\nYou can use try/catch to handle exceptions or allow them to bubble up.\n\n

\n

Here is an example of the asynchronous version:\n\n

\n
var fs = require('fs');\n\nfs.unlink('/tmp/hello', function (err) {\n  if (err) throw err;\n  console.log('successfully deleted /tmp/hello');\n});
\n

Here is the synchronous version:\n\n

\n
var fs = require('fs');\n\nfs.unlinkSync('/tmp/hello')\nconsole.log('successfully deleted /tmp/hello');
\n

With the asynchronous methods there is no guaranteed ordering. So the\nfollowing is prone to error:\n\n

\n
fs.rename('/tmp/hello', '/tmp/world', function (err) {\n  if (err) throw err;\n  console.log('renamed complete');\n});\nfs.stat('/tmp/world', function (err, stats) {\n  if (err) throw err;\n  console.log('stats: ' + JSON.stringify(stats));\n});
\n

It could be that fs.stat is executed before fs.rename.\nThe correct way to do this is to chain the callbacks.\n\n

\n
fs.rename('/tmp/hello', '/tmp/world', function (err) {\n  if (err) throw err;\n  fs.stat('/tmp/world', function (err, stats) {\n    if (err) throw err;\n    console.log('stats: ' + JSON.stringify(stats));\n  });\n});
\n

In busy processes, the programmer is strongly encouraged to use the\nasynchronous versions of these calls. The synchronous versions will block\nthe entire process until they complete--halting all connections.\n\n

\n

Relative path to filename can be used, remember however that this path will be relative\nto process.cwd().\n\n

\n", - "methods": [ - { - "textRaw": "fs.rename(path1, path2, [callback])", - "type": "method", - "name": "rename", - "desc": "

Asynchronous rename(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path1" - }, - { - "name": "path2" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.renameSync(path1, path2)", - "type": "method", - "name": "renameSync", - "desc": "

Synchronous rename(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path1" - }, - { - "name": "path2" - } - ] - } - ] - }, - { - "textRaw": "fs.truncate(fd, len, [callback])", - "type": "method", - "name": "truncate", - "desc": "

Asynchronous ftruncate(2). No arguments other than a possible exception are\ngiven to the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "len" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.truncateSync(fd, len)", - "type": "method", - "name": "truncateSync", - "desc": "

Synchronous ftruncate(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "len" - } - ] - } - ] - }, - { - "textRaw": "fs.chown(path, uid, gid, [callback])", - "type": "method", - "name": "chown", - "desc": "

Asynchronous chown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "uid" - }, - { - "name": "gid" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.chownSync(path, uid, gid)", - "type": "method", - "name": "chownSync", - "desc": "

Synchronous chown(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "uid" - }, - { - "name": "gid" - } - ] - } - ] - }, - { - "textRaw": "fs.fchown(fd, uid, gid, [callback])", - "type": "method", - "name": "fchown", - "desc": "

Asynchronous fchown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "uid" - }, - { - "name": "gid" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.fchownSync(fd, uid, gid)", - "type": "method", - "name": "fchownSync", - "desc": "

Synchronous fchown(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "uid" - }, - { - "name": "gid" - } - ] - } - ] - }, - { - "textRaw": "fs.lchown(path, uid, gid, [callback])", - "type": "method", - "name": "lchown", - "desc": "

Asynchronous lchown(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "uid" - }, - { - "name": "gid" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.lchownSync(path, uid, gid)", - "type": "method", - "name": "lchownSync", - "desc": "

Synchronous lchown(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "uid" - }, - { - "name": "gid" - } - ] - } - ] - }, - { - "textRaw": "fs.chmod(path, mode, [callback])", - "type": "method", - "name": "chmod", - "desc": "

Asynchronous chmod(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.chmodSync(path, mode)", - "type": "method", - "name": "chmodSync", - "desc": "

Synchronous chmod(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode" - } - ] - } - ] - }, - { - "textRaw": "fs.fchmod(fd, mode, [callback])", - "type": "method", - "name": "fchmod", - "desc": "

Asynchronous fchmod(2). No arguments other than a possible exception\nare given to the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "mode" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.fchmodSync(fd, mode)", - "type": "method", - "name": "fchmodSync", - "desc": "

Synchronous fchmod(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "mode" - } - ] - } - ] - }, - { - "textRaw": "fs.lchmod(path, mode, [callback])", - "type": "method", - "name": "lchmod", - "desc": "

Asynchronous lchmod(2). No arguments other than a possible exception\nare given to the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.lchmodSync(path, mode)", - "type": "method", - "name": "lchmodSync", - "desc": "

Synchronous lchmod(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode" - } - ] - } - ] - }, - { - "textRaw": "fs.stat(path, [callback])", - "type": "method", - "name": "stat", - "desc": "

Asynchronous stat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. See the fs.Stats\nsection below for more information.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.lstat(path, [callback])", - "type": "method", - "name": "lstat", - "desc": "

Asynchronous lstat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. lstat() is identical to stat(), except that if\npath is a symbolic link, then the link itself is stat-ed, not the file that it\nrefers to.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.fstat(fd, [callback])", - "type": "method", - "name": "fstat", - "desc": "

Asynchronous fstat(2). The callback gets two arguments (err, stats) where\nstats is a fs.Stats object. fstat() is identical to stat(), except that\nthe file to be stat-ed is specified by the file descriptor fd.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.statSync(path)", - "type": "method", - "name": "statSync", - "desc": "

Synchronous stat(2). Returns an instance of fs.Stats.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.lstatSync(path)", - "type": "method", - "name": "lstatSync", - "desc": "

Synchronous lstat(2). Returns an instance of fs.Stats.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.fstatSync(fd)", - "type": "method", - "name": "fstatSync", - "desc": "

Synchronous fstat(2). Returns an instance of fs.Stats.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - } - ] - } - ] - }, - { - "textRaw": "fs.link(srcpath, dstpath, [callback])", - "type": "method", - "name": "link", - "desc": "

Asynchronous link(2). No arguments other than a possible exception are given to\nthe completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "srcpath" - }, - { - "name": "dstpath" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.linkSync(srcpath, dstpath)", - "type": "method", - "name": "linkSync", - "desc": "

Synchronous link(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "srcpath" - }, - { - "name": "dstpath" - } - ] - } - ] - }, - { - "textRaw": "fs.symlink(linkdata, path, [type], [callback])", - "type": "method", - "name": "symlink", - "desc": "

Asynchronous symlink(2). No arguments other than a possible exception are given\nto the completion callback.\ntype argument can be either 'dir' or 'file' (default is 'file'). It is only \nused on Windows (ignored on other platforms).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "linkdata" - }, - { - "name": "path" - }, - { - "name": "type", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.symlinkSync(linkdata, path, [type])", - "type": "method", - "name": "symlinkSync", - "desc": "

Synchronous symlink(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "linkdata" - }, - { - "name": "path" - }, - { - "name": "type", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readlink(path, [callback])", - "type": "method", - "name": "readlink", - "desc": "

Asynchronous readlink(2). The callback gets two arguments (err,\nlinkString).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readlinkSync(path)", - "type": "method", - "name": "readlinkSync", - "desc": "

Synchronous readlink(2). Returns the symbolic link's string value.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.realpath(path, [callback])", - "type": "method", - "name": "realpath", - "desc": "

Asynchronous realpath(2). The callback gets two arguments (err,\nresolvedPath). May use process.cwd to resolve relative paths.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.realpathSync(path)", - "type": "method", - "name": "realpathSync", - "desc": "

Synchronous realpath(2). Returns the resolved path.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.unlink(path, [callback])", - "type": "method", - "name": "unlink", - "desc": "

Asynchronous unlink(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.unlinkSync(path)", - "type": "method", - "name": "unlinkSync", - "desc": "

Synchronous unlink(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.rmdir(path, [callback])", - "type": "method", - "name": "rmdir", - "desc": "

Asynchronous rmdir(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.rmdirSync(path)", - "type": "method", - "name": "rmdirSync", - "desc": "

Synchronous rmdir(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.mkdir(path, [mode], [callback])", - "type": "method", - "name": "mkdir", - "desc": "

Asynchronous mkdir(2). No arguments other than a possible exception are given\nto the completion callback. mode defaults to 0777.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.mkdirSync(path, [mode])", - "type": "method", - "name": "mkdirSync", - "desc": "

Synchronous mkdir(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "mode", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readdir(path, [callback])", - "type": "method", - "name": "readdir", - "desc": "

Asynchronous readdir(3). Reads the contents of a directory.\nThe callback gets two arguments (err, files) where files is an array of\nthe names of the files in the directory excluding '.' and '..'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readdirSync(path)", - "type": "method", - "name": "readdirSync", - "desc": "

Synchronous readdir(3). Returns an array of filenames excluding '.' and\n'..'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - } - ] - } - ] - }, - { - "textRaw": "fs.close(fd, [callback])", - "type": "method", - "name": "close", - "desc": "

Asynchronous close(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.closeSync(fd)", - "type": "method", - "name": "closeSync", - "desc": "

Synchronous close(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - } - ] - } - ] - }, - { - "textRaw": "fs.open(path, flags, [mode], [callback])", - "type": "method", - "name": "open", - "desc": "

Asynchronous file open. See open(2). flags can be:\n\n

\n
    \n

  • 'r' - Open file for reading.\nAn exception occurs if the file does not exist.

    \n
    • \n

  • 'r+' - Open file for reading and writing.\nAn exception occurs if the file does not exist.

    \n
    • \n

  • 'w' - Open file for writing.\nThe file is created (if it does not exist) or truncated (if it exists).

    \n
    • \n

  • 'w+' - Open file for reading and writing.\nThe file is created (if it does not exist) or truncated (if it exists).

    \n
    • \n

  • 'a' - Open file for appending.\nThe file is created if it does not exist.

    \n
    • \n

  • 'a+' - Open file for reading and appending.\nThe file is created if it does not exist.

    \n
    • \n
\n

mode defaults to 0666. The callback gets two arguments (err, fd).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "flags" - }, - { - "name": "mode", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.openSync(path, flags, [mode])", - "type": "method", - "name": "openSync", - "desc": "

Synchronous open(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "flags" - }, - { - "name": "mode", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.utimes(path, atime, mtime, [callback])", - "type": "method", - "name": "utimes", - "desc": "

Change file timestamps of the file referenced by the supplied path.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "atime" - }, - { - "name": "mtime" - } - ] - }, - { - "params": [ - { - "name": "path" - }, - { - "name": "atime" - }, - { - "name": "mtime" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.utimesSync(path, atime, mtime)", - "type": "method", - "name": "utimesSync", - "desc": "

Change file timestamps of the file referenced by the supplied path.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "atime" - }, - { - "name": "mtime" - } - ] - } - ] - }, - { - "textRaw": "fs.futimes(fd, atime, mtime, [callback])", - "type": "method", - "name": "futimes", - "desc": "

Change the file timestamps of a file referenced by the supplied file\ndescriptor.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "atime" - }, - { - "name": "mtime" - } - ] - }, - { - "params": [ - { - "name": "fd" - }, - { - "name": "atime" - }, - { - "name": "mtime" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.futimesSync(fd, atime, mtime)", - "type": "method", - "name": "futimesSync", - "desc": "

Change the file timestamps of a file referenced by the supplied file\ndescriptor.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "atime" - }, - { - "name": "mtime" - } - ] - } - ] - }, - { - "textRaw": "fs.fsync(fd, [callback])", - "type": "method", - "name": "fsync", - "desc": "

Asynchronous fsync(2). No arguments other than a possible exception are given\nto the completion callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.fsyncSync(fd)", - "type": "method", - "name": "fsyncSync", - "desc": "

Synchronous fsync(2).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - } - ] - } - ] - }, - { - "textRaw": "fs.write(fd, buffer, offset, length, position, [callback])", - "type": "method", - "name": "write", - "desc": "

Write buffer to the file specified by fd.\n\n

\n

offset and length determine the part of the buffer to be written.\n\n

\n

position refers to the offset from the beginning of the file where this data\nshould be written. If position is null, the data will be written at the\ncurrent position.\nSee pwrite(2).\n\n

\n

The callback will be given three arguments (err, written, buffer) where written\nspecifies how many bytes were written from buffer.\n\n

\n

Note that it is unsafe to use fs.write multiple times on the same file\nwithout waiting for the callback. For this scenario,\nfs.createWriteStream is strongly recommended.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "buffer" - }, - { - "name": "offset" - }, - { - "name": "length" - }, - { - "name": "position" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.writeSync(fd, buffer, offset, length, position)", - "type": "method", - "name": "writeSync", - "desc": "

Synchronous version of buffer-based fs.write(). Returns the number of bytes\nwritten.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "buffer" - }, - { - "name": "offset" - }, - { - "name": "length" - }, - { - "name": "position" - } - ] - } - ] - }, - { - "textRaw": "fs.writeSync(fd, str, position, [encoding])", - "type": "method", - "name": "writeSync", - "desc": "

Synchronous version of string-based fs.write(). encoding defaults to\n'utf8'. Returns the number of bytes written.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "str" - }, - { - "name": "position" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.read(fd, buffer, offset, length, position, [callback])", - "type": "method", - "name": "read", - "desc": "

Read data from the file specified by fd.\n\n

\n

buffer is the buffer that the data will be written to.\n\n

\n

offset is offset within the buffer where writing will start.\n\n

\n

length is an integer specifying the number of bytes to read.\n\n

\n

position is an integer specifying where to begin reading from in the file.\nIf position is null, data will be read from the current file position.\n\n

\n

The callback is given the three arguments, (err, bytesRead, buffer).\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "buffer" - }, - { - "name": "offset" - }, - { - "name": "length" - }, - { - "name": "position" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readSync(fd, buffer, offset, length, position)", - "type": "method", - "name": "readSync", - "desc": "

Synchronous version of buffer-based fs.read. Returns the number of\nbytesRead.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "buffer" - }, - { - "name": "offset" - }, - { - "name": "length" - }, - { - "name": "position" - } - ] - } - ] - }, - { - "textRaw": "fs.readSync(fd, length, position, encoding)", - "type": "method", - "name": "readSync", - "desc": "

Synchronous version of string-based fs.read. Returns the number of\nbytesRead.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - }, - { - "name": "length" - }, - { - "name": "position" - }, - { - "name": "encoding" - } - ] - } - ] - }, - { - "textRaw": "fs.readFile(filename, [encoding], [callback])", - "type": "method", - "name": "readFile", - "desc": "

Asynchronously reads the entire contents of a file. Example:\n\n

\n
fs.readFile('/etc/passwd', function (err, data) {\n  if (err) throw err;\n  console.log(data);\n});
\n

The callback is passed two arguments (err, data), where data is the\ncontents of the file.\n\n

\n

If no encoding is specified, then the raw buffer is returned.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "encoding", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.readFileSync(filename, [encoding])", - "type": "method", - "name": "readFileSync", - "desc": "

Synchronous version of fs.readFile. Returns the contents of the filename.\n\n

\n

If encoding is specified then this function returns a string. Otherwise it\nreturns a buffer.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.writeFile(filename, data, [encoding], [callback])", - "type": "method", - "name": "writeFile", - "desc": "

Asynchronously writes data to a file, replacing the file if it already exists.\ndata can be a string or a buffer. The encoding argument is ignored if\ndata is a buffer. It defaults to 'utf8'.\n\n

\n

Example:\n\n

\n
fs.writeFile('message.txt', 'Hello Node', function (err) {\n  if (err) throw err;\n  console.log('It\\'s saved!');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "data" - }, - { - "name": "encoding", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.writeFileSync(filename, data, [encoding])", - "type": "method", - "name": "writeFileSync", - "desc": "

The synchronous version of fs.writeFile.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "data" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.watchFile(filename, [options], listener)", - "type": "method", - "name": "watchFile", - "stability": 2, - "stabilityText": "Unstable. Use fs.watch instead, if available.", - "desc": "

Watch for changes on filename. The callback listener will be called each\ntime the file is accessed.\n\n

\n

The second argument is optional. The options if provided should be an object\ncontaining two members a boolean, persistent, and interval. persistent\nindicates whether the process should continue to run as long as files are\nbeing watched. interval indicates how often the target should be polled,\nin milliseconds. (On Linux systems with inotify, interval is ignored.) The\ndefault is { persistent: true, interval: 0 }.\n\n

\n

The listener gets two arguments the current stat object and the previous\nstat object:\n\n

\n
fs.watchFile('message.text', function (curr, prev) {\n  console.log('the current mtime is: ' + curr.mtime);\n  console.log('the previous mtime was: ' + prev.mtime);\n});
\n

These stat objects are instances of fs.Stat.\n\n

\n

If you want to be notified when the file was modified, not just accessed\nyou need to compare curr.mtime and prev.mtime.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "options", - "optional": true - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "fs.unwatchFile(filename)", - "type": "method", - "name": "unwatchFile", - "stability": 2, - "stabilityText": "Unstable. Use fs.watch instead, if available.", - "desc": "

Stop watching for changes on filename.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "filename" - } - ] - } - ] - }, - { - "textRaw": "fs.watch(filename, [options], listener)", - "type": "method", - "name": "watch", - "stability": 2, - "stabilityText": "Unstable. Not available on all platforms.", - "desc": "

Watch for changes on filename, where filename is either a file or a\ndirectory. The returned object is a fs.FSWatcher.\n\n

\n

The second argument is optional. The options if provided should be an object\ncontaining a boolean member persistent, which indicates whether the process\nshould continue to run as long as files are being watched. The default is\n{ persistent: true }.\n\n

\n

The listener callback gets two arguments (event, filename). event is either\n'rename' or 'change', and filename is the name of the file which triggered\nthe event.\n\n

\n", - "miscs": [ - { - "textRaw": "Caveats", - "name": "Caveats", - "type": "misc", - "desc": "

The fs.watch API is not 100% consistent across platforms, and is\nunavailable in some situations.\n\n

\n", - "miscs": [ - { - "textRaw": "Availability", - "name": "Availability", - "type": "misc", - "desc": "

This feature depends on the underlying operating system providing a way\nto be notified of filesystem changes.\n\n

\n
    \n
  • On Linux systems, this uses inotify.
    • \n
  • On BSD systems (including OS X), this uses kqueue.
    • \n
  • On SunOS systems (including Solaris and SmartOS), this uses event ports.
    • \n
  • On Windows systems, this feature depends on ReadDirectoryChangesW.
    • \n
\n

If the underlying functionality is not available for some reason, then\nfs.watch will not be able to function. You can still use\nfs.watchFile, which uses stat polling, but it is slower and less\nreliable.\n\n

\n" - }, - { - "textRaw": "Filename Argument", - "name": "Filename Argument", - "type": "misc", - "desc": "

Providing filename argument in the callback is not supported\non every platform (currently it's only supported on Linux and Windows). Even\non supported platforms filename is not always guaranteed to be provided.\nTherefore, don't assume that filename argument is always provided in the\ncallback, and have some fallback logic if it is null.\n\n

\n
fs.watch('somedir', function (event, filename) {\n  console.log('event is: ' + event);\n  if (filename) {\n    console.log('filename provided: ' + filename);\n  } else {\n    console.log('filename not provided');\n  }\n});
\n" - } - ] - } - ], - "signatures": [ - { - "params": [ - { - "name": "filename" - }, - { - "name": "options", - "optional": true - }, - { - "name": "listener" - } - ] - } - ] - }, - { - "textRaw": "fs.createReadStream(path, [options])", - "type": "method", - "name": "createReadStream", - "desc": "

Returns a new ReadStream object (See Readable Stream).\n\n

\n

options is an object with the following defaults:\n\n

\n
{ flags: 'r',\n  encoding: null,\n  fd: null,\n  mode: 0666,\n  bufferSize: 64 * 1024\n}
\n

options can include start and end values to read a range of bytes from\nthe file instead of the entire file. Both start and end are inclusive and\nstart at 0.\n\n

\n

An example to read the last 10 bytes of a file which is 100 bytes long:\n\n

\n
fs.createReadStream('sample.txt', {start: 90, end: 99});
\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "fs.createWriteStream(path, [options])", - "type": "method", - "name": "createWriteStream", - "desc": "

Returns a new WriteStream object (See Writable Stream).\n\n

\n

options is an object with the following defaults:\n\n

\n
{ flags: 'w',\n  encoding: null,\n  mode: 0666 }
\n

options may also include a start option to allow writing data at\nsome position past the beginning of the file. Modifying a file rather\nthan replacing it may require a flags mode of r+ rather than the\ndefault mode w.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "options", - "optional": true - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: fs.Stats", - "type": "class", - "name": "fs.Stats", - "desc": "

Objects returned from fs.stat(), fs.lstat() and fs.fstat() and their\nsynchronous counterparts are of this type.\n\n

\n
    \n
  • stats.isFile()
    • \n
  • stats.isDirectory()
    • \n
  • stats.isBlockDevice()
    • \n
  • stats.isCharacterDevice()
    • \n
  • stats.isSymbolicLink() (only valid with fs.lstat())
    • \n
  • stats.isFIFO()
    • \n
  • stats.isSocket()
    • \n
\n

For a regular file util.inspect(stats) would return a string very\nsimilar to this:\n\n

\n
{ dev: 2114,\n  ino: 48064969,\n  mode: 33188,\n  nlink: 1,\n  uid: 85,\n  gid: 100,\n  rdev: 0,\n  size: 527,\n  blksize: 4096,\n  blocks: 8,\n  atime: Mon, 10 Oct 2011 23:24:11 GMT,\n  mtime: Mon, 10 Oct 2011 23:24:11 GMT,\n  ctime: Mon, 10 Oct 2011 23:24:11 GMT }
\n

Please note that atime, mtime and ctime are instances\nof [Date][MDN-Date] object and to compare the values of\nthese objects you should use appropriate methods. For most\ngeneral uses [getTime()][MDN-Date-getTime] will return\nthe number of milliseconds elapsed since 1 January 1970\n00:00:00 UTC and this integer should be sufficient for\nany comparison, however there additional methods which can\nbe used for displaying fuzzy information. More details can\nbe found in the [MDN JavaScript Reference][MDN-Date] page.\n\n

\n" - }, - { - "textRaw": "Class: fs.ReadStream", - "type": "class", - "name": "fs.ReadStream", - "desc": "

ReadStream is a Readable Stream.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'open'", - "type": "event", - "name": "open", - "params": [], - "desc": "

Emitted when the ReadStream's file is opened.\n\n\n

\n" - } - ] - }, - { - "textRaw": "Class: fs.FSWatcher", - "type": "class", - "name": "fs.FSWatcher", - "desc": "

Objects returned from fs.watch() are of this type.\n\n

\n", - "methods": [ - { - "textRaw": "watcher.close()", - "type": "method", - "name": "close", - "desc": "

Stop watching for changes on the given fs.FSWatcher.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "events": [ - { - "textRaw": "Event: 'change'", - "type": "event", - "name": "change", - "params": [], - "desc": "

Emitted when something changes in a watched directory or file.\nSee more details in fs.watch.\n\n

\n" - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "params": [], - "desc": "

Emitted when an error occurs.\n

\n" - } - ] - } - ], - "properties": [ - { - "textRaw": "fs.WriteStream", - "name": "WriteStream", - "desc": "

WriteStream is a Writable Stream.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'open'", - "type": "event", - "name": "open", - "params": [], - "desc": "

Emitted when the WriteStream's file is opened.\n\n

\n" - } - ], - "properties": [ - { - "textRaw": "file.bytesWritten", - "name": "bytesWritten", - "desc": "

The number of bytes written so far. Does not include data that is still queued\nfor writing.\n\n

\n" - } - ] - } - ], - "type": "module", - "displayName": "fs" - } - ] -} --- a/doc/api/api/globals.html +++ /dev/null @@ -1,255 +0,0 @@ - - - - - Global Objects Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Global Objects#

- - -

These objects are available in all modules. Some of these objects aren't -actually in the global scope but in the module scope - this will be noted. - -

-

global#

- - -
    -
  • {Object} The global namespace object.
    • -
-

In browsers, the top-level scope is the global scope. That means that in -browsers if you're in the global scope var something will define a global -variable. In Node this is different. The top-level scope is not the global -scope; var something inside a Node module will be local to that module. - -

-

process#

- - -
    -
  • {Object}
    • -
-

The process object. See the process object section. - -

-

console#

- - -
    -
  • {Object}
    • -
-

Used to print to stdout and stderr. See the stdio section. - -

-

Buffer#

- - -
    -
  • {Object}
    • -
-

Used to handle binary data. See the buffer section. - -

-

require()#

- - -
    -
  • {Function}
    • -
-

To require modules. See the Modules section. -require isn't actually a global but rather local to each module. - - -

-

require.resolve()#

-

Use the internal require() machinery to look up the location of a module, -but rather than loading the module, just return the resolved filename. - -

-

require.cache#

-
    -
  • Object
    • -
-

Modules are cached in this object when they are required. By deleting a key -value from this object, the next require will reload the module. - -

-

__filename#

- - -
    -
  • {String}
    • -
-

The filename of the code being executed. This is the resolved absolute path -of this code file. For a main program this is not necessarily the same -filename used in the command line. The value inside a module is the path -to that module file. - -

-

Example: running node example.js from /Users/mjr - -

-
console.log(__filename);
-// /Users/mjr/example.js
-

__filename isn't actually a global but rather local to each module. - -

-

__dirname#

- - -
    -
  • {String}
    • -
-

The name of the directory that the currently executing script resides in. - -

-

Example: running node example.js from /Users/mjr - -

-
console.log(__dirname);
-// /Users/mjr
-

__dirname isn't actually a global but rather local to each module. - - -

-

module#

- - -
    -
  • {Object}
    • -
-

A reference to the current module. In particular -module.exports is the same as the exports object. See src/node.js -for more information. -module isn't actually a global but rather local to each module. - - -

-

exports#

- - -

An object which is shared between all instances of the current module and -made accessible through require(). -exports is the same as the module.exports object. See src/node.js -for more information. -exports isn't actually a global but rather local to each module. - -

-

See the module system documentation for more -information. - -

-

See the module section for more information. - -

-

setTimeout(cb, ms)#

-

clearTimeout(t)#

-

setInterval(cb, ms)#

-

clearInterval(t)#

- - -

The timer functions are global variables. See the timers section. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/globals.json +++ /dev/null @@ -1,219 +0,0 @@ -{ - "source": "doc/api/globals.markdown", - "globals": [ - { - "textRaw": "global", - "name": "global", - "type": "global", - "desc": "

In browsers, the top-level scope is the global scope. That means that in\nbrowsers if you're in the global scope var something will define a global\nvariable. In Node this is different. The top-level scope is not the global\nscope; var something inside a Node module will be local to that module.\n\n

\n" - }, - { - "textRaw": "process", - "name": "process", - "type": "global", - "desc": "

The process object. See the process object section.\n\n

\n" - }, - { - "textRaw": "console", - "name": "console", - "type": "global", - "desc": "

Used to print to stdout and stderr. See the stdio section.\n\n

\n" - }, - { - "textRaw": "Buffer", - "name": "Buffer", - "type": "global", - "desc": "

Used to handle binary data. See the buffer section.\n\n

\n" - }, - { - "textRaw": "clearInterval(t)", - "type": "global", - "name": "clearInterval", - "desc": "

The timer functions are global variables. See the timers section.\n

\n" - } - ], - "vars": [ - { - "textRaw": "require()", - "type": "var", - "name": "require", - "desc": "

To require modules. See the Modules section.\nrequire isn't actually a global but rather local to each module.\n\n\n

\n", - "methods": [ - { - "textRaw": "require.resolve()", - "type": "method", - "name": "resolve", - "desc": "

Use the internal require() machinery to look up the location of a module,\nbut rather than loading the module, just return the resolved filename.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "properties": [ - { - "textRaw": "`cache` {Object} ", - "name": "cache", - "desc": "

Modules are cached in this object when they are required. By deleting a key\nvalue from this object, the next require will reload the module.\n\n

\n" - } - ] - }, - { - "textRaw": "__filename", - "name": "__filename", - "type": "var", - "desc": "

The filename of the code being executed. This is the resolved absolute path\nof this code file. For a main program this is not necessarily the same\nfilename used in the command line. The value inside a module is the path\nto that module file.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__filename);\n// /Users/mjr/example.js
\n

__filename isn't actually a global but rather local to each module.\n\n

\n" - }, - { - "textRaw": "__dirname", - "name": "__dirname", - "type": "var", - "desc": "

The name of the directory that the currently executing script resides in.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__dirname);\n// /Users/mjr
\n

__dirname isn't actually a global but rather local to each module.\n\n\n

\n" - }, - { - "textRaw": "module", - "name": "module", - "type": "var", - "desc": "

A reference to the current module. In particular\nmodule.exports is the same as the exports object. See src/node.js\nfor more information.\nmodule isn't actually a global but rather local to each module.\n\n\n

\n" - }, - { - "textRaw": "exports", - "name": "exports", - "type": "var", - "desc": "

An object which is shared between all instances of the current module and\nmade accessible through require().\nexports is the same as the module.exports object. See src/node.js\nfor more information.\nexports isn't actually a global but rather local to each module.\n\n

\n

See the module system documentation for more\ninformation.\n\n

\n

See the module section for more information.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "setInterval(cb, ms)", - "type": "method", - "name": "setInterval", - "desc": "

The timer functions are global variables. See the timers section.\n

\n", - "signatures": [ - { - "params": [ - { - "name": "cb" - }, - { - "name": "ms" - } - ] - } - ] - } - ], - "miscs": [ - { - "textRaw": "Global Objects", - "name": "Global Objects", - "type": "misc", - "desc": "

These objects are available in all modules. Some of these objects aren't\nactually in the global scope but in the module scope - this will be noted.\n\n

\n", - "globals": [ - { - "textRaw": "global", - "name": "global", - "type": "global", - "desc": "

In browsers, the top-level scope is the global scope. That means that in\nbrowsers if you're in the global scope var something will define a global\nvariable. In Node this is different. The top-level scope is not the global\nscope; var something inside a Node module will be local to that module.\n\n

\n" - }, - { - "textRaw": "process", - "name": "process", - "type": "global", - "desc": "

The process object. See the process object section.\n\n

\n" - }, - { - "textRaw": "console", - "name": "console", - "type": "global", - "desc": "

Used to print to stdout and stderr. See the stdio section.\n\n

\n" - }, - { - "textRaw": "Buffer", - "name": "Buffer", - "type": "global", - "desc": "

Used to handle binary data. See the buffer section.\n\n

\n" - }, - { - "textRaw": "clearInterval(t)", - "type": "global", - "name": "clearInterval", - "desc": "

The timer functions are global variables. See the timers section.\n

\n" - } - ], - "vars": [ - { - "textRaw": "require()", - "type": "var", - "name": "require", - "desc": "

To require modules. See the Modules section.\nrequire isn't actually a global but rather local to each module.\n\n\n

\n", - "methods": [ - { - "textRaw": "require.resolve()", - "type": "method", - "name": "resolve", - "desc": "

Use the internal require() machinery to look up the location of a module,\nbut rather than loading the module, just return the resolved filename.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "properties": [ - { - "textRaw": "`cache` {Object} ", - "name": "cache", - "desc": "

Modules are cached in this object when they are required. By deleting a key\nvalue from this object, the next require will reload the module.\n\n

\n" - } - ] - }, - { - "textRaw": "__filename", - "name": "__filename", - "type": "var", - "desc": "

The filename of the code being executed. This is the resolved absolute path\nof this code file. For a main program this is not necessarily the same\nfilename used in the command line. The value inside a module is the path\nto that module file.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__filename);\n// /Users/mjr/example.js
\n

__filename isn't actually a global but rather local to each module.\n\n

\n" - }, - { - "textRaw": "__dirname", - "name": "__dirname", - "type": "var", - "desc": "

The name of the directory that the currently executing script resides in.\n\n

\n

Example: running node example.js from /Users/mjr\n\n

\n
console.log(__dirname);\n// /Users/mjr
\n

__dirname isn't actually a global but rather local to each module.\n\n\n

\n" - }, - { - "textRaw": "module", - "name": "module", - "type": "var", - "desc": "

A reference to the current module. In particular\nmodule.exports is the same as the exports object. See src/node.js\nfor more information.\nmodule isn't actually a global but rather local to each module.\n\n\n

\n" - }, - { - "textRaw": "exports", - "name": "exports", - "type": "var", - "desc": "

An object which is shared between all instances of the current module and\nmade accessible through require().\nexports is the same as the module.exports object. See src/node.js\nfor more information.\nexports isn't actually a global but rather local to each module.\n\n

\n

See the module system documentation for more\ninformation.\n\n

\n

See the module section for more information.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "setInterval(cb, ms)", - "type": "method", - "name": "setInterval", - "desc": "

The timer functions are global variables. See the timers section.\n

\n", - "signatures": [ - { - "params": [ - { - "name": "cb" - }, - { - "name": "ms" - } - ] - } - ] - } - ] - } - ] -} --- a/doc/api/api/http.html +++ /dev/null @@ -1,1007 +0,0 @@ - - - - - HTTP Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- -
-

Table of Contents

- - -
- -
-

HTTP#

-
Stability: 3 - Stable
-

To use the HTTP server and client one must require('http'). - -

-

The HTTP interfaces in Node are designed to support many features -of the protocol which have been traditionally difficult to use. -In particular, large, possibly chunk-encoded, messages. The interface is -careful to never buffer entire requests or responses--the -user is able to stream data. - -

-

HTTP message headers are represented by an object like this: - -

-
{ 'content-length': '123',
-  'content-type': 'text/plain',
-  'connection': 'keep-alive',
-  'accept': '*/*' }
-

Keys are lowercased. Values are not modified. - -

-

In order to support the full spectrum of possible HTTP applications, Node's -HTTP API is very low-level. It deals with stream handling and message -parsing only. It parses a message into headers and body but it does not -parse the actual headers or the body. - - -

-

http.createServer([requestListener])#

-

Returns a new web server object. - -

-

The requestListener is a function which is automatically -added to the 'request' event. - -

-

Class: http.Server#

-

This is an EventEmitter with the following events: - -

-

Event: 'request'#

-

function (request, response) { } - -

-

Emitted each time there is a request. Note that there may be multiple requests -per connection (in the case of keep-alive connections). - request is an instance of http.ServerRequest and response is - an instance of http.ServerResponse - -

-

Event: 'connection'#

-

function (socket) { } - -

-

When a new TCP stream is established. socket is an object of type - net.Socket. Usually users will not want to access this event. The - socket can also be accessed at request.connection. - -

-

Event: 'close'#

-

function () { } - -

-

Emitted when the server closes. - -

-

Event: 'checkContinue'#

-

function (request, response) { } - -

-

Emitted each time a request with an http Expect: 100-continue is received. -If this event isn't listened for, the server will automatically respond -with a 100 Continue as appropriate. - -

-

Handling this event involves calling response.writeContinue if the client -should continue to send the request body, or generating an appropriate HTTP -response (e.g., 400 Bad Request) if the client should not continue to send the -request body. - -

-

Note that when this event is emitted and handled, the request event will -not be emitted. - -

-

Event: 'upgrade'#

-

function (request, socket, head) { } - -

-

Emitted each time a client requests a http upgrade. If this event isn't -listened for, then clients requesting an upgrade will have their connections -closed. - -

-
    -
  • request is the arguments for the http request, as it is in the request event.
    • -
  • socket is the network socket between the server and client.
    • -
  • head is an instance of Buffer, the first packet of the upgraded stream, this may be empty.
    • -
-

After this event is emitted, the request's socket will not have a data -event listener, meaning you will need to bind to it in order to handle data -sent to the server on that socket. - -

-

Event: 'clientError'#

-

function (exception) { } - -

-

If a client connection emits an 'error' event - it will forwarded here. - -

-

server.listen(port, [hostname], [callback])#

-

Begin accepting connections on the specified port and hostname. If the -hostname is omitted, the server will accept connections directed to any -IPv4 address (INADDR_ANY). - -

-

To listen to a unix socket, supply a filename instead of port and hostname. - -

-

This function is asynchronous. The last parameter callback will be added as -a listener for the 'listening' event. -See also net.Server.listen(). - - -

-

server.listen(path, [callback])#

-

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

-

This function is asynchronous. The last parameter callback will be added as -a listener for the 'listening' event. -See also net.Server.listen(). - - -

-

server.close()#

-

Stops the server from accepting new connections. -See net.Server.close(). - - -

-

Class: http.ServerRequest#

-

This object is created internally by a HTTP server -- not by -the user -- and passed as the first argument to a 'request' listener. - -

-

The request implements the Readable Stream -interface. This is an EventEmitter with the following events: - -

-

Event: 'data'#

-

function (chunk) { } - -

-

Emitted when a piece of the message body is received. The chunk is a string if -an encoding has been set with request.setEncoding(), otherwise it's a -Buffer. - -

-

Note that the data will be lost if there is no listener when a -ServerRequest emits a 'data' event. - -

-

Event: 'end'#

-

function () { } - -

-

Emitted exactly once for each request. After that, no more 'data' events -will be emitted on the request. - -

-

Event: 'close'#

-

function () { } - -

-

Indicates that the underlaying connection was terminated before -response.end() was called or able to flush. - -

-

Just like 'end', this event occurs only once per request, and no more 'data' -events will fire afterwards. - -

-

Note: 'close' can fire after 'end', but not vice versa. - -

-

request.method#

-

The request method as a string. Read only. Example: -'GET', 'DELETE'. - - -

-

request.url#

-

Request URL string. This contains only the URL that is -present in the actual HTTP request. If the request is: - -

-
GET /status?name=ryan HTTP/1.1\r\n
-Accept: text/plain\r\n
-\r\n
-

Then request.url will be: - -

-
'/status?name=ryan'
-

If you would like to parse the URL into its parts, you can use -require('url').parse(request.url). Example: - -

-
node> require('url').parse('/status?name=ryan')
-{ href: '/status?name=ryan',
-  search: '?name=ryan',
-  query: 'name=ryan',
-  pathname: '/status' }
-

If you would like to extract the params from the query string, -you can use the require('querystring').parse function, or pass -true as the second argument to require('url').parse. Example: - -

-
node> require('url').parse('/status?name=ryan', true)
-{ href: '/status?name=ryan',
-  search: '?name=ryan',
-  query: { name: 'ryan' },
-  pathname: '/status' }
-

request.headers#

-

Read only. - -

-

request.trailers#

-

Read only; HTTP trailers (if present). Only populated after the 'end' event. - -

-

request.httpVersion#

-

The HTTP protocol version as a string. Read only. Examples: -'1.1', '1.0'. -Also request.httpVersionMajor is the first integer and -request.httpVersionMinor is the second. - - -

-

request.setEncoding([encoding])#

-

Set the encoding for the request body. Either 'utf8' or 'binary'. Defaults -to null, which means that the 'data' event will emit a Buffer object.. - - -

-

request.pause()#

-

Pauses request from emitting events. Useful to throttle back an upload. - - -

-

request.resume()#

-

Resumes a paused request. - -

-

request.connection#

-

The net.Socket object associated with the connection. - - -

-

With HTTPS support, use request.connection.verifyPeer() and -request.connection.getPeerCertificate() to obtain the client's -authentication details. - - - -

-

Class: http.ServerResponse#

-

This object is created internally by a HTTP server--not by the user. It is -passed as the second parameter to the 'request' event. - -

-

The response implements the Writable Stream -interface. This is an EventEmitter with the following events: - -

-

Event: 'close'#

-

function () { } - -

-

Indicates that the underlaying connection was terminated before -response.end() was called or able to flush. - -

-

response.writeContinue()#

-

Sends a HTTP/1.1 100 Continue message to the client, indicating that -the request body should be sent. See the checkContinue event on -Server. - -

-

response.writeHead(statusCode, [reasonPhrase], [headers])#

-

Sends a response header to the request. The status code is a 3-digit HTTP -status code, like 404. The last argument, headers, are the response headers. -Optionally one can give a human-readable reasonPhrase as the second -argument. - -

-

Example: - -

-
var body = 'hello world';
-response.writeHead(200, {
-  'Content-Length': body.length,
-  'Content-Type': 'text/plain' });
-

This method must only be called once on a message and it must -be called before response.end() is called. - -

-

If you call response.write() or response.end() before calling this, the -implicit/mutable headers will be calculated and call this function for you. - -

-

Note: that Content-Length is given in bytes not characters. The above example -works because the string 'hello world' contains only single byte characters. -If the body contains higher coded characters then Buffer.byteLength() -should be used to determine the number of bytes in a given encoding. -And Node does not check whether Content-Length and the length of the body -which has been transmitted are equal or not. - -

-

response.statusCode#

-

When using implicit headers (not calling response.writeHead() explicitly), this property -controls the status code that will be send to the client when the headers get -flushed. - -

-

Example: - -

-
response.statusCode = 404;
-

After response header was sent to the client, this property indicates the -status code which was sent out. - -

-

response.setHeader(name, value)#

-

Sets a single header value for implicit headers. If this header already exists -in the to-be-sent headers, its value will be replaced. Use an array of strings -here if you need to send multiple headers with the same name. - -

-

Example: - -

-
response.setHeader("Content-Type", "text/html");
-

or - -

-
response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]);
-

response.getHeader(name)#

-

Reads out a header that's already been queued but not sent to the client. Note -that the name is case insensitive. This can only be called before headers get -implicitly flushed. - -

-

Example: - -

-
var contentType = response.getHeader('content-type');
-

response.removeHeader(name)#

-

Removes a header that's queued for implicit sending. - -

-

Example: - -

-
response.removeHeader("Content-Encoding");
-

response.write(chunk, [encoding])#

-

If this method is called and response.writeHead() has not been called, it will -switch to implicit header mode and flush the implicit headers. - -

-

This sends a chunk of the response body. This method may -be called multiple times to provide successive parts of the body. - -

-

chunk can be a string or a buffer. If chunk is a string, -the second parameter specifies how to encode it into a byte stream. -By default the encoding is 'utf8'. - -

-

Note: This is the raw HTTP body and has nothing to do with -higher-level multi-part body encodings that may be used. - -

-

The first time response.write() is called, it will send the buffered -header information and the first body to the client. The second time -response.write() is called, Node assumes you're going to be streaming -data, and sends that separately. That is, the response is buffered up to the -first chunk of body. - -

-

response.addTrailers(headers)#

-

This method adds HTTP trailing headers (a header but at the end of the -message) to the response. - -

-

Trailers will only be emitted if chunked encoding is used for the -response; if it is not (e.g., if the request was HTTP/1.0), they will -be silently discarded. - -

-

Note that HTTP requires the Trailer header to be sent if you intend to -emit trailers, with a list of the header fields in its value. E.g., - -

-
response.writeHead(200, { 'Content-Type': 'text/plain',
-                          'Trailer': 'Content-MD5' });
-response.write(fileData);
-response.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});
-response.end();
-

response.end([data], [encoding])#

-

This method signals to the server that all of the response headers and body -has been sent; that server should consider this message complete. -The method, response.end(), MUST be called on each -response. - -

-

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

-

http.request(options, callback)#

-

Node maintains several connections per server to make HTTP requests. -This function allows one to transparently issue requests. options align -with url.parse(). - -

-

Options: - -

-
    -
  • host: A domain name or IP address of the server to issue the request to. -Defaults to 'localhost'.
    • -
  • hostname: To support url.parse() hostname is preferred over host
    • -
  • port: Port of remote server. Defaults to 80.
    • -
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • -
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • -
  • path: Request path. Defaults to '/'. Should include query string if any. -E.G. '/index.html?page=12'
    • -
  • headers: An object containing request headers.
    • -
  • auth: Basic authentication i.e. 'user:password' to compute an -Authorization header.
    • -
  • agent: Controls Agent behavior. When an Agent is used -request will default to Connection: keep-alive. Possible values:
      -
    • undefined (default): use global Agent for this host -and port.
      • -
    • Agent object: explicitly use the passed in Agent.
      • -
    • false: opts out of connection pooling with an Agent, defaults request to -Connection: close.
      • -
    -
    • -
-

http.request() returns an instance of the http.ClientRequest -class. The ClientRequest instance is a writable stream. If one needs to -upload a file with a POST request, then write to the ClientRequest object. - -

-

Example: - -

-
var options = {
-  host: 'www.google.com',
-  port: 80,
-  path: '/upload',
-  method: 'POST'
-};
-
-var req = http.request(options, function(res) {
-  console.log('STATUS: ' + res.statusCode);
-  console.log('HEADERS: ' + JSON.stringify(res.headers));
-  res.setEncoding('utf8');
-  res.on('data', function (chunk) {
-    console.log('BODY: ' + chunk);
-  });
-});
-
-req.on('error', function(e) {
-  console.log('problem with request: ' + e.message);
-});
-
-// write data to request body
-req.write('data\n');
-req.write('data\n');
-req.end();
-

Note that in the example req.end() was called. With http.request() one -must always call req.end() to signify that you're done with the request - -even if there is no data being written to the request body. - -

-

If any error is encountered during the request (be that with DNS resolution, -TCP level errors, or actual HTTP parse errors) an 'error' event is emitted -on the returned request object. - -

-

There are a few special headers that should be noted. - -

-
    -

  • Sending a 'Connection: keep-alive' will notify Node that the connection to -the server should be persisted until the next request.

    -
    • -

  • Sending a 'Content-length' header will disable the default chunked encoding.

    -
    • -

  • Sending an 'Expect' header will immediately send the request headers. -Usually, when sending 'Expect: 100-continue', you should both set a timeout -and listen for the continue event. See RFC2616 Section 8.2.3 for more -information.

    -
    • -

  • Sending an Authorization header will override using the auth option -to compute basic authentication.

    -
    • -
-

http.get(options, callback)#

-

Since most requests are GET requests without bodies, Node provides this -convenience method. The only difference between this method and http.request() is -that it sets the method to GET and calls req.end() automatically. - -

-

Example: - -

-
var options = {
-  host: 'www.google.com',
-  port: 80,
-  path: '/index.html'
-};
-
-http.get(options, function(res) {
-  console.log("Got response: " + res.statusCode);
-}).on('error', function(e) {
-  console.log("Got error: " + e.message);
-});
-

Class: http.Agent#

-

In node 0.5.3+ there is a new implementation of the HTTP Agent which is used -for pooling sockets used in HTTP client requests. - -

-

Previously, a single agent instance help the pool for single host+port. The -current implementation now holds sockets for any number of hosts. - -

-

The current HTTP Agent also defaults client requests to using -Connection:keep-alive. If no pending HTTP requests are waiting on a socket -to become free the socket is closed. This means that node's pool has the -benefit of keep-alive when under load but still does not require developers -to manually close the HTTP clients using keep-alive. - -

-

Sockets are removed from the agent's pool when the socket emits either a -"close" event or a special "agentRemove" event. This means that if you intend -to keep one HTTP request open for a long time and don't want it to stay in the -pool you can do something along the lines of: - -

-
http.get(options, function(res) {
-  // Do stuff
-}).on("socket", function (socket) {
-  socket.emit("agentRemove");
-});
-

Alternatively, you could just opt out of pooling entirely using agent:false: - -

-
http.get({host:'localhost', port:80, path:'/', agent:false}, function (res) {
-  // Do stuff
-})
-

agent.maxSockets#

-

By default set to 5. Determines how many concurrent sockets the agent can have -open per host. - -

-

agent.sockets#

-

An object which contains arrays of sockets currently in use by the Agent. Do not -modify. - -

-

agent.requests#

-

An object which contains queues of requests that have not yet been assigned to -sockets. Do not modify. - -

-

http.globalAgent#

-

Global instance of Agent which is used as the default for all http client -requests. - - -

-

Class: http.ClientRequest#

-

This object is created internally and returned from http.request(). It -represents an in-progress request whose header has already been queued. The -header is still mutable using the setHeader(name, value), getHeader(name), -removeHeader(name) API. The actual header will be sent along with the first -data chunk or when closing the connection. - -

-

To get the response, add a listener for 'response' to the request object. -'response' will be emitted from the request object when the response -headers have been received. The 'response' event is executed with one -argument which is an instance of http.ClientResponse. - -

-

During the 'response' event, one can add listeners to the -response object; particularly to listen for the 'data' event. Note that -the 'response' event is called before any part of the response body is received, -so there is no need to worry about racing to catch the first part of the -body. As long as a listener for 'data' is added during the 'response' -event, the entire body will be caught. - - -

-
// Good
-request.on('response', function (response) {
-  response.on('data', function (chunk) {
-    console.log('BODY: ' + chunk);
-  });
-});
-
-// Bad - misses all or part of the body
-request.on('response', function (response) {
-  setTimeout(function () {
-    response.on('data', function (chunk) {
-      console.log('BODY: ' + chunk);
-    });
-  }, 10);
-});
-

Note: Node does not check whether Content-Length and the length of the body -which has been transmitted are equal or not. - -

-

The request implements the Writable Stream -interface. This is an EventEmitter with the following events: - -

-

Event 'response'#

-

function (response) { } - -

-

Emitted when a response is received to this request. This event is emitted only once. The -response argument will be an instance of http.ClientResponse. - -

-

Options: - -

-
    -
  • host: A domain name or IP address of the server to issue the request to.
    • -
  • port: Port of remote server.
    • -
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • -
-

Event: 'socket'#

-

function (socket) { } - -

-

Emitted after a socket is assigned to this request. - -

-

Event: 'upgrade'#

-

function (response, 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. - -

-

A client server pair that show you how to listen for the upgrade event using http.getAgent: - -

-
var http = require('http');
-var net = require('net');
-
-// Create an HTTP server
-var srv = http.createServer(function (req, res) {
-  res.writeHead(200, {'Content-Type': 'text/plain'});
-  res.end('okay');
-});
-srv.on('upgrade', function(req, socket, upgradeHead) {
-  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
-               'Upgrade: WebSocket\r\n' +
-               'Connection: Upgrade\r\n' +
-               '\r\n\r\n');
-
-  socket.ondata = function(data, start, end) {
-    socket.write(data.toString('utf8', start, end), 'utf8'); // echo back
-  };
-});
-
-// now that server is running
-srv.listen(1337, '127.0.0.1', function() {
-
-  // make a request
-  var options = {
-    port: 1337,
-    host: '127.0.0.1',
-    headers: {
-      'Connection': 'Upgrade',
-      'Upgrade': 'websocket'
-    }
-  };
-
-  var req = http.request(options);
-  req.end();
-
-  req.on('upgrade', function(res, socket, upgradeHead) {
-    console.log('got upgraded!');
-    socket.end();
-    process.exit(0);
-  });
-});
-

Event: 'continue'#

-

function () { } - -

-

Emitted when the server sends a '100 Continue' HTTP response, usually because -the request contained 'Expect: 100-continue'. This is an instruction that -the client should send the request body. - -

-

request.write(chunk, [encoding])#

-

Sends a chunk of the body. By calling this method -many times, the user can stream a request body to a -server--in that case it is suggested to use the -['Transfer-Encoding', 'chunked'] header line when -creating the request. - -

-

The chunk argument should be a buffer or a string. - -

-

The encoding argument is optional and only applies when chunk is a string. -Defaults to 'utf8'. - - -

-

request.end([data], [encoding])#

-

Finishes sending the request. If any parts of the body are -unsent, it will flush them to the stream. If the request is -chunked, this will send the terminating '0\r\n\r\n'. - -

-

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

-

request.abort()#

-

Aborts a request. (New since v0.3.8.) - -

-

request.setTimeout(timeout, [callback])#

-

Once a socket is assigned to this request and is connected -socket.setTimeout(timeout, [callback]) -will be called. - -

-

request.setNoDelay([noDelay])#

-

Once a socket is assigned to this request and is connected -socket.setNoDelay(noDelay) -will be called. - -

-

request.setSocketKeepAlive([enable], [initialDelay])#

-

Once a socket is assigned to this request and is connected -socket.setKeepAlive(enable, [initialDelay]) -will be called. - -

-

http.ClientResponse#

-

This object is created when making a request with http.request(). It is -passed to the 'response' event of the request object. - -

-

The response implements the Readable Stream -interface. This is an EventEmitter with the following events: - - -

-

Event: 'data'#

-

function (chunk) { } - -

-

Emitted when a piece of the message body is received. - -

-

Note that the data will be lost if there is no listener when a -ClientResponse emits a 'data' event. - - -

-

Event: 'end'#

-

function () { } - -

-

Emitted exactly once for each message. No arguments. After -emitted no other events will be emitted on the response. - -

-

Event: 'close'#

-

function (err) { } - -

-

Indicates that the underlaying connection was terminated before -end event was emitted. -See http.ServerRequest's 'close' event for more -information. - -

-

response.statusCode#

-

The 3-digit HTTP response status code. E.G. 404. - -

-

response.httpVersion#

-

The HTTP version of the connected-to server. Probably either -'1.1' or '1.0'. -Also response.httpVersionMajor is the first integer and -response.httpVersionMinor is the second. - -

-

response.headers#

-

The response headers object. - -

-

response.trailers#

-

The response trailers object. Only populated after the 'end' event. - -

-

response.setEncoding([encoding])#

-

Set the encoding for the response body. Either 'utf8', 'ascii', or -'base64'. Defaults to null, which means that the 'data' event will emit -a Buffer object. - -

-

response.pause()#

-

Pauses response from emitting events. Useful to throttle back a download. - -

-

response.resume()#

-

Resumes a paused response. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/http.json +++ /dev/null @@ -1,699 +0,0 @@ -{ - "source": "doc/api/http.markdown", - "modules": [ - { - "textRaw": "HTTP", - "name": "http", - "stability": 3, - "stabilityText": "Stable", - "desc": "

To use the HTTP server and client one must require('http').\n\n

\n

The HTTP interfaces in Node are designed to support many features\nof the protocol which have been traditionally difficult to use.\nIn particular, large, possibly chunk-encoded, messages. The interface is\ncareful to never buffer entire requests or responses--the\nuser is able to stream data.\n\n

\n

HTTP message headers are represented by an object like this:\n\n

\n
{ 'content-length': '123',\n  'content-type': 'text/plain',\n  'connection': 'keep-alive',\n  'accept': '*/*' }
\n

Keys are lowercased. Values are not modified.\n\n

\n

In order to support the full spectrum of possible HTTP applications, Node's\nHTTP API is very low-level. It deals with stream handling and message\nparsing only. It parses a message into headers and body but it does not\nparse the actual headers or the body.\n\n\n

\n", - "methods": [ - { - "textRaw": "http.createServer([requestListener])", - "type": "method", - "name": "createServer", - "desc": "

Returns a new web server object.\n\n

\n

The requestListener is a function which is automatically\nadded to the 'request' event.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "requestListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "http.request(options, callback)", - "type": "method", - "name": "request", - "desc": "

Node maintains several connections per server to make HTTP requests.\nThis function allows one to transparently issue requests. options align\nwith url.parse().\n\n

\n

Options:\n\n

\n
    \n
  • host: A domain name or IP address of the server to issue the request to.\nDefaults to 'localhost'.
    • \n
  • hostname: To support url.parse() hostname is preferred over host
    • \n
  • port: Port of remote server. Defaults to 80.
    • \n
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • \n
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • \n
  • path: Request path. Defaults to '/'. Should include query string if any.\nE.G. '/index.html?page=12'
    • \n
  • headers: An object containing request headers.
    • \n
  • auth: Basic authentication i.e. 'user:password' to compute an\nAuthorization header.
    • \n
  • agent: Controls Agent behavior. When an Agent is used\nrequest will default to Connection: keep-alive. Possible values:
      \n
    • undefined (default): use global Agent for this host\nand port.
      • \n
    • Agent object: explicitly use the passed in Agent.
      • \n
    • false: opts out of connection pooling with an Agent, defaults request to\nConnection: close.
      • \n
    \n
    • \n
\n

http.request() returns an instance of the http.ClientRequest\nclass. The ClientRequest instance is a writable stream. If one needs to\nupload a file with a POST request, then write to the ClientRequest object.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'www.google.com',\n  port: 80,\n  path: '/upload',\n  method: 'POST'\n};\n\nvar req = http.request(options, function(res) {\n  console.log('STATUS: ' + res.statusCode);\n  console.log('HEADERS: ' + JSON.stringify(res.headers));\n  res.setEncoding('utf8');\n  res.on('data', function (chunk) {\n    console.log('BODY: ' + chunk);\n  });\n});\n\nreq.on('error', function(e) {\n  console.log('problem with request: ' + e.message);\n});\n\n// write data to request body\nreq.write('data\\n');\nreq.write('data\\n');\nreq.end();
\n

Note that in the example req.end() was called. With http.request() one\nmust always call req.end() to signify that you're done with the request -\neven if there is no data being written to the request body.\n\n

\n

If any error is encountered during the request (be that with DNS resolution,\nTCP level errors, or actual HTTP parse errors) an 'error' event is emitted\non the returned request object.\n\n

\n

There are a few special headers that should be noted.\n\n

\n
    \n

  • Sending a 'Connection: keep-alive' will notify Node that the connection to\nthe server should be persisted until the next request.

    \n
    • \n

  • Sending a 'Content-length' header will disable the default chunked encoding.

    \n
    • \n

  • Sending an 'Expect' header will immediately send the request headers.\nUsually, when sending 'Expect: 100-continue', you should both set a timeout\nand listen for the continue event. See RFC2616 Section 8.2.3 for more\ninformation.

    \n
    • \n

  • Sending an Authorization header will override using the auth option\nto compute basic authentication.

    \n
    • \n
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "http.get(options, callback)", - "type": "method", - "name": "get", - "desc": "

Since most requests are GET requests without bodies, Node provides this\nconvenience method. The only difference between this method and http.request() is\nthat it sets the method to GET and calls req.end() automatically.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'www.google.com',\n  port: 80,\n  path: '/index.html'\n};\n\nhttp.get(options, function(res) {\n  console.log("Got response: " + res.statusCode);\n}).on('error', function(e) {\n  console.log("Got error: " + e.message);\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "callback" - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: http.Server", - "type": "class", - "name": "http.Server", - "desc": "

This is an EventEmitter with the following events:\n\n

\n", - "events": [ - { - "textRaw": "Event: 'request'", - "type": "event", - "name": "request", - "desc": "

function (request, response) { }\n\n

\n

Emitted each time there is a request. Note that there may be multiple requests\nper connection (in the case of keep-alive connections).\n request is an instance of http.ServerRequest and response is\n an instance of http.ServerResponse\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'connection'", - "type": "event", - "name": "connection", - "desc": "

function (socket) { }\n\n

\n

When a new TCP stream is established. socket is an object of type\n net.Socket. Usually users will not want to access this event. The\n socket can also be accessed at request.connection.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () { }\n\n

\n

Emitted when the server closes.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'checkContinue'", - "type": "event", - "name": "checkContinue", - "desc": "

function (request, response) { }\n\n

\n

Emitted each time a request with an http Expect: 100-continue is received.\nIf this event isn't listened for, the server will automatically respond\nwith a 100 Continue as appropriate.\n\n

\n

Handling this event involves calling response.writeContinue if the client\nshould continue to send the request body, or generating an appropriate HTTP\nresponse (e.g., 400 Bad Request) if the client should not continue to send the\nrequest body.\n\n

\n

Note that when this event is emitted and handled, the request event will\nnot be emitted.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'upgrade'", - "type": "event", - "name": "upgrade", - "desc": "

function (request, socket, head) { }\n\n

\n

Emitted each time a client requests a http upgrade. If this event isn't\nlistened for, then clients requesting an upgrade will have their connections\nclosed.\n\n

\n
    \n
  • request is the arguments for the http request, as it is in the request event.
    • \n
  • socket is the network socket between the server and client.
    • \n
  • head is an instance of Buffer, the first packet of the upgraded stream, this may be empty.
    • \n
\n

After this event is emitted, the request's socket will not have a data\nevent listener, meaning you will need to bind to it in order to handle data\nsent to the server on that socket.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'clientError'", - "type": "event", - "name": "clientError", - "desc": "

function (exception) { }\n\n

\n

If a client connection emits an 'error' event - it will forwarded here.\n\n

\n", - "params": [] - } - ], - "methods": [ - { - "textRaw": "server.listen(port, [hostname], [callback])", - "type": "method", - "name": "listen", - "desc": "

Begin accepting connections on the specified port and hostname. If the\nhostname is omitted, the server will accept connections directed to any\nIPv4 address (INADDR_ANY).\n\n

\n

To listen to a unix socket, supply a filename instead of port and hostname.\n\n

\n

This function is asynchronous. The last parameter callback will be added as\na listener for the 'listening' event.\nSee also net.Server.listen().\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "port" - }, - { - "name": "hostname", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "server.listen(path, [callback])", - "type": "method", - "name": "listen", - "desc": "

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

\n

This function is asynchronous. The last parameter callback will be added as\na listener for the 'listening' event.\nSee also net.Server.listen().\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "server.close()", - "type": "method", - "name": "close", - "desc": "

Stops the server from accepting new connections.\nSee net.Server.close().\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - }, - { - "textRaw": "Class: http.ServerRequest", - "type": "class", - "name": "http.ServerRequest", - "desc": "

This object is created internally by a HTTP server -- not by\nthe user -- and passed as the first argument to a 'request' listener.\n\n

\n

The request implements the Readable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", - "events": [ - { - "textRaw": "Event: 'data'", - "type": "event", - "name": "data", - "desc": "

function (chunk) { }\n\n

\n

Emitted when a piece of the message body is received. The chunk is a string if\nan encoding has been set with request.setEncoding(), otherwise it's a\nBuffer.\n\n

\n

Note that the data will be lost if there is no listener when a\nServerRequest emits a 'data' event.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'end'", - "type": "event", - "name": "end", - "desc": "

function () { }\n\n

\n

Emitted exactly once for each request. After that, no more 'data' events\nwill be emitted on the request.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () { }\n\n

\n

Indicates that the underlaying connection was terminated before\nresponse.end() was called or able to flush.\n\n

\n

Just like 'end', this event occurs only once per request, and no more 'data'\nevents will fire afterwards.\n\n

\n

Note: 'close' can fire after 'end', but not vice versa.\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "request.method", - "name": "method", - "desc": "

The request method as a string. Read only. Example:\n'GET', 'DELETE'.\n\n\n

\n" - }, - { - "textRaw": "request.url", - "name": "url", - "desc": "

Request URL string. This contains only the URL that is\npresent in the actual HTTP request. If the request is:\n\n

\n
GET /status?name=ryan HTTP/1.1\\r\\n\nAccept: text/plain\\r\\n\n\\r\\n
\n

Then request.url will be:\n\n

\n
'/status?name=ryan'
\n

If you would like to parse the URL into its parts, you can use\nrequire('url').parse(request.url). Example:\n\n

\n
node> require('url').parse('/status?name=ryan')\n{ href: '/status?name=ryan',\n  search: '?name=ryan',\n  query: 'name=ryan',\n  pathname: '/status' }
\n

If you would like to extract the params from the query string,\nyou can use the require('querystring').parse function, or pass\ntrue as the second argument to require('url').parse. Example:\n\n

\n
node> require('url').parse('/status?name=ryan', true)\n{ href: '/status?name=ryan',\n  search: '?name=ryan',\n  query: { name: 'ryan' },\n  pathname: '/status' }
\n" - }, - { - "textRaw": "request.headers", - "name": "headers", - "desc": "

Read only.\n\n

\n" - }, - { - "textRaw": "request.trailers", - "name": "trailers", - "desc": "

Read only; HTTP trailers (if present). Only populated after the 'end' event.\n\n

\n" - }, - { - "textRaw": "request.httpVersion", - "name": "httpVersion", - "desc": "

The HTTP protocol version as a string. Read only. Examples:\n'1.1', '1.0'.\nAlso request.httpVersionMajor is the first integer and\nrequest.httpVersionMinor is the second.\n\n\n

\n" - }, - { - "textRaw": "request.connection", - "name": "connection", - "desc": "

The net.Socket object associated with the connection.\n\n\n

\n

With HTTPS support, use request.connection.verifyPeer() and\nrequest.connection.getPeerCertificate() to obtain the client's\nauthentication details.\n\n\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "request.setEncoding([encoding])", - "type": "method", - "name": "setEncoding", - "desc": "

Set the encoding for the request body. Either 'utf8' or 'binary'. Defaults\nto null, which means that the 'data' event will emit a Buffer object..\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "request.pause()", - "type": "method", - "name": "pause", - "desc": "

Pauses request from emitting events. Useful to throttle back an upload.\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "request.resume()", - "type": "method", - "name": "resume", - "desc": "

Resumes a paused request.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - }, - { - "textRaw": "Class: http.ServerResponse", - "type": "class", - "name": "http.ServerResponse", - "desc": "

This object is created internally by a HTTP server--not by the user. It is\npassed as the second parameter to the 'request' event.\n\n

\n

The response implements the Writable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", - "events": [ - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () { }\n\n

\n

Indicates that the underlaying connection was terminated before\nresponse.end() was called or able to flush.\n\n

\n", - "params": [] - } - ], - "methods": [ - { - "textRaw": "response.writeContinue()", - "type": "method", - "name": "writeContinue", - "desc": "

Sends a HTTP/1.1 100 Continue message to the client, indicating that\nthe request body should be sent. See the checkContinue event on\nServer.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "response.writeHead(statusCode, [reasonPhrase], [headers])", - "type": "method", - "name": "writeHead", - "desc": "

Sends a response header to the request. The status code is a 3-digit HTTP\nstatus code, like 404. The last argument, headers, are the response headers.\nOptionally one can give a human-readable reasonPhrase as the second\nargument.\n\n

\n

Example:\n\n

\n
var body = 'hello world';\nresponse.writeHead(200, {\n  'Content-Length': body.length,\n  'Content-Type': 'text/plain' });
\n

This method must only be called once on a message and it must\nbe called before response.end() is called.\n\n

\n

If you call response.write() or response.end() before calling this, the\nimplicit/mutable headers will be calculated and call this function for you.\n\n

\n

Note: that Content-Length is given in bytes not characters. The above example\nworks because the string 'hello world' contains only single byte characters.\nIf the body contains higher coded characters then Buffer.byteLength()\nshould be used to determine the number of bytes in a given encoding.\nAnd Node does not check whether Content-Length and the length of the body\nwhich has been transmitted are equal or not.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "statusCode" - }, - { - "name": "reasonPhrase", - "optional": true - }, - { - "name": "headers", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "response.setHeader(name, value)", - "type": "method", - "name": "setHeader", - "desc": "

Sets a single header value for implicit headers. If this header already exists\nin the to-be-sent headers, its value will be replaced. Use an array of strings\nhere if you need to send multiple headers with the same name.\n\n

\n

Example:\n\n

\n
response.setHeader("Content-Type", "text/html");
\n

or\n\n

\n
response.setHeader("Set-Cookie", ["type=ninja", "language=javascript"]);
\n", - "signatures": [ - { - "params": [ - { - "name": "name" - }, - { - "name": "value" - } - ] - } - ] - }, - { - "textRaw": "response.getHeader(name)", - "type": "method", - "name": "getHeader", - "desc": "

Reads out a header that's already been queued but not sent to the client. Note\nthat the name is case insensitive. This can only be called before headers get\nimplicitly flushed.\n\n

\n

Example:\n\n

\n
var contentType = response.getHeader('content-type');
\n", - "signatures": [ - { - "params": [ - { - "name": "name" - } - ] - } - ] - }, - { - "textRaw": "response.removeHeader(name)", - "type": "method", - "name": "removeHeader", - "desc": "

Removes a header that's queued for implicit sending.\n\n

\n

Example:\n\n

\n
response.removeHeader("Content-Encoding");
\n", - "signatures": [ - { - "params": [ - { - "name": "name" - } - ] - } - ] - }, - { - "textRaw": "response.write(chunk, [encoding])", - "type": "method", - "name": "write", - "desc": "

If this method is called and response.writeHead() has not been called, it will\nswitch to implicit header mode and flush the implicit headers.\n\n

\n

This sends a chunk of the response body. This method may\nbe called multiple times to provide successive parts of the body.\n\n

\n

chunk can be a string or a buffer. If chunk is a string,\nthe second parameter specifies how to encode it into a byte stream.\nBy default the encoding is 'utf8'.\n\n

\n

Note: This is the raw HTTP body and has nothing to do with\nhigher-level multi-part body encodings that may be used.\n\n

\n

The first time response.write() is called, it will send the buffered\nheader information and the first body to the client. The second time\nresponse.write() is called, Node assumes you're going to be streaming\ndata, and sends that separately. That is, the response is buffered up to the\nfirst chunk of body.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "chunk" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "response.addTrailers(headers)", - "type": "method", - "name": "addTrailers", - "desc": "

This method adds HTTP trailing headers (a header but at the end of the\nmessage) to the response.\n\n

\n

Trailers will only be emitted if chunked encoding is used for the\nresponse; if it is not (e.g., if the request was HTTP/1.0), they will\nbe silently discarded.\n\n

\n

Note that HTTP requires the Trailer header to be sent if you intend to\nemit trailers, with a list of the header fields in its value. E.g.,\n\n

\n
response.writeHead(200, { 'Content-Type': 'text/plain',\n                          'Trailer': 'Content-MD5' });\nresponse.write(fileData);\nresponse.addTrailers({'Content-MD5': "7895bf4b8828b55ceaf47747b4bca667"});\nresponse.end();
\n", - "signatures": [ - { - "params": [ - { - "name": "headers" - } - ] - } - ] - }, - { - "textRaw": "response.end([data], [encoding])", - "type": "method", - "name": "end", - "desc": "

This method signals to the server that all of the response headers and body\nhas been sent; that server should consider this message complete.\nThe method, response.end(), MUST be called on each\nresponse.\n\n

\n

If data is specified, it is equivalent to calling response.write(data, encoding)\nfollowed by response.end().\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data", - "optional": true - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - } - ], - "properties": [ - { - "textRaw": "response.statusCode", - "name": "statusCode", - "desc": "

When using implicit headers (not calling response.writeHead() explicitly), this property\ncontrols the status code that will be send to the client when the headers get\nflushed.\n\n

\n

Example:\n\n

\n
response.statusCode = 404;
\n

After response header was sent to the client, this property indicates the\nstatus code which was sent out.\n\n

\n" - } - ] - }, - { - "textRaw": "Class: http.Agent", - "type": "class", - "name": "http.Agent", - "desc": "

In node 0.5.3+ there is a new implementation of the HTTP Agent which is used\nfor pooling sockets used in HTTP client requests.\n\n

\n

Previously, a single agent instance help the pool for single host+port. The\ncurrent implementation now holds sockets for any number of hosts.\n\n

\n

The current HTTP Agent also defaults client requests to using\nConnection:keep-alive. If no pending HTTP requests are waiting on a socket\nto become free the socket is closed. This means that node's pool has the\nbenefit of keep-alive when under load but still does not require developers\nto manually close the HTTP clients using keep-alive.\n\n

\n

Sockets are removed from the agent's pool when the socket emits either a\n"close" event or a special "agentRemove" event. This means that if you intend\nto keep one HTTP request open for a long time and don't want it to stay in the\npool you can do something along the lines of:\n\n

\n
http.get(options, function(res) {\n  // Do stuff\n}).on("socket", function (socket) {\n  socket.emit("agentRemove");\n});
\n

Alternatively, you could just opt out of pooling entirely using agent:false:\n\n

\n
http.get({host:'localhost', port:80, path:'/', agent:false}, function (res) {\n  // Do stuff\n})
\n", - "properties": [ - { - "textRaw": "agent.maxSockets", - "name": "maxSockets", - "desc": "

By default set to 5. Determines how many concurrent sockets the agent can have \nopen per host.\n\n

\n" - }, - { - "textRaw": "agent.sockets", - "name": "sockets", - "desc": "

An object which contains arrays of sockets currently in use by the Agent. Do not \nmodify.\n\n

\n" - }, - { - "textRaw": "agent.requests", - "name": "requests", - "desc": "

An object which contains queues of requests that have not yet been assigned to \nsockets. Do not modify.\n\n

\n" - } - ] - }, - { - "textRaw": "Class: http.ClientRequest", - "type": "class", - "name": "http.ClientRequest", - "desc": "

This object is created internally and returned from http.request(). It\nrepresents an in-progress request whose header has already been queued. The\nheader is still mutable using the setHeader(name, value), getHeader(name),\nremoveHeader(name) API. The actual header will be sent along with the first\ndata chunk or when closing the connection.\n\n

\n

To get the response, add a listener for 'response' to the request object.\n'response' will be emitted from the request object when the response\nheaders have been received. The 'response' event is executed with one\nargument which is an instance of http.ClientResponse.\n\n

\n

During the 'response' event, one can add listeners to the\nresponse object; particularly to listen for the 'data' event. Note that\nthe 'response' event is called before any part of the response body is received,\nso there is no need to worry about racing to catch the first part of the\nbody. As long as a listener for 'data' is added during the 'response'\nevent, the entire body will be caught.\n\n\n

\n
// Good\nrequest.on('response', function (response) {\n  response.on('data', function (chunk) {\n    console.log('BODY: ' + chunk);\n  });\n});\n\n// Bad - misses all or part of the body\nrequest.on('response', function (response) {\n  setTimeout(function () {\n    response.on('data', function (chunk) {\n      console.log('BODY: ' + chunk);\n    });\n  }, 10);\n});
\n

Note: Node does not check whether Content-Length and the length of the body\nwhich has been transmitted are equal or not.\n\n

\n

The request implements the Writable Stream\ninterface. This is an EventEmitter with the following events:\n\n

\n", - "events": [ - { - "textRaw": "Event 'response'", - "type": "event", - "name": "response", - "desc": "

function (response) { }\n\n

\n

Emitted when a response is received to this request. This event is emitted only once. The\nresponse argument will be an instance of http.ClientResponse.\n\n

\n

Options:\n\n

\n
    \n
  • host: A domain name or IP address of the server to issue the request to.
    • \n
  • port: Port of remote server.
    • \n
  • socketPath: Unix Domain Socket (use one of host:port or socketPath)
    • \n
\n", - "params": [] - }, - { - "textRaw": "Event: 'socket'", - "type": "event", - "name": "socket", - "desc": "

function (socket) { }\n\n

\n

Emitted after a socket is assigned to this request.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'upgrade'", - "type": "event", - "name": "upgrade", - "desc": "

function (response, socket, head) { }\n\n

\n

Emitted each time a server responds to a request with an upgrade. If this\nevent isn't being listened for, clients receiving an upgrade header will have\ntheir connections closed.\n\n

\n

A client server pair that show you how to listen for the upgrade event using http.getAgent:\n\n

\n
var http = require('http');\nvar net = require('net');\n\n// Create an HTTP server\nvar srv = http.createServer(function (req, res) {\n  res.writeHead(200, {'Content-Type': 'text/plain'});\n  res.end('okay');\n});\nsrv.on('upgrade', function(req, socket, upgradeHead) {\n  socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\\r\\n' +\n               'Upgrade: WebSocket\\r\\n' +\n               'Connection: Upgrade\\r\\n' +\n               '\\r\\n\\r\\n');\n\n  socket.ondata = function(data, start, end) {\n    socket.write(data.toString('utf8', start, end), 'utf8'); // echo back\n  };\n});\n\n// now that server is running\nsrv.listen(1337, '127.0.0.1', function() {\n\n  // make a request\n  var options = {\n    port: 1337,\n    host: '127.0.0.1',\n    headers: {\n      'Connection': 'Upgrade',\n      'Upgrade': 'websocket'\n    }\n  };\n\n  var req = http.request(options);\n  req.end();\n\n  req.on('upgrade', function(res, socket, upgradeHead) {\n    console.log('got upgraded!');\n    socket.end();\n    process.exit(0);\n  });\n});
\n", - "params": [] - }, - { - "textRaw": "Event: 'continue'", - "type": "event", - "name": "continue", - "desc": "

function () { }\n\n

\n

Emitted when the server sends a '100 Continue' HTTP response, usually because\nthe request contained 'Expect: 100-continue'. This is an instruction that\nthe client should send the request body.\n\n

\n", - "params": [] - } - ], - "methods": [ - { - "textRaw": "request.write(chunk, [encoding])", - "type": "method", - "name": "write", - "desc": "

Sends a chunk of the body. By calling this method\nmany times, the user can stream a request body to a\nserver--in that case it is suggested to use the\n['Transfer-Encoding', 'chunked'] header line when\ncreating the request.\n\n

\n

The chunk argument should be a buffer or a string.\n\n

\n

The encoding argument is optional and only applies when chunk is a string.\nDefaults to 'utf8'.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "chunk" - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "request.end([data], [encoding])", - "type": "method", - "name": "end", - "desc": "

Finishes sending the request. If any parts of the body are\nunsent, it will flush them to the stream. If the request is\nchunked, this will send the terminating '0\\r\\n\\r\\n'.\n\n

\n

If data is specified, it is equivalent to calling\nrequest.write(data, encoding) followed by request.end().\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data", - "optional": true - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "request.abort()", - "type": "method", - "name": "abort", - "desc": "

Aborts a request. (New since v0.3.8.)\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "request.setTimeout(timeout, [callback])", - "type": "method", - "name": "setTimeout", - "desc": "

Once a socket is assigned to this request and is connected \nsocket.setTimeout(timeout, [callback])\nwill be called.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "timeout" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "request.setNoDelay([noDelay])", - "type": "method", - "name": "setNoDelay", - "desc": "

Once a socket is assigned to this request and is connected \nsocket.setNoDelay(noDelay)\nwill be called.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "noDelay", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "request.setSocketKeepAlive([enable], [initialDelay])", - "type": "method", - "name": "setSocketKeepAlive", - "desc": "

Once a socket is assigned to this request and is connected \nsocket.setKeepAlive(enable, [initialDelay])\nwill be called.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "enable", - "optional": true - }, - { - "name": "initialDelay", - "optional": true - } - ] - } - ] - } - ] - } - ], - "properties": [ - { - "textRaw": "http.globalAgent", - "name": "globalAgent", - "desc": "

Global instance of Agent which is used as the default for all http client\nrequests.\n\n\n

\n" - }, - { - "textRaw": "http.ClientResponse", - "name": "ClientResponse", - "desc": "

This object is created when making a request with http.request(). It is\npassed to the 'response' event of the request object.\n\n

\n

The response implements the Readable Stream\ninterface. This is an EventEmitter with the following events:\n\n\n

\n", - "events": [ - { - "textRaw": "Event: 'data'", - "type": "event", - "name": "data", - "desc": "

function (chunk) { }\n\n

\n

Emitted when a piece of the message body is received.\n\n

\n

Note that the data will be lost if there is no listener when a\nClientResponse emits a 'data' event.\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'end'", - "type": "event", - "name": "end", - "desc": "

function () { }\n\n

\n

Emitted exactly once for each message. No arguments. After\nemitted no other events will be emitted on the response.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function (err) { }\n\n

\n

Indicates that the underlaying connection was terminated before\nend event was emitted.\nSee http.ServerRequest's 'close' event for more\ninformation.\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "response.statusCode", - "name": "statusCode", - "desc": "

The 3-digit HTTP response status code. E.G. 404.\n\n

\n" - }, - { - "textRaw": "response.httpVersion", - "name": "httpVersion", - "desc": "

The HTTP version of the connected-to server. Probably either\n'1.1' or '1.0'.\nAlso response.httpVersionMajor is the first integer and\nresponse.httpVersionMinor is the second.\n\n

\n" - }, - { - "textRaw": "response.headers", - "name": "headers", - "desc": "

The response headers object.\n\n

\n" - }, - { - "textRaw": "response.trailers", - "name": "trailers", - "desc": "

The response trailers object. Only populated after the 'end' event.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "response.setEncoding([encoding])", - "type": "method", - "name": "setEncoding", - "desc": "

Set the encoding for the response body. Either 'utf8', 'ascii', or\n'base64'. Defaults to null, which means that the 'data' event will emit\na Buffer object.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "response.pause()", - "type": "method", - "name": "pause", - "desc": "

Pauses response from emitting events. Useful to throttle back a download.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "response.resume()", - "type": "method", - "name": "resume", - "desc": "

Resumes a paused response.\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - } - ], - "type": "module", - "displayName": "HTTP" - } - ] -} --- a/doc/api/api/https.html +++ /dev/null @@ -1,285 +0,0 @@ - - - - - HTTPS Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

HTTPS#

-
Stability: 3 - Stable
-

HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a -separate module. - -

-

Class: https.Server#

-

This class is a subclass of tls.Server and emits events same as -http.Server. See http.Server for more information. - -

-

https.createServer(options, [requestListener])#

-

Returns a new HTTPS web server object. The options is similar to -tls.createServer(). The requestListener is a function which is -automatically added to the 'request' event. - -

-

Example: - -

-
// curl -k https://localhost:8000/
-var https = require('https');
-var fs = require('fs');
-
-var options = {
-  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
-  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
-};
-
-https.createServer(options, function (req, res) {
-  res.writeHead(200);
-  res.end("hello world\n");
-}).listen(8000);
-

Or - -

-
var https = require('https');
-var fs = require('fs');
-
-var options = {
-  pfx: fs.readFileSync('server.pfx')
-};
-
-https.createServer(options, function (req, res) {
-  res.writeHead(200);
-  res.end("hello world\n");
-}).listen(8000);
-

https.request(options, callback)#

-

Makes a request to a secure web server. -All options from http.request() are valid. - -

-

Example: - -

-
var https = require('https');
-
-var options = {
-  host: 'encrypted.google.com',
-  port: 443,
-  path: '/',
-  method: 'GET'
-};
-
-var req = https.request(options, function(res) {
-  console.log("statusCode: ", res.statusCode);
-  console.log("headers: ", res.headers);
-
-  res.on('data', function(d) {
-    process.stdout.write(d);
-  });
-});
-req.end();
-
-req.on('error', function(e) {
-  console.error(e);
-});
-

The options argument has the following options - -

-
    -
  • host: IP or domain of host to make request to. Defaults to 'localhost'.
    • -
  • port: port of host to request to. Defaults to 443.
    • -
  • path: Path to request. Default '/'.
    • -

  • method: HTTP request method. Default 'GET'.

    -
    • -

  • host: A domain name or IP address of the server to issue the request to. -Defaults to 'localhost'.

    -
    • -
  • hostname: To support url.parse() hostname is preferred over host
    • -
  • port: Port of remote server. Defaults to 443.
    • -
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • -
  • path: Request path. Defaults to '/'. Should include query string if any. -E.G. '/index.html?page=12'
    • -
  • headers: An object containing request headers.
    • -
  • auth: Basic authentication i.e. 'user:password' to compute an -Authorization header.
    • -
  • agent: Controls Agent behavior. When an Agent is -used request will default to Connection: keep-alive. Possible values:
      -
    • undefined (default): use globalAgent for this -host and port.
      • -
    • Agent object: explicitly use the passed in Agent.
      • -
    • false: opts out of connection pooling with an Agent, defaults request to -Connection: close.
      • -
    -
    • -
-

The following options from tls.connect() can also be -specified. However, a globalAgent silently ignores these. - -

-
    -
  • pfx: Certificate, Private key and CA certificates to use for SSL. Default null.
    • -
  • key: Private key to use for SSL. Default null.
    • -
  • passphrase: A string of passphrase for the private key or pfx. Default null.
    • -
  • cert: Public x509 certificate to use. Default null.
    • -
  • ca: An authority certificate or array of authority certificates to check -the remote host against.
    • -
-

In order to specify these options, use a custom Agent. - -

-

Example: - -

-
var options = {
-  host: 'encrypted.google.com',
-  port: 443,
-  path: '/',
-  method: 'GET',
-  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
-  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
-};
-options.agent = new https.Agent(options);
-
-var req = https.request(options, function(res) {
-  ...
-}
-

Or does not use an Agent. - -

-

Example: - -

-
var options = {
-  host: 'encrypted.google.com',
-  port: 443,
-  path: '/',
-  method: 'GET',
-  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
-  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),
-  agent: false
-};
-
-var req = https.request(options, function(res) {
-  ...
-}
-

https.get(options, callback)#

-

Like http.get() but for HTTPS. - -

-

Example: - -

-
var https = require('https');
-
-https.get({ host: 'encrypted.google.com', path: '/' }, function(res) {
-  console.log("statusCode: ", res.statusCode);
-  console.log("headers: ", res.headers);
-
-  res.on('data', function(d) {
-    process.stdout.write(d);
-  });
-
-}).on('error', function(e) {
-  console.error(e);
-});
-

Class: https.Agent#

-

An Agent object for HTTPS similar to http.Agent. -See https.request() for more information. - - -

-

https.globalAgent#

-

Global instance of https.Agent which is used as the default -for all HTTPS client requests. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/https.json +++ /dev/null @@ -1,92 +0,0 @@ -{ - "source": "doc/api/https.markdown", - "modules": [ - { - "textRaw": "HTTPS", - "name": "https", - "stability": 3, - "stabilityText": "Stable", - "desc": "

HTTPS is the HTTP protocol over TLS/SSL. In Node this is implemented as a\nseparate module.\n\n

\n", - "classes": [ - { - "textRaw": "Class: https.Server", - "type": "class", - "name": "https.Server", - "desc": "

This class is a subclass of tls.Server and emits events same as\nhttp.Server. See http.Server for more information.\n\n

\n" - }, - { - "textRaw": "Class: https.Agent", - "type": "class", - "name": "https.Agent", - "desc": "

An Agent object for HTTPS similar to http.Agent.\nSee https.request() for more information.\n\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "https.createServer(options, [requestListener])", - "type": "method", - "name": "createServer", - "desc": "

Returns a new HTTPS web server object. The options is similar to\ntls.createServer(). The requestListener is a function which is\nautomatically added to the 'request' event.\n\n

\n

Example:\n\n

\n
// curl -k https://localhost:8000/\nvar https = require('https');\nvar fs = require('fs');\n\nvar options = {\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\n\nhttps.createServer(options, function (req, res) {\n  res.writeHead(200);\n  res.end("hello world\\n");\n}).listen(8000);
\n

Or\n\n

\n
var https = require('https');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('server.pfx')\n};\n\nhttps.createServer(options, function (req, res) {\n  res.writeHead(200);\n  res.end("hello world\\n");\n}).listen(8000);
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "requestListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "https.request(options, callback)", - "type": "method", - "name": "request", - "desc": "

Makes a request to a secure web server.\nAll options from http.request() are valid.\n\n

\n

Example:\n\n

\n
var https = require('https');\n\nvar options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET'\n};\n\nvar req = https.request(options, function(res) {\n  console.log("statusCode: ", res.statusCode);\n  console.log("headers: ", res.headers);\n\n  res.on('data', function(d) {\n    process.stdout.write(d);\n  });\n});\nreq.end();\n\nreq.on('error', function(e) {\n  console.error(e);\n});
\n

The options argument has the following options\n\n

\n
    \n
  • host: IP or domain of host to make request to. Defaults to 'localhost'.
    • \n
  • port: port of host to request to. Defaults to 443.
    • \n
  • path: Path to request. Default '/'.
    • \n

  • method: HTTP request method. Default 'GET'.

    \n
    • \n

  • host: A domain name or IP address of the server to issue the request to.\nDefaults to 'localhost'.

    \n
    • \n
  • hostname: To support url.parse() hostname is preferred over host
    • \n
  • port: Port of remote server. Defaults to 443.
    • \n
  • method: A string specifying the HTTP request method. Defaults to 'GET'.
    • \n
  • path: Request path. Defaults to '/'. Should include query string if any.\nE.G. '/index.html?page=12'
    • \n
  • headers: An object containing request headers.
    • \n
  • auth: Basic authentication i.e. 'user:password' to compute an\nAuthorization header.
    • \n
  • agent: Controls Agent behavior. When an Agent is\nused request will default to Connection: keep-alive. Possible values:
      \n
    • undefined (default): use globalAgent for this\nhost and port.
      • \n
    • Agent object: explicitly use the passed in Agent.
      • \n
    • false: opts out of connection pooling with an Agent, defaults request to\nConnection: close.
      • \n
    \n
    • \n
\n

The following options from tls.connect() can also be\nspecified. However, a globalAgent silently ignores these.\n\n

\n
    \n
  • pfx: Certificate, Private key and CA certificates to use for SSL. Default null.
    • \n
  • key: Private key to use for SSL. Default null.
    • \n
  • passphrase: A string of passphrase for the private key or pfx. Default null.
    • \n
  • cert: Public x509 certificate to use. Default null.
    • \n
  • ca: An authority certificate or array of authority certificates to check\nthe remote host against.
    • \n
\n

In order to specify these options, use a custom Agent.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')\n};\noptions.agent = new https.Agent(options);\n\nvar req = https.request(options, function(res) {\n  ...\n}
\n

Or does not use an Agent.\n\n

\n

Example:\n\n

\n
var options = {\n  host: 'encrypted.google.com',\n  port: 443,\n  path: '/',\n  method: 'GET',\n  key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),\n  cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem'),\n  agent: false\n};\n\nvar req = https.request(options, function(res) {\n  ...\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "https.get(options, callback)", - "type": "method", - "name": "get", - "desc": "

Like http.get() but for HTTPS.\n\n

\n

Example:\n\n

\n
var https = require('https');\n\nhttps.get({ host: 'encrypted.google.com', path: '/' }, function(res) {\n  console.log("statusCode: ", res.statusCode);\n  console.log("headers: ", res.headers);\n\n  res.on('data', function(d) {\n    process.stdout.write(d);\n  });\n\n}).on('error', function(e) {\n  console.error(e);\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "callback" - } - ] - } - ] - } - ], - "properties": [ - { - "textRaw": "https.globalAgent", - "name": "globalAgent", - "desc": "

Global instance of https.Agent which is used as the default\nfor all HTTPS client requests.\n

\n" - } - ], - "type": "module", - "displayName": "HTTPS" - } - ] -} --- a/doc/api/api/index.html +++ /dev/null @@ -1,127 +0,0 @@ - - - - - Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - - -
- - - - - - - - - - --- a/doc/api/api/index.json +++ /dev/null @@ -1,382 +0,0 @@ -{ - "source": "doc/api/index.markdown", - "desc": [ - { - "type": "list_start", - "ordered": false - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[About these Docs](documentation.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Synopsis](synopsis.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Globals](globals.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[STDIO](stdio.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Timers](timers.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Modules](modules.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[C/C++ Addons](addons.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Process](process.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Utilities](util.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Events](events.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Buffer](buffer.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Stream](stream.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Crypto](crypto.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[TLS/SSL](tls.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[String Decoder](string_decoder.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[File System](fs.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Path](path.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Net](net.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[UDP/Datagram](dgram.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[DNS](dns.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[HTTP](http.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[HTTPS](https.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[URL](url.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Query Strings](querystring.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Readline](readline.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[REPL](repl.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[VM](vm.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Child Processes](child_process.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Assertion Testing](assert.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[TTY](tty.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[ZLIB](zlib.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[OS](os.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Debugger](debugger.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Cluster](cluster.html)" - }, - { - "type": "list_item_end" - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "Appendixes" - }, - { - "type": "list_start", - "ordered": false - }, - { - "type": "list_item_start" - }, - { - "type": "text", - "text": "[Appendix 1: Recommended Third-party Modules](appendix_1.html)" - }, - { - "type": "space" - }, - { - "type": "list_item_end" - }, - { - "type": "list_end" - }, - { - "type": "list_item_end" - }, - { - "type": "list_end" - } - ] -} --- a/doc/api/api/modules.html +++ /dev/null @@ -1,615 +0,0 @@ - - - - - Modules Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Modules#

-
Stability: 5 - Locked
- - -

Node has a simple module loading system. In Node, files and modules are in -one-to-one correspondence. As an example, foo.js loads the module -circle.js in the same directory. - -

-

The contents of foo.js: - -

-
var circle = require('./circle.js');
-console.log( 'The area of a circle of radius 4 is '
-           + circle.area(4));
-

The contents of circle.js: - -

-
var PI = Math.PI;
-
-exports.area = function (r) {
-  return PI * r * r;
-};
-
-exports.circumference = function (r) {
-  return 2 * PI * r;
-};
-

The module circle.js has exported the functions area() and -circumference(). To export an object, add to the special exports -object. - -

-

Variables -local to the module will be private. In this example the variable PI is -private to circle.js. - -

-

The module system is implemented in the require("module") module. - -

-

Cycles#

- - -

When there are circular require() calls, a module might not be -done being executed when it is returned. - -

-

Consider this situation: - -

-

a.js: - -

-
console.log('a starting');
-exports.done = false;
-var b = require('./b.js');
-console.log('in a, b.done = %j', b.done);
-exports.done = true;
-console.log('a done');
-

b.js: - -

-
console.log('b starting');
-exports.done = false;
-var a = require('./a.js');
-console.log('in b, a.done = %j', a.done);
-exports.done = true;
-console.log('b done');
-

main.js: - -

-
console.log('main starting');
-var a = require('./a.js');
-var b = require('./b.js');
-console.log('in main, a.done=%j, b.done=%j', a.done, b.done);
-

When main.js loads a.js, then a.js in turn loads b.js. At that -point, b.js tries to load a.js. In order to prevent an infinite -loop an unfinished copy of the a.js exports object is returned to the -b.js module. b.js then finishes loading, and its exports object is -provided to the a.js module. - -

-

By the time main.js has loaded both modules, they're both finished. -The output of this program would thus be: - -

-
$ node main.js
-main starting
-a starting
-b starting
-in b, a.done = false
-b done
-in a, b.done = true
-a done
-in main, a.done=true, b.done=true
-

If you have cyclic module dependencies in your program, make sure to -plan accordingly. - -

-

Core Modules#

- - -

Node has several modules compiled into the binary. These modules are -described in greater detail elsewhere in this documentation. - -

-

The core modules are defined in node's source in the lib/ folder. - -

-

Core modules are always preferentially loaded if their identifier is -passed to require(). For instance, require('http') will always -return the built in HTTP module, even if there is a file by that name. - -

-

File Modules#

- - -

If the exact filename is not found, then node will attempt to load the -required filename with the added extension of .js, .json, and then .node. - -

-

.js files are interpreted as JavaScript text files, and .json files are -parsed as JSON text files. .node files are interpreted as compiled addon -modules loaded with dlopen. - -

-

A module prefixed with '/' is an absolute path to the file. For -example, require('/home/marco/foo.js') will load the file at -/home/marco/foo.js. - -

-

A module prefixed with './' is relative to the file calling require(). -That is, circle.js must be in the same directory as foo.js for -require('./circle') to find it. - -

-

Without a leading '/' or './' to indicate a file, the module is either a -"core module" or is loaded from a node_modules folder. - -

-

Loading from node_modules Folders#

- - -

If the module identifier passed to require() is not a native module, -and does not begin with '/', '../', or './', then node starts at the -parent directory of the current module, and adds /node_modules, and -attempts to load the module from that location. - -

-

If it is not found there, then it moves to the parent directory, and so -on, until the root of the tree is reached. - -

-

For example, if the file at '/home/ry/projects/foo.js' called -require('bar.js'), then node would look in the following locations, in -this order: - -

-
    -
  • /home/ry/projects/node_modules/bar.js
    • -
  • /home/ry/node_modules/bar.js
    • -
  • /home/node_modules/bar.js
    • -
  • /node_modules/bar.js
    • -
-

This allows programs to localize their dependencies, so that they do not -clash. - -

-

Folders as Modules#

- - -

It is convenient to organize programs and libraries into self-contained -directories, and then provide a single entry point to that library. -There are three ways in which a folder may be passed to require() as -an argument. - -

-

The first is to create a package.json file in the root of the folder, -which specifies a main module. An example package.json file might -look like this: - -

-
{ "name" : "some-library",
-  "main" : "./lib/some-library.js" }
-

If this was in a folder at ./some-library, then -require('./some-library') would attempt to load -./some-library/lib/some-library.js. - -

-

This is the extent of Node's awareness of package.json files. - -

-

If there is no package.json file present in the directory, then node -will attempt to load an index.js or index.node file out of that -directory. For example, if there was no package.json file in the above -example, then require('./some-library') would attempt to load: - -

-
    -
  • ./some-library/index.js
    • -
  • ./some-library/index.node
    • -
-

Caching#

- - -

Modules are cached after the first time they are loaded. This means -(among other things) that every call to require('foo') will get -exactly the same object returned, if it would resolve to the same file. - -

-

Multiple calls to require('foo') may not cause the module code to be -executed multiple times. This is an important feature. With it, -"partially done" objects can be returned, thus allowing transitive -dependencies to be loaded even when they would cause cycles. - -

-

If you want to have a module execute code multiple times, then export a -function, and call that function. - -

-

Module Caching Caveats#

- - -

Modules are cached based on their resolved filename. Since modules may -resolve to a different filename based on the location of the calling -module (loading from node_modules folders), it is not a guarantee -that require('foo') will always return the exact same object, if it -would resolve to different files. - -

-

The module Object#

- - - -
    -
  • {Object}
    • -
-

In each module, the module free variable is a reference to the object -representing the current module. In particular -module.exports is the same as the exports object. -module isn't actually a global but rather local to each module. - -

-

module.exports#

-
    -
  • Object
    • -
-

The exports object is created by the Module system. Sometimes this is not -acceptable, many want their module to be an instance of some class. To do this -assign the desired export object to module.exports. For example suppose we -were making a module called a.js - -

-
var EventEmitter = require('events').EventEmitter;
-
-module.exports = new EventEmitter();
-
-// Do some work, and after some time emit
-// the 'ready' event from the module itself.
-setTimeout(function() {
-  module.exports.emit('ready');
-}, 1000);
-

Then in another file we could do - -

-
var a = require('./a');
-a.on('ready', function() {
-  console.log('module a is ready');
-});
-

Note that assignment to module.exports must be done immediately. It cannot be -done in any callbacks. This does not work: - -

-

x.js: - -

-
setTimeout(function() {
-  module.exports = { a: "hello" };
-}, 0);
-

y.js: - -

-
var x = require('./x');
-console.log(x.a);
-

module.require(id)#

-
    -
  • id String
    • -
  • Return: Object exports from the resolved module
    • -
-

The module.require method provides a way to load a module as if -require() was called from the original module. - -

-

Note that in order to do this, you must get a reference to the module -object. Since require() returns the exports, and the module is -typically only available within a specific module's code, it must be -explicitly exported in order to be used. - - -

-

module.id#

-
    -
  • String
    • -
-

The identifier for the module. Typically this is the fully resolved -filename. - - -

-

module.filename#

-
    -
  • String
    • -
-

The fully resolved filename to the module. - - -

-

module.loaded#

-
    -
  • Boolean
    • -
-

Whether or not the module is done loading, or is in the process of -loading. - - -

-

module.parent#

-
    -
  • Module Object
    • -
-

The module that required this one. - - -

-

module.children#

-
    -
  • Array
    • -
-

The module objects required by this one. - - - -

-

All Together...#

- - -

To get the exact filename that will be loaded when require() is called, use -the require.resolve() function. - -

-

Putting together all of the above, here is the high-level algorithm -in pseudocode of what require.resolve does: - -

-
require(X) from module at path Y
-1. If X is a core module,
-   a. return the core module
-   b. STOP
-2. If X begins with './' or '/' or '../'
-   a. LOAD_AS_FILE(Y + X)
-   b. LOAD_AS_DIRECTORY(Y + X)
-3. LOAD_NODE_MODULES(X, dirname(Y))
-4. THROW "not found"
-
-LOAD_AS_FILE(X)
-1. If X is a file, load X as JavaScript text.  STOP
-2. If X.js is a file, load X.js as JavaScript text.  STOP
-3. If X.node is a file, load X.node as binary addon.  STOP
-
-LOAD_AS_DIRECTORY(X)
-1. If X/package.json is a file,
-   a. Parse X/package.json, and look for "main" field.
-   b. let M = X + (json main field)
-   c. LOAD_AS_FILE(M)
-2. If X/index.js is a file, load X/index.js as JavaScript text.  STOP
-3. If X/index.node is a file, load X/index.node as binary addon.  STOP
-
-LOAD_NODE_MODULES(X, START)
-1. let DIRS=NODE_MODULES_PATHS(START)
-2. for each DIR in DIRS:
-   a. LOAD_AS_FILE(DIR/X)
-   b. LOAD_AS_DIRECTORY(DIR/X)
-
-NODE_MODULES_PATHS(START)
-1. let PARTS = path split(START)
-2. let ROOT = index of first instance of "node_modules" in PARTS, or 0
-3. let I = count of PARTS - 1
-4. let DIRS = []
-5. while I > ROOT,
-   a. if PARTS[I] = "node_modules" CONTINUE
-   c. DIR = path join(PARTS[0 .. I] + "node_modules")
-   b. DIRS = DIRS + DIR
-   c. let I = I - 1
-6. return DIRS
-

Loading from the global folders#

- - -

If the NODE_PATH environment variable is set to a colon-delimited list -of absolute paths, then node will search those paths for modules if they -are not found elsewhere. (Note: On Windows, NODE_PATH is delimited by -semicolons instead of colons.) - -

-

Additionally, node will search in the following locations: - -

-
    -
  • 1: $HOME/.node_modules
    • -
  • 2: $HOME/.node_libraries
    • -
  • 3: $PREFIX/lib/node
    • -
-

Where $HOME is the user's home directory, and $PREFIX is node's -configured installPrefix. - -

-

These are mostly for historic reasons. You are highly encouraged to -place your dependencies locally in node_modules folders. They will be -loaded faster, and more reliably. - -

-

Accessing the main module#

- - -

When a file is run directly from Node, require.main is set to its -module. That means that you can determine whether a file has been run -directly by testing - -

-
require.main === module
-

For a file foo.js, this will be true if run via node foo.js, but -false if run by require('./foo'). - -

-

Because module provides a filename property (normally equivalent to -__filename), the entry point of the current application can be obtained -by checking require.main.filename. - -

-

Addenda: Package Manager Tips#

- - -

The semantics of Node's require() function were designed to be general -enough to support a number of sane directory structures. Package manager -programs such as dpkg, rpm, and npm will hopefully find it possible to -build native packages from Node modules without modification. - -

-

Below we give a suggested directory structure that could work: - -

-

Let's say that we wanted to have the folder at -/usr/lib/node/<some-package>/<some-version> hold the contents of a -specific version of a package. - -

-

Packages can depend on one another. In order to install package foo, you -may have to install a specific version of package bar. The bar package -may itself have dependencies, and in some cases, these dependencies may even -collide or form cycles. - -

-

Since Node looks up the realpath of any modules it loads (that is, -resolves symlinks), and then looks for their dependencies in the -node_modules folders as described above, this situation is very simple to -resolve with the following architecture: - -

-
    -
  • /usr/lib/node/foo/1.2.3/ - Contents of the foo package, version 1.2.3.
    • -
  • /usr/lib/node/bar/4.3.2/ - Contents of the bar package that foo -depends on.
    • -
  • /usr/lib/node/foo/1.2.3/node_modules/bar - Symbolic link to -/usr/lib/node/bar/4.3.2/.
    • -
  • /usr/lib/node/bar/4.3.2/node_modules/* - Symbolic links to the packages -that bar depends on.
    • -
-

Thus, even if a cycle is encountered, or if there are dependency -conflicts, every module will be able to get a version of its dependency -that it can use. - -

-

When the code in the foo package does require('bar'), it will get the -version that is symlinked into /usr/lib/node/foo/1.2.3/node_modules/bar. -Then, when the code in the bar package calls require('quux'), it'll get -the version that is symlinked into -/usr/lib/node/bar/4.3.2/node_modules/quux. - -

-

Furthermore, to make the module lookup process even more optimal, rather -than putting packages directly in /usr/lib/node, we could put them in -/usr/lib/node_modules/<name>/<version>. Then node will not bother -looking for missing dependencies in /usr/node_modules or /node_modules. - -

-

In order to make modules available to the node REPL, it might be useful to -also add the /usr/lib/node_modules folder to the $NODE_PATH environment -variable. Since the module lookups using node_modules folders are all -relative, and based on the real path of the files making the calls to -require(), the packages themselves can be anywhere. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/modules.json +++ /dev/null @@ -1,156 +0,0 @@ -{ - "source": "doc/api/modules.markdown", - "modules": [ - { - "textRaw": "Modules", - "name": "module", - "stability": 5, - "stabilityText": "Locked", - "desc": "

Node has a simple module loading system. In Node, files and modules are in\none-to-one correspondence. As an example, foo.js loads the module\ncircle.js in the same directory.\n\n

\n

The contents of foo.js:\n\n

\n
var circle = require('./circle.js');\nconsole.log( 'The area of a circle of radius 4 is '\n           + circle.area(4));
\n

The contents of circle.js:\n\n

\n
var PI = Math.PI;\n\nexports.area = function (r) {\n  return PI * r * r;\n};\n\nexports.circumference = function (r) {\n  return 2 * PI * r;\n};
\n

The module circle.js has exported the functions area() and\ncircumference(). To export an object, add to the special exports\nobject.\n\n

\n

Variables\nlocal to the module will be private. In this example the variable PI is\nprivate to circle.js.\n\n

\n

The module system is implemented in the require("module") module.\n\n

\n", - "miscs": [ - { - "textRaw": "Cycles", - "name": "Cycles", - "type": "misc", - "desc": "

When there are circular require() calls, a module might not be\ndone being executed when it is returned.\n\n

\n

Consider this situation:\n\n

\n

a.js:\n\n

\n
console.log('a starting');\nexports.done = false;\nvar b = require('./b.js');\nconsole.log('in a, b.done = %j', b.done);\nexports.done = true;\nconsole.log('a done');
\n

b.js:\n\n

\n
console.log('b starting');\nexports.done = false;\nvar a = require('./a.js');\nconsole.log('in b, a.done = %j', a.done);\nexports.done = true;\nconsole.log('b done');
\n

main.js:\n\n

\n
console.log('main starting');\nvar a = require('./a.js');\nvar b = require('./b.js');\nconsole.log('in main, a.done=%j, b.done=%j', a.done, b.done);
\n

When main.js loads a.js, then a.js in turn loads b.js. At that\npoint, b.js tries to load a.js. In order to prevent an infinite\nloop an unfinished copy of the a.js exports object is returned to the\nb.js module. b.js then finishes loading, and its exports object is\nprovided to the a.js module.\n\n

\n

By the time main.js has loaded both modules, they're both finished.\nThe output of this program would thus be:\n\n

\n
$ node main.js\nmain starting\na starting\nb starting\nin b, a.done = false\nb done\nin a, b.done = true\na done\nin main, a.done=true, b.done=true
\n

If you have cyclic module dependencies in your program, make sure to\nplan accordingly.\n\n

\n" - }, - { - "textRaw": "Core Modules", - "name": "Core Modules", - "type": "misc", - "desc": "

Node has several modules compiled into the binary. These modules are\ndescribed in greater detail elsewhere in this documentation.\n\n

\n

The core modules are defined in node's source in the lib/ folder.\n\n

\n

Core modules are always preferentially loaded if their identifier is\npassed to require(). For instance, require('http') will always\nreturn the built in HTTP module, even if there is a file by that name.\n\n

\n" - }, - { - "textRaw": "File Modules", - "name": "File Modules", - "type": "misc", - "desc": "

If the exact filename is not found, then node will attempt to load the\nrequired filename with the added extension of .js, .json, and then .node.\n\n

\n

.js files are interpreted as JavaScript text files, and .json files are\nparsed as JSON text files. .node files are interpreted as compiled addon\nmodules loaded with dlopen.\n\n

\n

A module prefixed with '/' is an absolute path to the file. For\nexample, require('/home/marco/foo.js') will load the file at\n/home/marco/foo.js.\n\n

\n

A module prefixed with './' is relative to the file calling require().\nThat is, circle.js must be in the same directory as foo.js for\nrequire('./circle') to find it.\n\n

\n

Without a leading '/' or './' to indicate a file, the module is either a\n"core module" or is loaded from a node_modules folder.\n\n

\n" - }, - { - "textRaw": "Loading from `node_modules` Folders", - "name": "Loading from `node_modules` Folders", - "type": "misc", - "desc": "

If the module identifier passed to require() is not a native module,\nand does not begin with '/', '../', or './', then node starts at the\nparent directory of the current module, and adds /node_modules, and\nattempts to load the module from that location.\n\n

\n

If it is not found there, then it moves to the parent directory, and so\non, until the root of the tree is reached.\n\n

\n

For example, if the file at '/home/ry/projects/foo.js' called\nrequire('bar.js'), then node would look in the following locations, in\nthis order:\n\n

\n
    \n
  • /home/ry/projects/node_modules/bar.js
    • \n
  • /home/ry/node_modules/bar.js
    • \n
  • /home/node_modules/bar.js
    • \n
  • /node_modules/bar.js
    • \n
\n

This allows programs to localize their dependencies, so that they do not\nclash.\n\n

\n" - }, - { - "textRaw": "Folders as Modules", - "name": "Folders as Modules", - "type": "misc", - "desc": "

It is convenient to organize programs and libraries into self-contained\ndirectories, and then provide a single entry point to that library.\nThere are three ways in which a folder may be passed to require() as\nan argument.\n\n

\n

The first is to create a package.json file in the root of the folder,\nwhich specifies a main module. An example package.json file might\nlook like this:\n\n

\n
{ "name" : "some-library",\n  "main" : "./lib/some-library.js" }
\n

If this was in a folder at ./some-library, then\nrequire('./some-library') would attempt to load\n./some-library/lib/some-library.js.\n\n

\n

This is the extent of Node's awareness of package.json files.\n\n

\n

If there is no package.json file present in the directory, then node\nwill attempt to load an index.js or index.node file out of that\ndirectory. For example, if there was no package.json file in the above\nexample, then require('./some-library') would attempt to load:\n\n

\n
    \n
  • ./some-library/index.js
    • \n
  • ./some-library/index.node
    • \n
\n" - }, - { - "textRaw": "Caching", - "name": "Caching", - "type": "misc", - "desc": "

Modules are cached after the first time they are loaded. This means\n(among other things) that every call to require('foo') will get\nexactly the same object returned, if it would resolve to the same file.\n\n

\n

Multiple calls to require('foo') may not cause the module code to be\nexecuted multiple times. This is an important feature. With it,\n"partially done" objects can be returned, thus allowing transitive\ndependencies to be loaded even when they would cause cycles.\n\n

\n

If you want to have a module execute code multiple times, then export a\nfunction, and call that function.\n\n

\n", - "miscs": [ - { - "textRaw": "Module Caching Caveats", - "name": "Module Caching Caveats", - "type": "misc", - "desc": "

Modules are cached based on their resolved filename. Since modules may\nresolve to a different filename based on the location of the calling\nmodule (loading from node_modules folders), it is not a guarantee\nthat require('foo') will always return the exact same object, if it\nwould resolve to different files.\n\n

\n" - } - ] - }, - { - "textRaw": "All Together...", - "name": "All Together...", - "type": "misc", - "desc": "

To get the exact filename that will be loaded when require() is called, use\nthe require.resolve() function.\n\n

\n

Putting together all of the above, here is the high-level algorithm\nin pseudocode of what require.resolve does:\n\n

\n
require(X) from module at path Y\n1. If X is a core module,\n   a. return the core module\n   b. STOP\n2. If X begins with './' or '/' or '../'\n   a. LOAD_AS_FILE(Y + X)\n   b. LOAD_AS_DIRECTORY(Y + X)\n3. LOAD_NODE_MODULES(X, dirname(Y))\n4. THROW "not found"\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as JavaScript text.  STOP\n2. If X.js is a file, load X.js as JavaScript text.  STOP\n3. If X.node is a file, load X.node as binary addon.  STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n   a. Parse X/package.json, and look for "main" field.\n   b. let M = X + (json main field)\n   c. LOAD_AS_FILE(M)\n2. If X/index.js is a file, load X/index.js as JavaScript text.  STOP\n3. If X/index.node is a file, load X/index.node as binary addon.  STOP\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS=NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n   a. LOAD_AS_FILE(DIR/X)\n   b. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let ROOT = index of first instance of "node_modules" in PARTS, or 0\n3. let I = count of PARTS - 1\n4. let DIRS = []\n5. while I > ROOT,\n   a. if PARTS[I] = "node_modules" CONTINUE\n   c. DIR = path join(PARTS[0 .. I] + "node_modules")\n   b. DIRS = DIRS + DIR\n   c. let I = I - 1\n6. return DIRS
\n" - }, - { - "textRaw": "Loading from the global folders", - "name": "Loading from the global folders", - "type": "misc", - "desc": "

If the NODE_PATH environment variable is set to a colon-delimited list\nof absolute paths, then node will search those paths for modules if they\nare not found elsewhere. (Note: On Windows, NODE_PATH is delimited by\nsemicolons instead of colons.)\n\n

\n

Additionally, node will search in the following locations:\n\n

\n
    \n
  • 1: $HOME/.node_modules
    • \n
  • 2: $HOME/.node_libraries
    • \n
  • 3: $PREFIX/lib/node
    • \n
\n

Where $HOME is the user's home directory, and $PREFIX is node's\nconfigured installPrefix.\n\n

\n

These are mostly for historic reasons. You are highly encouraged to\nplace your dependencies locally in node_modules folders. They will be\nloaded faster, and more reliably.\n\n

\n" - }, - { - "textRaw": "Accessing the main module", - "name": "Accessing the main module", - "type": "misc", - "desc": "

When a file is run directly from Node, require.main is set to its\nmodule. That means that you can determine whether a file has been run\ndirectly by testing\n\n

\n
require.main === module
\n

For a file foo.js, this will be true if run via node foo.js, but\nfalse if run by require('./foo').\n\n

\n

Because module provides a filename property (normally equivalent to\n__filename), the entry point of the current application can be obtained\nby checking require.main.filename.\n\n

\n" - }, - { - "textRaw": "Addenda: Package Manager Tips", - "name": "Addenda: Package Manager Tips", - "type": "misc", - "desc": "

The semantics of Node's require() function were designed to be general\nenough to support a number of sane directory structures. Package manager\nprograms such as dpkg, rpm, and npm will hopefully find it possible to\nbuild native packages from Node modules without modification.\n\n

\n

Below we give a suggested directory structure that could work:\n\n

\n

Let's say that we wanted to have the folder at\n/usr/lib/node/<some-package>/<some-version> hold the contents of a\nspecific version of a package.\n\n

\n

Packages can depend on one another. In order to install package foo, you\nmay have to install a specific version of package bar. The bar package\nmay itself have dependencies, and in some cases, these dependencies may even\ncollide or form cycles.\n\n

\n

Since Node looks up the realpath of any modules it loads (that is,\nresolves symlinks), and then looks for their dependencies in the\nnode_modules folders as described above, this situation is very simple to\nresolve with the following architecture:\n\n

\n
    \n
  • /usr/lib/node/foo/1.2.3/ - Contents of the foo package, version 1.2.3.
    • \n
  • /usr/lib/node/bar/4.3.2/ - Contents of the bar package that foo\ndepends on.
    • \n
  • /usr/lib/node/foo/1.2.3/node_modules/bar - Symbolic link to\n/usr/lib/node/bar/4.3.2/.
    • \n
  • /usr/lib/node/bar/4.3.2/node_modules/* - Symbolic links to the packages\nthat bar depends on.
    • \n
\n

Thus, even if a cycle is encountered, or if there are dependency\nconflicts, every module will be able to get a version of its dependency\nthat it can use.\n\n

\n

When the code in the foo package does require('bar'), it will get the\nversion that is symlinked into /usr/lib/node/foo/1.2.3/node_modules/bar.\nThen, when the code in the bar package calls require('quux'), it'll get\nthe version that is symlinked into\n/usr/lib/node/bar/4.3.2/node_modules/quux.\n\n

\n

Furthermore, to make the module lookup process even more optimal, rather\nthan putting packages directly in /usr/lib/node, we could put them in\n/usr/lib/node_modules/<name>/<version>. Then node will not bother\nlooking for missing dependencies in /usr/node_modules or /node_modules.\n\n

\n

In order to make modules available to the node REPL, it might be useful to\nalso add the /usr/lib/node_modules folder to the $NODE_PATH environment\nvariable. Since the module lookups using node_modules folders are all\nrelative, and based on the real path of the files making the calls to\nrequire(), the packages themselves can be anywhere.\n

\n" - } - ], - "vars": [ - { - "textRaw": "The `module` Object", - "name": "module", - "type": "var", - "desc": "

In each module, the module free variable is a reference to the object\nrepresenting the current module. In particular\nmodule.exports is the same as the exports object.\nmodule isn't actually a global but rather local to each module.\n\n

\n", - "properties": [ - { - "textRaw": "`exports` {Object} ", - "name": "exports", - "desc": "

The exports object is created by the Module system. Sometimes this is not\nacceptable, many want their module to be an instance of some class. To do this\nassign the desired export object to module.exports. For example suppose we\nwere making a module called a.js\n\n

\n
var EventEmitter = require('events').EventEmitter;\n\nmodule.exports = new EventEmitter();\n\n// Do some work, and after some time emit\n// the 'ready' event from the module itself.\nsetTimeout(function() {\n  module.exports.emit('ready');\n}, 1000);
\n

Then in another file we could do\n\n

\n
var a = require('./a');\na.on('ready', function() {\n  console.log('module a is ready');\n});
\n

Note that assignment to module.exports must be done immediately. It cannot be\ndone in any callbacks. This does not work:\n\n

\n

x.js:\n\n

\n
setTimeout(function() {\n  module.exports = { a: "hello" };\n}, 0);
\n

y.js:\n\n

\n
var x = require('./x');\nconsole.log(x.a);
\n" - }, - { - "textRaw": "`id` {String} ", - "name": "id", - "desc": "

The identifier for the module. Typically this is the fully resolved\nfilename.\n\n\n

\n" - }, - { - "textRaw": "`filename` {String} ", - "name": "filename", - "desc": "

The fully resolved filename to the module.\n\n\n

\n" - }, - { - "textRaw": "`loaded` {Boolean} ", - "name": "loaded", - "desc": "

Whether or not the module is done loading, or is in the process of\nloading.\n\n\n

\n" - }, - { - "textRaw": "`parent` {Module Object} ", - "name": "parent", - "desc": "

The module that required this one.\n\n\n

\n" - }, - { - "textRaw": "`children` {Array} ", - "name": "children", - "desc": "

The module objects required by this one.\n\n\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "module.require(id)", - "type": "method", - "name": "require", - "signatures": [ - { - "return": { - "textRaw": "Return: {Object} `exports` from the resolved module ", - "name": "return", - "type": "Object", - "desc": "`exports` from the resolved module" - }, - "params": [ - { - "textRaw": "`id` {String} ", - "name": "id", - "type": "String" - } - ] - }, - { - "params": [ - { - "name": "id" - } - ] - } - ], - "desc": "

The module.require method provides a way to load a module as if\nrequire() was called from the original module.\n\n

\n

Note that in order to do this, you must get a reference to the module\nobject. Since require() returns the exports, and the module is\ntypically only available within a specific module's code, it must be\nexplicitly exported in order to be used.\n\n\n

\n" - } - ] - } - ], - "type": "module", - "displayName": "module" - } - ] -} --- a/doc/api/api/net.html +++ /dev/null @@ -1,607 +0,0 @@ - - - - - net Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

net#

-
Stability: 3 - Stable
-

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'); - -

-

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

-

Creates a new TCP server. The connectionListener argument is -automatically set as a listener for the 'connection' -event. - -

-

options is an object with the following defaults: - -

-
{ allowHalfOpen: false
-}
-

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. - -

-

Here is an example of a echo server which listens for connections -on port 8124: - -

-
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');
-});
-

Test this by using telnet: - -

-
telnet localhost 8124
-

To listen on the socket /tmp/echo.sock the third line from the last would -just be changed to - -

-
server.listen('/tmp/echo.sock', function() { //'listening' listener
-

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

-
nc -U /tmp/echo.sock
-

net.connect(arguments...)#

-

net.createConnection(arguments...)#

-

Construct a new socket object and opens a socket to the given location. When -the socket is established the 'connect' event will be -emitted. - -

-

The arguments for these methods change the type of connection: - -

-
    -
  • net.connect(port, [host], [connectListener])
    • -

  • net.createConnection(port, [host], [connectListener])

    -

    Creates a TCP connection to port on host. If host is omitted, -'localhost' will be assumed.

    -
    • -

  • net.connect(path, [connectListener])

    -
    • -

  • net.createConnection(path, [connectListener])

    -

    Creates unix socket connection to path.

    -
    • -
-

The connectListener parameter will be added as an listener for the -'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 connect on the socket /tmp/echo.sock the second line would just be -changed to - -

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

Class: net.Server#

-

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. When the server has been bound, -'listening' event will be emitted. -the last parameter listeningListener will be added as an listener for the -'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 -would be to wait a second and then try again. This can be done with - -

-
server.on('error', function (e) {
-  if (e.code == 'EADDRINUSE') {
-    console.log('Address in use, retrying...');
-    setTimeout(function () {
-      server.close();
-      server.listen(PORT, HOST);
-    }, 1000);
-  }
-});
-

(Note: All sockets in Node set SO_REUSEADDR already) - - -

-

server.listen(path, [listeningListener])#

-

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

-

This function is asynchronous. When the server has been bound, -'listening' event will be emitted. -the last parameter listeningListener will be added as an listener for the -'listening' event. - -

-

server.close()#

-

Stops the server from accepting new connections. This function is -asynchronous, the server is finally closed when the server emits a 'close' -event. - - -

-

server.address()#

-

Returns the bound address and port of the server as reported by the operating system. -Useful to find which port was assigned when giving getting an OS-assigned address. -Returns an object with two properties, e.g. {"address":"127.0.0.1", "port":2121} - -

-

Example: - -

-
var server = net.createServer(function (socket) {
-  socket.end("goodbye\n");
-});
-
-// grab a random port.
-server.listen(function() {
-  address = server.address();
-  console.log("opened server on %j", address);
-});
-

Don't call server.address() until the 'listening' event has been emitted. - -

-

server.maxConnections#

-

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

-

server.connections#

-

The number of concurrent connections on the server. - - -

-

net.Server is an EventEmitter with the following events: - -

-

Event: 'listening'#

-

Emitted when the server has been bound after calling server.listen. - -

-

Event: 'connection'#

-
    -
  • Socket object The connection object
    • -
-

Emitted when a new connection is made. socket is an instance of -net.Socket. - -

-

Event: 'close'#

-

Emitted when the server closes. - -

-

Event: 'error'#

-
    -
  • Error Object
    • -
-

Emitted when an error occurs. The 'close' event will be called directly -following this event. See example in discussion of server.listen. - -

-

Class: net.Socket#

-

This object is an abstraction of a TCP or UNIX socket. net.Socket -instances implement a duplex Stream interface. They can be created by the -user and used as a client (with connect()) or they can be created by Node -and passed to the user through the 'connection' event of a server. - -

-

new net.Socket([options])#

-

Construct a new socket object. - -

-

options is an object with the following defaults: - -

-
{ fd: null
-  type: null
-  allowHalfOpen: false
-}
-

fd allows you to specify the existing file descriptor of socket. type -specified underlying protocol. It can be 'tcp4', 'tcp6', or 'unix'. -About allowHalfOpen, refer to createServer() and 'end' event. - -

-

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, -localhost will be assumed. If a path is given, the socket will be -opened as a unix socket to that path. - -

-

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 -the exception. - -

-

The connectListener parameter will be added as an listener for the -'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). - -

-

The consequence of this internal buffering is that memory may grow. This -property shows the number of characters currently buffered to be written. -(Number of characters is approximately equal to the number of bytes to be -written, but the buffer may contain strings, and the strings are lazily -encoded, so the exact number of bytes is not known.) - -

-

Users who experience large or growing bufferSize should attempt to -"throttle" the data flows in their program with pause() and resume(). - - -

-

socket.setEncoding([encoding])#

-

Sets the encoding (either 'ascii', 'utf8', or 'base64') for data that is -received. Defaults to null. - -

-

socket.setSecure()#

-

This function has been removed in v0.3. It used to upgrade the connection to -SSL/TLS. See the TLS section for the new API. - - -

-

socket.write(data, [encoding], [callback])#

-

Sends data on the socket. The second parameter specifies the encoding in the -case of a string--it defaults to UTF8 encoding. - -

-

Returns true if the entire data was flushed successfully to the kernel -buffer. Returns false if all or part of the data was queued in user memory. -'drain' will be emitted when the buffer is again free. - -

-

The optional callback parameter will be executed when the data is finally -written out - this may not be immediately. - -

-

socket.end([data], [encoding])#

-

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(). - -

-

socket.destroy()#

-

Ensures that no more I/O activity happens on this socket. Only necessary in -case of errors (parse error or so). - -

-

socket.pause()#

-

Pauses the reading of data. That is, 'data' events will not be emitted. -Useful to throttle back an upload. - -

-

socket.resume()#

-

Resumes reading after a call to pause(). - -

-

socket.setTimeout(timeout, [callback])#

-

Sets the socket to timeout after timeout milliseconds of inactivity on -the socket. By default net.Socket do not have a timeout. - -

-

When an idle timeout is triggered the socket will receive a 'timeout' -event but the connection will not be severed. The user must manually end() -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. - -

-

socket.setNoDelay([noDelay])#

-

Disables the Nagle algorithm. By default TCP connections use the Nagle -algorithm, they buffer data before sending it off. Setting true for -noDelay will immediately fire off data each time socket.write() is called. -noDelay defaults to true. - -

-

socket.setKeepAlive([enable], [initialDelay])#

-

Enable/disable keep-alive functionality, and optionally set the initial -delay before the first keepalive probe is sent on an idle socket. -enable defaults to false. - -

-

Set initialDelay (in milliseconds) to set the delay between the last -data packet received and the first keepalive probe. Setting 0 for -initialDelay will leave the value unchanged from the default -(or previous) setting. Defaults to 0. - -

-

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} - -

-

socket.remoteAddress#

-

The string representation of the remote IP address. For example, -'74.125.127.100' or '2001:4860:a005::68'. - -

-

socket.remotePort#

-

The numeric representation of the remote port. For example, -80 or 21. - -

-

socket.bytesRead#

-

The amount of received bytes. - -

-

socket.bytesWritten#

-

The amount of bytes sent. - - -

-

net.Socket instances are EventEmitters with the following events: - -

-

Event: 'connect'#

-

Emitted when a socket connection is successfully established. -See connect(). - -

-

Event: 'data'#

-
    -
  • Buffer object
    • -
-

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 section for more -information.) - -

-

Note that the data will be lost if there is no listener when a Socket -emits a 'data' event. - -

-

Event: 'end'#

-

Emitted when the other end of the socket sends a FIN packet. - -

-

By default (allowHalfOpen == false) the socket will destroy its file -descriptor once it has written out its pending write queue. However, by -setting allowHalfOpen == true the socket will not automatically end() -its side allowing the user to write arbitrary amounts of data, with the -caveat that the user is required to end() their side now. - - -

-

Event: 'timeout'#

-

Emitted if the socket times out from inactivity. This is only to notify that -the socket has been idle. The user must manually close the connection. - -

-

See also: socket.setTimeout() - - -

-

Event: 'drain'#

-

Emitted when the write buffer becomes empty. Can be used to throttle uploads. - -

-

See also: the return values of socket.write() - -

-

Event: 'error'#

-
    -
  • Error object
    • -
-

Emitted when an error occurs. The 'close' event will be called directly -following this event. - -

-

Event: 'close'#

-
    -
  • had_error Boolean true if the socket had a transmission error
    • -
-

Emitted once the socket is fully closed. The argument had_error is a boolean -which says if the socket was closed due to a transmission error. - -

-

net.isIP(input)#

-

Tests if input is an IP address. Returns 0 for invalid strings, -returns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses. - - -

-

net.isIPv4(input)#

-

Returns true if input is a version 4 IP address, otherwise returns false. - - -

-

net.isIPv6(input)#

-

Returns true if input is a version 6 IP address, otherwise returns false. - -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/net.json +++ /dev/null @@ -1,558 +0,0 @@ -{ - "source": "doc/api/net.markdown", - "modules": [ - { - "textRaw": "net", - "name": "net", - "stability": 3, - "stabilityText": "Stable", - "desc": "

The net module provides you with an asynchronous network wrapper. It contains\nmethods for creating both servers and clients (called streams). You can include\nthis module with require('net');\n\n

\n", - "methods": [ - { - "textRaw": "net.createServer([options], [connectionListener])", - "type": "method", - "name": "createServer", - "desc": "

Creates a new TCP server. The connectionListener argument is\nautomatically set as a listener for the 'connection'\nevent.\n\n

\n

options is an object with the following defaults:\n\n

\n
{ allowHalfOpen: false\n}
\n

If allowHalfOpen is true, then the socket won't automatically send FIN\npacket when the other end of the socket sends a FIN packet. The socket becomes\nnon-readable, but still writable. You should call the end() method explicitly.\nSee 'end' event for more information.\n\n

\n

Here is an example of a echo server which listens for connections\non port 8124:\n\n

\n
var net = require('net');\nvar server = net.createServer(function(c) { //'connection' listener\n  console.log('server connected');\n  c.on('end', function() {\n    console.log('server disconnected');\n  });\n  c.write('hello\\r\\n');\n  c.pipe(c);\n});\nserver.listen(8124, function() { //'listening' listener\n  console.log('server bound');\n});
\n

Test this by using telnet:\n\n

\n
telnet localhost 8124
\n

To listen on the socket /tmp/echo.sock the third line from the last would\njust be changed to\n\n

\n
server.listen('/tmp/echo.sock', function() { //'listening' listener
\n

Use nc to connect to a UNIX domain socket server:\n\n

\n
nc -U /tmp/echo.sock
\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - }, - { - "name": "connectionListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "net.connect(arguments...)", - "type": "method", - "name": "connect", - "desc": "

Construct a new socket object and opens a socket to the given location. When\nthe socket is established the 'connect' event will be\nemitted.\n\n

\n

The arguments for these methods change the type of connection:\n\n

\n
    \n
  • net.connect(port, [host], [connectListener])
    • \n

  • net.createConnection(port, [host], [connectListener])

    \n

    Creates a TCP connection to port on host. If host is omitted,\n'localhost' will be assumed.

    \n
    • \n

  • net.connect(path, [connectListener])

    \n
    • \n

  • net.createConnection(path, [connectListener])

    \n

    Creates unix socket connection to path.

    \n
    • \n
\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n

\n

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

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

To connect on the socket /tmp/echo.sock the second line would just be\nchanged to\n\n

\n
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
\n", - "signatures": [ - { - "params": [ - { - "name": "arguments..." - } - ] - }, - { - "params": [ - { - "name": "arguments..." - } - ] - } - ] - }, - { - "textRaw": "net.createConnection(arguments...)", - "type": "method", - "name": "createConnection", - "desc": "

Construct a new socket object and opens a socket to the given location. When\nthe socket is established the 'connect' event will be\nemitted.\n\n

\n

The arguments for these methods change the type of connection:\n\n

\n
    \n
  • net.connect(port, [host], [connectListener])
    • \n

  • net.createConnection(port, [host], [connectListener])

    \n

    Creates a TCP connection to port on host. If host is omitted,\n'localhost' will be assumed.

    \n
    • \n

  • net.connect(path, [connectListener])

    \n
    • \n

  • net.createConnection(path, [connectListener])

    \n

    Creates unix socket connection to path.

    \n
    • \n
\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n

\n

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

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

To connect on the socket /tmp/echo.sock the second line would just be\nchanged to\n\n

\n
var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
\n", - "signatures": [ - { - "params": [ - { - "name": "arguments..." - } - ] - } - ] - }, - { - "textRaw": "net.isIP(input)", - "type": "method", - "name": "isIP", - "desc": "

Tests if input is an IP address. Returns 0 for invalid strings,\nreturns 4 for IP version 4 addresses, and returns 6 for IP version 6 addresses.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "input" - } - ] - } - ] - }, - { - "textRaw": "net.isIPv4(input)", - "type": "method", - "name": "isIPv4", - "desc": "

Returns true if input is a version 4 IP address, otherwise returns false.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "input" - } - ] - } - ] - }, - { - "textRaw": "net.isIPv6(input)", - "type": "method", - "name": "isIPv6", - "desc": "

Returns true if input is a version 6 IP address, otherwise returns false.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "input" - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: net.Server", - "type": "class", - "name": "net.Server", - "desc": "

This class is used to create a TCP or UNIX server.\nA server is a net.Socket that can listen for new incoming connections.\n\n

\n", - "methods": [ - { - "textRaw": "server.listen(port, [host], [listeningListener])", - "type": "method", - "name": "listen", - "desc": "

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

\n

This function is asynchronous. When the server has been bound,\n'listening' event will be emitted.\nthe last parameter listeningListener will be added as an listener for the\n'listening' event.\n\n

\n

One issue some users run into is getting EADDRINUSE errors. This means that\nanother server is already running on the requested port. One way of handling this\nwould be to wait a second and then try again. This can be done with\n\n

\n
server.on('error', function (e) {\n  if (e.code == 'EADDRINUSE') {\n    console.log('Address in use, retrying...');\n    setTimeout(function () {\n      server.close();\n      server.listen(PORT, HOST);\n    }, 1000);\n  }\n});
\n

(Note: All sockets in Node set SO_REUSEADDR already)\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "port" - }, - { - "name": "host", - "optional": true - }, - { - "name": "listeningListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "server.listen(path, [listeningListener])", - "type": "method", - "name": "listen", - "desc": "

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

\n

This function is asynchronous. When the server has been bound,\n'listening' event will be emitted.\nthe last parameter listeningListener will be added as an listener for the\n'listening' event.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "listeningListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "server.close()", - "type": "method", - "name": "close", - "desc": "

Stops the server from accepting new connections. This function is\nasynchronous, the server is finally closed when the server emits a 'close'\nevent.\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "server.address()", - "type": "method", - "name": "address", - "desc": "

Returns the bound address and port of the server as reported by the operating system.\nUseful to find which port was assigned when giving getting an OS-assigned address.\nReturns an object with two properties, e.g. {"address":"127.0.0.1", "port":2121}\n\n

\n

Example:\n\n

\n
var server = net.createServer(function (socket) {\n  socket.end("goodbye\\n");\n});\n\n// grab a random port.\nserver.listen(function() {\n  address = server.address();\n  console.log("opened server on %j", address);\n});
\n

Don't call server.address() until the 'listening' event has been emitted.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "properties": [ - { - "textRaw": "server.maxConnections", - "name": "maxConnections", - "desc": "

Set this property to reject connections when the server's connection count gets\nhigh.\n\n

\n" - }, - { - "textRaw": "server.connections", - "name": "connections", - "desc": "

The number of concurrent connections on the server.\n\n\n

\n

net.Server is an EventEmitter with the following events:\n\n

\n" - } - ], - "events": [ - { - "textRaw": "Event: 'listening'", - "type": "event", - "name": "listening", - "desc": "

Emitted when the server has been bound after calling server.listen.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'connection'", - "type": "event", - "name": "connection", - "params": [], - "desc": "

Emitted when a new connection is made. socket is an instance of\nnet.Socket.\n\n

\n" - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

Emitted when the server closes.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "params": [], - "desc": "

Emitted when an error occurs. The 'close' event will be called directly\nfollowing this event. See example in discussion of server.listen.\n\n

\n" - } - ] - }, - { - "textRaw": "Class: net.Socket", - "type": "class", - "name": "net.Socket", - "desc": "

This object is an abstraction of a TCP or UNIX socket. net.Socket\ninstances implement a duplex Stream interface. They can be created by the\nuser and used as a client (with connect()) or they can be created by Node\nand passed to the user through the 'connection' event of a server.\n\n

\n", - "methods": [ - { - "textRaw": "new net.Socket([options])", - "type": "method", - "name": "Socket", - "desc": "

Construct a new socket object.\n\n

\n

options is an object with the following defaults:\n\n

\n
{ fd: null\n  type: null\n  allowHalfOpen: false\n}
\n

fd allows you to specify the existing file descriptor of socket. type\nspecified underlying protocol. It can be 'tcp4', 'tcp6', or 'unix'.\nAbout allowHalfOpen, refer to createServer() and 'end' event.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.connect(port, [host], [connectListener])", - "type": "method", - "name": "connect", - "desc": "

Opens the connection for a given socket. If port and host are given,\nthen the socket will be opened as a TCP socket, if host is omitted,\nlocalhost will be assumed. If a path is given, the socket will be\nopened as a unix socket to that path.\n\n

\n

Normally this method is not needed, as net.createConnection opens the\nsocket. Use this only if you are implementing a custom Socket or if a\nSocket is closed and you want to reuse it to connect to another server.\n\n

\n

This function is asynchronous. When the 'connect' event is\nemitted the socket is established. If there is a problem connecting, the\n'connect' event will not be emitted, the 'error' event will be emitted with\nthe exception.\n\n

\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "connectListener", - "optional": true - } - ] - }, - { - "params": [ - { - "name": "port" - }, - { - "name": "host", - "optional": true - }, - { - "name": "connectListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.connect(path, [connectListener])", - "type": "method", - "name": "connect", - "desc": "

Opens the connection for a given socket. If port and host are given,\nthen the socket will be opened as a TCP socket, if host is omitted,\nlocalhost will be assumed. If a path is given, the socket will be\nopened as a unix socket to that path.\n\n

\n

Normally this method is not needed, as net.createConnection opens the\nsocket. Use this only if you are implementing a custom Socket or if a\nSocket is closed and you want to reuse it to connect to another server.\n\n

\n

This function is asynchronous. When the 'connect' event is\nemitted the socket is established. If there is a problem connecting, the\n'connect' event will not be emitted, the 'error' event will be emitted with\nthe exception.\n\n

\n

The connectListener parameter will be added as an listener for the\n'connect' event.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "path" - }, - { - "name": "connectListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.setEncoding([encoding])", - "type": "method", - "name": "setEncoding", - "desc": "

Sets the encoding (either 'ascii', 'utf8', or 'base64') for data that is\nreceived. Defaults to null.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.setSecure()", - "type": "method", - "name": "setSecure", - "desc": "

This function has been removed in v0.3. It used to upgrade the connection to\nSSL/TLS. See the TLS section for the new API.\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "socket.write(data, [encoding], [callback])", - "type": "method", - "name": "write", - "desc": "

Sends data on the socket. The second parameter specifies the encoding in the\ncase of a string--it defaults to UTF8 encoding.\n\n

\n

Returns true if the entire data was flushed successfully to the kernel\nbuffer. Returns false if all or part of the data was queued in user memory.\n'drain' will be emitted when the buffer is again free.\n\n

\n

The optional callback parameter will be executed when the data is finally\nwritten out - this may not be immediately.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "data" - }, - { - "name": "encoding", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.end([data], [encoding])", - "type": "method", - "name": "end", - "desc": "

Half-closes the socket. i.e., it sends a FIN packet. It is possible the\nserver will still send some data.\n\n

\n

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

\n", - "signatures": [ - { - "params": [ - { - "name": "data", - "optional": true - }, - { - "name": "encoding", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.destroy()", - "type": "method", - "name": "destroy", - "desc": "

Ensures that no more I/O activity happens on this socket. Only necessary in\ncase of errors (parse error or so).\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "socket.pause()", - "type": "method", - "name": "pause", - "desc": "

Pauses the reading of data. That is, 'data' events will not be emitted.\nUseful to throttle back an upload.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "socket.resume()", - "type": "method", - "name": "resume", - "desc": "

Resumes reading after a call to pause().\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "socket.setTimeout(timeout, [callback])", - "type": "method", - "name": "setTimeout", - "desc": "

Sets the socket to timeout after timeout milliseconds of inactivity on\nthe socket. By default net.Socket do not have a timeout.\n\n

\n

When an idle timeout is triggered the socket will receive a 'timeout'\nevent but the connection will not be severed. The user must manually end()\nor destroy() the socket.\n\n

\n

If timeout is 0, then the existing idle timeout is disabled.\n\n

\n

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

\n", - "signatures": [ - { - "params": [ - { - "name": "timeout" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.setNoDelay([noDelay])", - "type": "method", - "name": "setNoDelay", - "desc": "

Disables the Nagle algorithm. By default TCP connections use the Nagle\nalgorithm, they buffer data before sending it off. Setting true for\nnoDelay will immediately fire off data each time socket.write() is called.\nnoDelay defaults to true.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "noDelay", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.setKeepAlive([enable], [initialDelay])", - "type": "method", - "name": "setKeepAlive", - "desc": "

Enable/disable keep-alive functionality, and optionally set the initial\ndelay before the first keepalive probe is sent on an idle socket.\nenable defaults to false.\n\n

\n

Set initialDelay (in milliseconds) to set the delay between the last\ndata packet received and the first keepalive probe. Setting 0 for\ninitialDelay will leave the value unchanged from the default\n(or previous) setting. Defaults to 0.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "enable", - "optional": true - }, - { - "name": "initialDelay", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "socket.address()", - "type": "method", - "name": "address", - "desc": "

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

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "properties": [ - { - "textRaw": "socket.bufferSize", - "name": "bufferSize", - "desc": "

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

\n

The consequence of this internal buffering is that memory may grow. This\nproperty shows the number of characters currently buffered to be written.\n(Number of characters is approximately equal to the number of bytes to be\nwritten, but the buffer may contain strings, and the strings are lazily\nencoded, so the exact number of bytes is not known.)\n\n

\n

Users who experience large or growing bufferSize should attempt to\n"throttle" the data flows in their program with pause() and resume().\n\n\n

\n" - }, - { - "textRaw": "socket.remoteAddress", - "name": "remoteAddress", - "desc": "

The string representation of the remote IP address. For example,\n'74.125.127.100' or '2001:4860:a005::68'.\n\n

\n" - }, - { - "textRaw": "socket.remotePort", - "name": "remotePort", - "desc": "

The numeric representation of the remote port. For example,\n80 or 21.\n\n

\n" - }, - { - "textRaw": "socket.bytesRead", - "name": "bytesRead", - "desc": "

The amount of received bytes.\n\n

\n" - }, - { - "textRaw": "socket.bytesWritten", - "name": "bytesWritten", - "desc": "

The amount of bytes sent.\n\n\n

\n

net.Socket instances are EventEmitters with the following events:\n\n

\n" - } - ], - "events": [ - { - "textRaw": "Event: 'connect'", - "type": "event", - "name": "connect", - "desc": "

Emitted when a socket connection is successfully established.\nSee connect().\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'data'", - "type": "event", - "name": "data", - "params": [], - "desc": "

Emitted when data is received. The argument data will be a Buffer or\nString. Encoding of data is set by socket.setEncoding().\n(See the Readable Stream section for more\ninformation.)\n\n

\n

Note that the data will be lost if there is no listener when a Socket\nemits a 'data' event.\n\n

\n" - }, - { - "textRaw": "Event: 'end'", - "type": "event", - "name": "end", - "desc": "

Emitted when the other end of the socket sends a FIN packet.\n\n

\n

By default (allowHalfOpen == false) the socket will destroy its file\ndescriptor once it has written out its pending write queue. However, by\nsetting allowHalfOpen == true the socket will not automatically end()\nits side allowing the user to write arbitrary amounts of data, with the\ncaveat that the user is required to end() their side now.\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'timeout'", - "type": "event", - "name": "timeout", - "desc": "

Emitted if the socket times out from inactivity. This is only to notify that\nthe socket has been idle. The user must manually close the connection.\n\n

\n

See also: socket.setTimeout()\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'drain'", - "type": "event", - "name": "drain", - "desc": "

Emitted when the write buffer becomes empty. Can be used to throttle uploads.\n\n

\n

See also: the return values of socket.write()\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "params": [], - "desc": "

Emitted when an error occurs. The 'close' event will be called directly\nfollowing this event.\n\n

\n" - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "params": [], - "desc": "

Emitted once the socket is fully closed. The argument had_error is a boolean\nwhich says if the socket was closed due to a transmission error.\n\n

\n" - } - ] - } - ], - "type": "module", - "displayName": "net" - } - ] -} --- a/doc/api/api/os.html +++ /dev/null @@ -1,233 +0,0 @@ - - - - - os Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

os#

-
Stability: 4 - API Frozen
-

Provides a few basic operating-system related utility functions. - -

-

Use require('os') to access this module. - -

-

os.hostname()#

-

Returns the hostname of the operating system. - -

-

os.type()#

-

Returns the operating system name. - -

-

os.platform()#

-

Returns the operating system platform. - -

-

os.arch()#

-

Returns the operating system CPU architecture. - -

-

os.release()#

-

Returns the operating system release. - -

-

os.uptime()#

-

Returns the system uptime in seconds. - -

-

os.loadavg()#

-

Returns an array containing the 1, 5, and 15 minute load averages. - -

-

os.totalmem()#

-

Returns the total amount of system memory in bytes. - -

-

os.freemem()#

-

Returns the amount of free system memory in bytes. - -

-

os.cpus()#

-

Returns an array of objects containing information about each CPU/core installed: model, speed (in MHz), and times (an object containing the number of CPU ticks spent in: user, nice, sys, idle, and irq). - -

-

Example inspection of os.cpus: - -

-
[ { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 252020,
-       nice: 0,
-       sys: 30340,
-       idle: 1070356870,
-       irq: 0 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 306960,
-       nice: 0,
-       sys: 26980,
-       idle: 1071569080,
-       irq: 0 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 248450,
-       nice: 0,
-       sys: 21750,
-       idle: 1070919370,
-       irq: 0 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 256880,
-       nice: 0,
-       sys: 19430,
-       idle: 1070905480,
-       irq: 20 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 511580,
-       nice: 20,
-       sys: 40900,
-       idle: 1070842510,
-       irq: 0 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 291660,
-       nice: 0,
-       sys: 34360,
-       idle: 1070888000,
-       irq: 10 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 308260,
-       nice: 0,
-       sys: 55410,
-       idle: 1071129970,
-       irq: 880 } },
-  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',
-    speed: 2926,
-    times:
-     { user: 266450,
-       nice: 1480,
-       sys: 34920,
-       idle: 1072572010,
-       irq: 30 } } ]
-

os.networkInterfaces()#

-

Get a list of network interfaces: - -

-
{ lo0: 
-   [ { address: '::1', family: 'IPv6', internal: true },
-     { address: 'fe80::1', family: 'IPv6', internal: true },
-     { address: '127.0.0.1', family: 'IPv4', internal: true } ],
-  en1: 
-   [ { address: 'fe80::cabc:c8ff:feef:f996', family: 'IPv6',
-       internal: false },
-     { address: '10.0.1.123', family: 'IPv4', internal: false } ],
-  vmnet1: [ { address: '10.99.99.254', family: 'IPv4', internal: false } ],
-  vmnet8: [ { address: '10.88.88.1', family: 'IPv4', internal: false } ],
-  ppp0: [ { address: '10.2.0.231', family: 'IPv4', internal: false } ] }
- -
-
-
- - - - - - - - - - --- a/doc/api/api/os.json +++ /dev/null @@ -1,137 +0,0 @@ -{ - "source": "doc/api/os.markdown", - "modules": [ - { - "textRaw": "os", - "name": "os", - "stability": 4, - "stabilityText": "API Frozen", - "desc": "

Provides a few basic operating-system related utility functions.\n\n

\n

Use require('os') to access this module.\n\n

\n", - "methods": [ - { - "textRaw": "os.hostname()", - "type": "method", - "name": "hostname", - "desc": "

Returns the hostname of the operating system.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.type()", - "type": "method", - "name": "type", - "desc": "

Returns the operating system name.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.platform()", - "type": "method", - "name": "platform", - "desc": "

Returns the operating system platform.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.arch()", - "type": "method", - "name": "arch", - "desc": "

Returns the operating system CPU architecture.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.release()", - "type": "method", - "name": "release", - "desc": "

Returns the operating system release.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.uptime()", - "type": "method", - "name": "uptime", - "desc": "

Returns the system uptime in seconds.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.loadavg()", - "type": "method", - "name": "loadavg", - "desc": "

Returns an array containing the 1, 5, and 15 minute load averages.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.totalmem()", - "type": "method", - "name": "totalmem", - "desc": "

Returns the total amount of system memory in bytes.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.freemem()", - "type": "method", - "name": "freemem", - "desc": "

Returns the amount of free system memory in bytes.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.cpus()", - "type": "method", - "name": "cpus", - "desc": "

Returns an array of objects containing information about each CPU/core installed: model, speed (in MHz), and times (an object containing the number of CPU ticks spent in: user, nice, sys, idle, and irq).\n\n

\n

Example inspection of os.cpus:\n\n

\n
[ { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 252020,\n       nice: 0,\n       sys: 30340,\n       idle: 1070356870,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 306960,\n       nice: 0,\n       sys: 26980,\n       idle: 1071569080,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 248450,\n       nice: 0,\n       sys: 21750,\n       idle: 1070919370,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 256880,\n       nice: 0,\n       sys: 19430,\n       idle: 1070905480,\n       irq: 20 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 511580,\n       nice: 20,\n       sys: 40900,\n       idle: 1070842510,\n       irq: 0 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 291660,\n       nice: 0,\n       sys: 34360,\n       idle: 1070888000,\n       irq: 10 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 308260,\n       nice: 0,\n       sys: 55410,\n       idle: 1071129970,\n       irq: 880 } },\n  { model: 'Intel(R) Core(TM) i7 CPU         860  @ 2.80GHz',\n    speed: 2926,\n    times:\n     { user: 266450,\n       nice: 1480,\n       sys: 34920,\n       idle: 1072572010,\n       irq: 30 } } ]
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "os.networkInterfaces()", - "type": "method", - "name": "networkInterfaces", - "desc": "

Get a list of network interfaces:\n\n

\n
{ lo0: \n   [ { address: '::1', family: 'IPv6', internal: true },\n     { address: 'fe80::1', family: 'IPv6', internal: true },\n     { address: '127.0.0.1', family: 'IPv4', internal: true } ],\n  en1: \n   [ { address: 'fe80::cabc:c8ff:feef:f996', family: 'IPv6',\n       internal: false },\n     { address: '10.0.1.123', family: 'IPv4', internal: false } ],\n  vmnet1: [ { address: '10.99.99.254', family: 'IPv4', internal: false } ],\n  vmnet8: [ { address: '10.88.88.1', family: 'IPv4', internal: false } ],\n  ppp0: [ { address: '10.2.0.231', family: 'IPv4', internal: false } ] }
\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "type": "module", - "displayName": "os" - } - ] -} --- a/doc/api/api/path.html +++ /dev/null @@ -1,259 +0,0 @@ - - - - - Path Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Path#

-
Stability: 3 - Stable
-

This module contains utilities for handling and transforming file -paths. Almost all these methods perform only string transformations. -The file system is not consulted to check whether paths are valid. - -

-

path.exists and path.existsSync are the exceptions, and should -logically be found in the fs module as they do access the file system. - -

-

Use require('path') to use this module. The following methods are provided: - -

-

path.normalize(p)#

-

Normalize a string path, taking care of '..' and '.' parts. - -

-

When multiple slashes are found, they're replaced by a single one; -when the path contains a trailing slash, it is preserved. -On windows backslashes are used. - -

-

Example: - -

-
path.normalize('/foo/bar//baz/asdf/quux/..')
-// returns
-'/foo/bar/baz/asdf'
-

path.join([path1], [path2], [...])#

-

Join all arguments together and normalize the resulting path. -Non-string arguments are ignored. - -

-

Example: - -

-
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
-// returns
-'/foo/bar/baz/asdf'
-
-path.join('foo', {}, 'bar')
-// returns
-'foo/bar'
-

path.resolve([from ...], to)#

-

Resolves to to an absolute path. - -

-

If to isn't already absolute from arguments are prepended in right to left -order, until an absolute path is found. If after using all from paths still -no absolute path is found, the current working directory is used as well. The -resulting path is normalized, and trailing slashes are removed unless the path -gets resolved to the root directory. Non-string arguments are ignored. - -

-

Another way to think of it is as a sequence of cd commands in a shell. - -

-
path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
-

Is similar to: - -

-
cd foo/bar
-cd /tmp/file/
-cd ..
-cd a/../subfile
-pwd
-

The difference is that the different paths don't need to exist and may also be -files. - -

-

Examples: - -

-
path.resolve('/foo/bar', './baz')
-// returns
-'/foo/bar/baz'
-
-path.resolve('/foo/bar', '/tmp/file/')
-// returns
-'/tmp/file'
-
-path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
-// if currently in /home/myself/node, it returns
-'/home/myself/node/wwwroot/static_files/gif/image.gif'
-

path.relative(from, to)#

-

Solve the relative path from from to to. - -

-

At times we have two absolute paths, and we need to derive the relative -path from one to the other. This is actually the reverse transform of -path.resolve, which means we see that: - -

-
path.resolve(from, path.relative(from, to)) == path.resolve(to)
-

Examples: - -

-
path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb')
-// returns
-'..\\..\\impl\\bbb'
-
-path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
-// returns
-'../../impl/bbb'
-

path.dirname(p)#

-

Return the directory name of a path. Similar to the Unix dirname command. - -

-

Example: - -

-
path.dirname('/foo/bar/baz/asdf/quux')
-// returns
-'/foo/bar/baz/asdf'
-

path.basename(p, [ext])#

-

Return the last portion of a path. Similar to the Unix basename command. - -

-

Example: - -

-
path.basename('/foo/bar/baz/asdf/quux.html')
-// returns
-'quux.html'
-
-path.basename('/foo/bar/baz/asdf/quux.html', '.html')
-// returns
-'quux'
-

path.extname(p)#

-

Return the extension of the path, from the last '.' to end of string -in the last portion of the path. If there is no '.' in the last portion -of the path or the first character of it is '.', then it returns -an empty string. Examples: - -

-
path.extname('index.html')
-// returns
-'.html'
-
-path.extname('index.')
-// returns
-'.'
-
-path.extname('index')
-// returns
-''
-

path.exists(p, [callback])#

-

Test whether or not the given path exists by checking with the file system. -Then call the callback argument with either true or false. Example: - -

-
path.exists('/etc/passwd', function (exists) {
-  util.debug(exists ? "it's there" : "no passwd!");
-});
-

path.existsSync(p)#

-

Synchronous version of path.exists. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/path.json +++ /dev/null @@ -1,175 +0,0 @@ -{ - "source": "doc/api/path.markdown", - "modules": [ - { - "textRaw": "Path", - "name": "path", - "stability": 3, - "stabilityText": "Stable", - "desc": "

This module contains utilities for handling and transforming file\npaths. Almost all these methods perform only string transformations.\nThe file system is not consulted to check whether paths are valid.\n\n

\n

path.exists and path.existsSync are the exceptions, and should\nlogically be found in the fs module as they do access the file system.\n\n

\n

Use require('path') to use this module. The following methods are provided:\n\n

\n", - "methods": [ - { - "textRaw": "path.normalize(p)", - "type": "method", - "name": "normalize", - "desc": "

Normalize a string path, taking care of '..' and '.' parts.\n\n

\n

When multiple slashes are found, they're replaced by a single one;\nwhen the path contains a trailing slash, it is preserved.\nOn windows backslashes are used. \n\n

\n

Example:\n\n

\n
path.normalize('/foo/bar//baz/asdf/quux/..')\n// returns\n'/foo/bar/baz/asdf'
\n", - "signatures": [ - { - "params": [ - { - "name": "p" - } - ] - } - ] - }, - { - "textRaw": "path.join([path1], [path2], [...])", - "type": "method", - "name": "join", - "desc": "

Join all arguments together and normalize the resulting path.\nNon-string arguments are ignored.\n\n

\n

Example:\n\n

\n
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')\n// returns\n'/foo/bar/baz/asdf'\n\npath.join('foo', {}, 'bar')\n// returns\n'foo/bar'
\n", - "signatures": [ - { - "params": [ - { - "name": "path1", - "optional": true - }, - { - "name": "path2", - "optional": true - }, - { - "name": "...", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "path.resolve([from ...], to)", - "type": "method", - "name": "resolve", - "desc": "

Resolves to to an absolute path.\n\n

\n

If to isn't already absolute from arguments are prepended in right to left\norder, until an absolute path is found. If after using all from paths still\nno absolute path is found, the current working directory is used as well. The\nresulting path is normalized, and trailing slashes are removed unless the path \ngets resolved to the root directory. Non-string arguments are ignored.\n\n

\n

Another way to think of it is as a sequence of cd commands in a shell.\n\n

\n
path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
\n

Is similar to:\n\n

\n
cd foo/bar\ncd /tmp/file/\ncd ..\ncd a/../subfile\npwd
\n

The difference is that the different paths don't need to exist and may also be\nfiles.\n\n

\n

Examples:\n\n

\n
path.resolve('/foo/bar', './baz')\n// returns\n'/foo/bar/baz'\n\npath.resolve('/foo/bar', '/tmp/file/')\n// returns\n'/tmp/file'\n\npath.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')\n// if currently in /home/myself/node, it returns\n'/home/myself/node/wwwroot/static_files/gif/image.gif'
\n", - "signatures": [ - { - "params": [ - { - "name": "from ...", - "optional": true - }, - { - "name": "to" - } - ] - } - ] - }, - { - "textRaw": "path.relative(from, to)", - "type": "method", - "name": "relative", - "desc": "

Solve the relative path from from to to.\n\n

\n

At times we have two absolute paths, and we need to derive the relative\npath from one to the other. This is actually the reverse transform of\npath.resolve, which means we see that:\n\n

\n
path.resolve(from, path.relative(from, to)) == path.resolve(to)
\n

Examples:\n\n

\n
path.relative('C:\\\\orandea\\\\test\\\\aaa', 'C:\\\\orandea\\\\impl\\\\bbb')\n// returns\n'..\\\\..\\\\impl\\\\bbb'\n\npath.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')\n// returns\n'../../impl/bbb'
\n", - "signatures": [ - { - "params": [ - { - "name": "from" - }, - { - "name": "to" - } - ] - } - ] - }, - { - "textRaw": "path.dirname(p)", - "type": "method", - "name": "dirname", - "desc": "

Return the directory name of a path. Similar to the Unix dirname command.\n\n

\n

Example:\n\n

\n
path.dirname('/foo/bar/baz/asdf/quux')\n// returns\n'/foo/bar/baz/asdf'
\n", - "signatures": [ - { - "params": [ - { - "name": "p" - } - ] - } - ] - }, - { - "textRaw": "path.basename(p, [ext])", - "type": "method", - "name": "basename", - "desc": "

Return the last portion of a path. Similar to the Unix basename command.\n\n

\n

Example:\n\n

\n
path.basename('/foo/bar/baz/asdf/quux.html')\n// returns\n'quux.html'\n\npath.basename('/foo/bar/baz/asdf/quux.html', '.html')\n// returns\n'quux'
\n", - "signatures": [ - { - "params": [ - { - "name": "p" - }, - { - "name": "ext", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "path.extname(p)", - "type": "method", - "name": "extname", - "desc": "

Return the extension of the path, from the last '.' to end of string\nin the last portion of the path. If there is no '.' in the last portion\nof the path or the first character of it is '.', then it returns\nan empty string. Examples:\n\n

\n
path.extname('index.html')\n// returns\n'.html'\n\npath.extname('index.')\n// returns\n'.'\n\npath.extname('index')\n// returns\n''
\n", - "signatures": [ - { - "params": [ - { - "name": "p" - } - ] - } - ] - }, - { - "textRaw": "path.exists(p, [callback])", - "type": "method", - "name": "exists", - "desc": "

Test whether or not the given path exists by checking with the file system.\nThen call the callback argument with either true or false. Example:\n\n

\n
path.exists('/etc/passwd', function (exists) {\n  util.debug(exists ? "it's there" : "no passwd!");\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "p" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "path.existsSync(p)", - "type": "method", - "name": "existsSync", - "desc": "

Synchronous version of path.exists.\n

\n", - "signatures": [ - { - "params": [ - { - "name": "p" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "Path" - } - ] -} --- a/doc/api/api/process.html +++ /dev/null @@ -1,450 +0,0 @@ - - - - - process Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

process#

- - -

The process object is a global object and can be accessed from anywhere. -It is an instance of EventEmitter. - - -

-

Event: 'exit'#

-

Emitted when the process is about to exit. This is a good hook to perform -constant time checks of the module's state (like for unit tests). The main -event loop will no longer be run after the 'exit' callback finishes, so -timers may not be scheduled. - -

-

Example of listening for exit: - -

-
process.on('exit', function () {
-  process.nextTick(function () {
-   console.log('This will not run');
-  });
-  console.log('About to exit.');
-});
-

Event: 'uncaughtException'#

-

Emitted when an exception bubbles all the way back to the event loop. If a -listener is added for this exception, the default action (which is to print -a stack trace and exit) will not occur. - -

-

Example of listening for uncaughtException: - -

-
process.on('uncaughtException', function (err) {
-  console.log('Caught exception: ' + err);
-});
-
-setTimeout(function () {
-  console.log('This will still run.');
-}, 500);
-
-// Intentionally cause an exception, but don't catch it.
-nonexistentFunc();
-console.log('This will not run.');
-

Note that uncaughtException is a very crude mechanism for exception -handling. Using try / catch in your program will give you more control over -your program's flow. Especially for server programs that are designed to -stay running forever, uncaughtException can be a useful safety mechanism. - - -

-

Signal Events#

- - - -

Emitted when the processes receives a signal. See sigaction(2) for a list of -standard POSIX signal names such as SIGINT, SIGUSR1, etc. - -

-

Example of listening for SIGINT: - -

-
// Start reading from stdin so we don't exit.
-process.stdin.resume();
-
-process.on('SIGINT', function () {
-  console.log('Got SIGINT.  Press Control-D to exit.');
-});
-

An easy way to send the SIGINT signal is with Control-C in most terminal -programs. - - -

-

process.stdout#

-

A Writable Stream to stdout. - -

-

Example: the definition of console.log - -

-
console.log = function (d) {
-  process.stdout.write(d + '\n');
-};
-

process.stderr and process.stdout are unlike other streams in Node in -that writes to them are usually blocking. They are blocking in the case -that they refer to regular files or TTY file descriptors. In the case they -refer to pipes, they are non-blocking like other streams. - - -

-

process.stderr#

-

A writable stream to stderr. - -

-

process.stderr and process.stdout are unlike other streams in Node in -that writes to them are usually blocking. They are blocking in the case -that they refer to regular files or TTY file descriptors. In the case they -refer to pipes, they are non-blocking like other streams. - - -

-

process.stdin#

-

A Readable Stream for stdin. The stdin stream is paused by default, so one -must call process.stdin.resume() to read from it. - -

-

Example of opening standard input and listening for both events: - -

-
process.stdin.resume();
-process.stdin.setEncoding('utf8');
-
-process.stdin.on('data', function (chunk) {
-  process.stdout.write('data: ' + chunk);
-});
-
-process.stdin.on('end', function () {
-  process.stdout.write('end');
-});
-

process.argv#

-

An array containing the command line arguments. The first element will be -'node', the second element will be the name of the JavaScript file. The -next elements will be any additional command line arguments. - -

-
// print process.argv
-process.argv.forEach(function (val, index, array) {
-  console.log(index + ': ' + val);
-});
-

This will generate: - -

-
$ node process-2.js one two=three four
-0: node
-1: /Users/mjr/work/node/process-2.js
-2: one
-3: two=three
-4: four
-

process.execPath#

-

This is the absolute pathname of the executable that started the process. - -

-

Example: - -

-
/usr/local/bin/node
-

process.chdir(directory)#

-

Changes the current working directory of the process or throws an exception if that fails. - -

-
console.log('Starting directory: ' + process.cwd());
-try {
-  process.chdir('/tmp');
-  console.log('New directory: ' + process.cwd());
-}
-catch (err) {
-  console.log('chdir: ' + err);
-}
-

process.cwd()#

-

Returns the current working directory of the process. - -

-
console.log('Current directory: ' + process.cwd());
-

process.env#

-

An object containing the user environment. See environ(7). - - -

-

process.exit([code])#

-

Ends the process with the specified code. If omitted, exit uses the -'success' code 0. - -

-

To exit with a 'failure' code: - -

-
process.exit(1);
-

The shell that executed node should see the exit code as 1. - - -

-

process.getgid()#

-

Gets the group identity of the process. (See getgid(2).) -This is the numerical group id, not the group name. - -

-
console.log('Current gid: ' + process.getgid());
-

process.setgid(id)#

-

Sets the group identity of the process. (See setgid(2).) This accepts either -a numerical ID or a groupname string. If a groupname is specified, this method -blocks while resolving it to a numerical ID. - -

-
console.log('Current gid: ' + process.getgid());
-try {
-  process.setgid(501);
-  console.log('New gid: ' + process.getgid());
-}
-catch (err) {
-  console.log('Failed to set gid: ' + err);
-}
-

process.getuid()#

-

Gets the user identity of the process. (See getuid(2).) -This is the numerical userid, not the username. - -

-
console.log('Current uid: ' + process.getuid());
-

process.setuid(id)#

-

Sets the user identity of the process. (See setuid(2).) This accepts either -a numerical ID or a username string. If a username is specified, this method -blocks while resolving it to a numerical ID. - -

-
console.log('Current uid: ' + process.getuid());
-try {
-  process.setuid(501);
-  console.log('New uid: ' + process.getuid());
-}
-catch (err) {
-  console.log('Failed to set uid: ' + err);
-}
-

process.version#

-

A compiled-in property that exposes NODE_VERSION. - -

-
console.log('Version: ' + process.version);
-

process.versions#

-

A property exposing version strings of node and its dependencies. - -

-
console.log(process.versions);
-

Will output: - -

-
{ node: '0.4.12',
-  v8: '3.1.8.26',
-  ares: '1.7.4',
-  ev: '4.4',
-  openssl: '1.0.0e-fips' }
-

process.installPrefix#

-

A compiled-in property that exposes NODE_PREFIX. - -

-
console.log('Prefix: ' + process.installPrefix);
-

process.kill(pid, [signal])#

-

Send a signal to a process. pid is the process id and signal is the -string describing the signal to send. Signal names are strings like -'SIGINT' or 'SIGUSR1'. If omitted, the signal will be 'SIGTERM'. -See kill(2) for more information. - -

-

Note that just because the name of this function is process.kill, it is -really just a signal sender, like the kill system call. The signal sent -may do something other than kill the target process. - -

-

Example of sending a signal to yourself: - -

-
process.on('SIGHUP', function () {
-  console.log('Got SIGHUP signal.');
-});
-
-setTimeout(function () {
-  console.log('Exiting.');
-  process.exit(0);
-}, 100);
-
-process.kill(process.pid, 'SIGHUP');
-

process.pid#

-

The PID of the process. - -

-
console.log('This process is pid ' + process.pid);
-

process.title#

-

Getter/setter to set what is displayed in 'ps'. - - -

-

process.arch#

-

What processor architecture you're running on: 'arm', 'ia32', or 'x64'. - -

-
console.log('This processor architecture is ' + process.arch);
-

process.platform#

-

What platform you're running on. 'linux2', 'darwin', etc. - -

-
console.log('This platform is ' + process.platform);
-

process.memoryUsage()#

-

Returns an object describing the memory usage of the Node process -measured in bytes. - -

-
var util = require('util');
-
-console.log(util.inspect(process.memoryUsage()));
-

This will generate: - -

-
{ rss: 4935680,
-  heapTotal: 1826816,
-  heapUsed: 650472 }
-

heapTotal and heapUsed refer to V8's memory usage. - - -

-

process.nextTick(callback)#

-

On the next loop around the event loop call this callback. -This is not a simple alias to setTimeout(fn, 0), it's much more -efficient. - -

-
process.nextTick(function () {
-  console.log('nextTick callback');
-});
-

process.umask([mask])#

-

Sets or reads the process's file mode creation mask. Child processes inherit -the mask from the parent process. Returns the old mask if mask argument is -given, otherwise returns the current mask. - -

-
var oldmask, newmask = 0644;
-
-oldmask = process.umask(newmask);
-console.log('Changed umask from: ' + oldmask.toString(8) +
-            ' to ' + newmask.toString(8));
-

process.uptime()#

-

Number of seconds Node has been running. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/process.json +++ /dev/null @@ -1,269 +0,0 @@ -{ - "source": "doc/api/process.markdown", - "globals": [ - { - "textRaw": "process", - "name": "process", - "type": "global", - "desc": "

The process object is a global object and can be accessed from anywhere.\nIt is an instance of EventEmitter.\n\n\n

\n", - "events": [ - { - "textRaw": "Event: 'exit'", - "type": "event", - "name": "exit", - "desc": "

Emitted when the process is about to exit. This is a good hook to perform\nconstant time checks of the module's state (like for unit tests). The main\nevent loop will no longer be run after the 'exit' callback finishes, so\ntimers may not be scheduled.\n\n

\n

Example of listening for exit:\n\n

\n
process.on('exit', function () {\n  process.nextTick(function () {\n   console.log('This will not run');\n  });\n  console.log('About to exit.');\n});
\n", - "params": [] - }, - { - "textRaw": "Event: 'uncaughtException'", - "type": "event", - "name": "uncaughtException", - "desc": "

Emitted when an exception bubbles all the way back to the event loop. If a\nlistener is added for this exception, the default action (which is to print\na stack trace and exit) will not occur.\n\n

\n

Example of listening for uncaughtException:\n\n

\n
process.on('uncaughtException', function (err) {\n  console.log('Caught exception: ' + err);\n});\n\nsetTimeout(function () {\n  console.log('This will still run.');\n}, 500);\n\n// Intentionally cause an exception, but don't catch it.\nnonexistentFunc();\nconsole.log('This will not run.');
\n

Note that uncaughtException is a very crude mechanism for exception\nhandling. Using try / catch in your program will give you more control over\nyour program's flow. Especially for server programs that are designed to\nstay running forever, uncaughtException can be a useful safety mechanism.\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Signal Events", - "name": "SIGINT, SIGUSR1, etc.", - "type": "event", - "desc": "

Emitted when the processes receives a signal. See sigaction(2) for a list of\nstandard POSIX signal names such as SIGINT, SIGUSR1, etc.\n\n

\n

Example of listening for SIGINT:\n\n

\n
// Start reading from stdin so we don't exit.\nprocess.stdin.resume();\n\nprocess.on('SIGINT', function () {\n  console.log('Got SIGINT.  Press Control-D to exit.');\n});
\n

An easy way to send the SIGINT signal is with Control-C in most terminal\nprograms.\n\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "process.stdout", - "name": "stdout", - "desc": "

A Writable Stream to stdout.\n\n

\n

Example: the definition of console.log\n\n

\n
console.log = function (d) {\n  process.stdout.write(d + '\\n');\n};
\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" - }, - { - "textRaw": "process.stderr", - "name": "stderr", - "desc": "

A writable stream to stderr.\n\n

\n

process.stderr and process.stdout are unlike other streams in Node in\nthat writes to them are usually blocking. They are blocking in the case\nthat they refer to regular files or TTY file descriptors. In the case they\nrefer to pipes, they are non-blocking like other streams.\n\n\n

\n" - }, - { - "textRaw": "process.stdin", - "name": "stdin", - "desc": "

A Readable Stream for stdin. The stdin stream is paused by default, so one\nmust call process.stdin.resume() to read from it.\n\n

\n

Example of opening standard input and listening for both events:\n\n

\n
process.stdin.resume();\nprocess.stdin.setEncoding('utf8');\n\nprocess.stdin.on('data', function (chunk) {\n  process.stdout.write('data: ' + chunk);\n});\n\nprocess.stdin.on('end', function () {\n  process.stdout.write('end');\n});
\n" - }, - { - "textRaw": "process.argv", - "name": "argv", - "desc": "

An array containing the command line arguments. The first element will be\n'node', the second element will be the name of the JavaScript file. The\nnext elements will be any additional command line arguments.\n\n

\n
// print process.argv\nprocess.argv.forEach(function (val, index, array) {\n  console.log(index + ': ' + val);\n});
\n

This will generate:\n\n

\n
$ node process-2.js one two=three four\n0: node\n1: /Users/mjr/work/node/process-2.js\n2: one\n3: two=three\n4: four
\n" - }, - { - "textRaw": "process.execPath", - "name": "execPath", - "desc": "

This is the absolute pathname of the executable that started the process.\n\n

\n

Example:\n\n

\n
/usr/local/bin/node
\n" - }, - { - "textRaw": "process.env", - "name": "env", - "desc": "

An object containing the user environment. See environ(7).\n\n\n

\n" - }, - { - "textRaw": "process.version", - "name": "version", - "desc": "

A compiled-in property that exposes NODE_VERSION.\n\n

\n
console.log('Version: ' + process.version);
\n" - }, - { - "textRaw": "process.versions", - "name": "versions", - "desc": "

A property exposing version strings of node and its dependencies.\n\n

\n
console.log(process.versions);
\n

Will output:\n\n

\n
{ node: '0.4.12',\n  v8: '3.1.8.26',\n  ares: '1.7.4',\n  ev: '4.4',\n  openssl: '1.0.0e-fips' }
\n" - }, - { - "textRaw": "process.installPrefix", - "name": "installPrefix", - "desc": "

A compiled-in property that exposes NODE_PREFIX.\n\n

\n
console.log('Prefix: ' + process.installPrefix);
\n" - }, - { - "textRaw": "process.pid", - "name": "pid", - "desc": "

The PID of the process.\n\n

\n
console.log('This process is pid ' + process.pid);
\n" - }, - { - "textRaw": "process.title", - "name": "title", - "desc": "

Getter/setter to set what is displayed in 'ps'.\n\n\n

\n" - }, - { - "textRaw": "process.arch", - "name": "arch", - "desc": "

What processor architecture you're running on: 'arm', 'ia32', or 'x64'.\n\n

\n
console.log('This processor architecture is ' + process.arch);
\n" - }, - { - "textRaw": "process.platform", - "name": "platform", - "desc": "

What platform you're running on. 'linux2', 'darwin', etc.\n\n

\n
console.log('This platform is ' + process.platform);
\n" - } - ], - "methods": [ - { - "textRaw": "process.chdir(directory)", - "type": "method", - "name": "chdir", - "desc": "

Changes the current working directory of the process or throws an exception if that fails.\n\n

\n
console.log('Starting directory: ' + process.cwd());\ntry {\n  process.chdir('/tmp');\n  console.log('New directory: ' + process.cwd());\n}\ncatch (err) {\n  console.log('chdir: ' + err);\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "directory" - } - ] - } - ] - }, - { - "textRaw": "process.cwd()", - "type": "method", - "name": "cwd", - "desc": "

Returns the current working directory of the process.\n\n

\n
console.log('Current directory: ' + process.cwd());
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.exit([code])", - "type": "method", - "name": "exit", - "desc": "

Ends the process with the specified code. If omitted, exit uses the\n'success' code 0.\n\n

\n

To exit with a 'failure' code:\n\n

\n
process.exit(1);
\n

The shell that executed node should see the exit code as 1.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "process.getgid()", - "type": "method", - "name": "getgid", - "desc": "

Gets the group identity of the process. (See getgid(2).)\nThis is the numerical group id, not the group name.\n\n

\n
console.log('Current gid: ' + process.getgid());
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.setgid(id)", - "type": "method", - "name": "setgid", - "desc": "

Sets the group identity of the process. (See setgid(2).) This accepts either\na numerical ID or a groupname string. If a groupname is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current gid: ' + process.getgid());\ntry {\n  process.setgid(501);\n  console.log('New gid: ' + process.getgid());\n}\ncatch (err) {\n  console.log('Failed to set gid: ' + err);\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "id" - } - ] - } - ] - }, - { - "textRaw": "process.getuid()", - "type": "method", - "name": "getuid", - "desc": "

Gets the user identity of the process. (See getuid(2).)\nThis is the numerical userid, not the username.\n\n

\n
console.log('Current uid: ' + process.getuid());
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.setuid(id)", - "type": "method", - "name": "setuid", - "desc": "

Sets the user identity of the process. (See setuid(2).) This accepts either\na numerical ID or a username string. If a username is specified, this method\nblocks while resolving it to a numerical ID.\n\n

\n
console.log('Current uid: ' + process.getuid());\ntry {\n  process.setuid(501);\n  console.log('New uid: ' + process.getuid());\n}\ncatch (err) {\n  console.log('Failed to set uid: ' + err);\n}
\n", - "signatures": [ - { - "params": [ - { - "name": "id" - } - ] - } - ] - }, - { - "textRaw": "process.kill(pid, [signal])", - "type": "method", - "name": "kill", - "desc": "

Send a signal to a process. pid is the process id and signal is the\nstring describing the signal to send. Signal names are strings like\n'SIGINT' or 'SIGUSR1'. If omitted, the signal will be 'SIGTERM'.\nSee kill(2) for more information.\n\n

\n

Note that just because the name of this function is process.kill, it is\nreally just a signal sender, like the kill system call. The signal sent\nmay do something other than kill the target process.\n\n

\n

Example of sending a signal to yourself:\n\n

\n
process.on('SIGHUP', function () {\n  console.log('Got SIGHUP signal.');\n});\n\nsetTimeout(function () {\n  console.log('Exiting.');\n  process.exit(0);\n}, 100);\n\nprocess.kill(process.pid, 'SIGHUP');
\n", - "signatures": [ - { - "params": [ - { - "name": "pid" - }, - { - "name": "signal", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "process.memoryUsage()", - "type": "method", - "name": "memoryUsage", - "desc": "

Returns an object describing the memory usage of the Node process\nmeasured in bytes.\n\n

\n
var util = require('util');\n\nconsole.log(util.inspect(process.memoryUsage()));
\n

This will generate:\n\n

\n
{ rss: 4935680,\n  heapTotal: 1826816,\n  heapUsed: 650472 }
\n

heapTotal and heapUsed refer to V8's memory usage.\n\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "process.nextTick(callback)", - "type": "method", - "name": "nextTick", - "desc": "

On the next loop around the event loop call this callback.\nThis is not a simple alias to setTimeout(fn, 0), it's much more\nefficient.\n\n

\n
process.nextTick(function () {\n  console.log('nextTick callback');\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "process.umask([mask])", - "type": "method", - "name": "umask", - "desc": "

Sets or reads the process's file mode creation mask. Child processes inherit\nthe mask from the parent process. Returns the old mask if mask argument is\ngiven, otherwise returns the current mask.\n\n

\n
var oldmask, newmask = 0644;\n\noldmask = process.umask(newmask);\nconsole.log('Changed umask from: ' + oldmask.toString(8) +\n            ' to ' + newmask.toString(8));
\n", - "signatures": [ - { - "params": [ - { - "name": "mask", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "process.uptime()", - "type": "method", - "name": "uptime", - "desc": "

Number of seconds Node has been running.\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - } - ] -} --- a/doc/api/api/querystring.html +++ /dev/null @@ -1,141 +0,0 @@ - - - - - Query String Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Query String#

-
Stability: 3 - Stable
- - -

This module provides utilities for dealing with query strings. -It provides the following methods: - -

-

querystring.stringify(obj, [sep], [eq])#

-

Serialize an object to a query string. -Optionally override the default separator ('&') and assignment ('=') -characters. - -

-

Example: - -

-
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })
-// returns
-'foo=bar&baz=qux&baz=quux&corge='
-
-querystring.stringify({foo: 'bar', baz: 'qux'}, ';', ':')
-// returns
-'foo:bar;baz:qux'
-

querystring.parse(str, [sep], [eq])#

-

Deserialize a query string to an object. -Optionally override the default separator ('&') and assignment ('=') -characters. - -

-

Example: - -

-
querystring.parse('foo=bar&baz=qux&baz=quux&corge')
-// returns
-{ foo: 'bar', baz: ['qux', 'quux'], corge: '' }
-

querystring.escape#

-

The escape function used by querystring.stringify, -provided so that it could be overridden if necessary. - -

-

querystring.unescape#

-

The unescape function used by querystring.parse, -provided so that it could be overridden if necessary. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/querystring.json +++ /dev/null @@ -1,74 +0,0 @@ -{ - "source": "doc/api/querystring.markdown", - "modules": [ - { - "textRaw": "Query String", - "name": "querystring", - "stability": 3, - "stabilityText": "Stable", - "desc": "

This module provides utilities for dealing with query strings.\nIt provides the following methods:\n\n

\n", - "methods": [ - { - "textRaw": "querystring.stringify(obj, [sep], [eq])", - "type": "method", - "name": "stringify", - "desc": "

Serialize an object to a query string.\nOptionally override the default separator ('&') and assignment ('=')\ncharacters.\n\n

\n

Example:\n\n

\n
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })\n// returns\n'foo=bar&baz=qux&baz=quux&corge='\n\nquerystring.stringify({foo: 'bar', baz: 'qux'}, ';', ':')\n// returns\n'foo:bar;baz:qux'
\n", - "signatures": [ - { - "params": [ - { - "name": "obj" - }, - { - "name": "sep", - "optional": true - }, - { - "name": "eq", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "querystring.parse(str, [sep], [eq])", - "type": "method", - "name": "parse", - "desc": "

Deserialize a query string to an object.\nOptionally override the default separator ('&') and assignment ('=')\ncharacters.\n\n

\n

Example:\n\n

\n
querystring.parse('foo=bar&baz=qux&baz=quux&corge')\n// returns\n{ foo: 'bar', baz: ['qux', 'quux'], corge: '' }
\n", - "signatures": [ - { - "params": [ - { - "name": "str" - }, - { - "name": "sep", - "optional": true - }, - { - "name": "eq", - "optional": true - } - ] - } - ] - } - ], - "properties": [ - { - "textRaw": "querystring.escape", - "name": "escape", - "desc": "

The escape function used by querystring.stringify,\nprovided so that it could be overridden if necessary.\n\n

\n" - }, - { - "textRaw": "querystring.unescape", - "name": "unescape", - "desc": "

The unescape function used by querystring.parse,\nprovided so that it could be overridden if necessary.\n

\n" - } - ], - "type": "module", - "displayName": "querystring" - } - ] -} --- a/doc/api/api/readline.html +++ /dev/null @@ -1,252 +0,0 @@ - - - - - Readline Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Readline#

-
Stability: 3 - Stable
-

To use this module, do require('readline'). Readline allows reading of a -stream (such as STDIN) on a line-by-line basis. - -

-

Note that once you've invoked this module, your node program will not -terminate until you've closed the interface, and the STDIN stream. Here's how -to allow your program to gracefully terminate: - -

-
var rl = require('readline');
-
-var i = rl.createInterface(process.stdin, process.stdout, null);
-i.question("What do you think of node.js?", function(answer) {
-  // TODO: Log the answer in a database
-  console.log("Thank you for your valuable feedback.");
-
-  // These two lines together allow the program to terminate. Without
-  // them, it would run forever.
-  i.close();
-  process.stdin.destroy();
-});
-

rl.createInterface(input, output, completer)#

-

Takes two streams and creates a readline interface. The completer function -is used for autocompletion. When given a substring, it returns [[substr1, -substr2, ...], originalsubstring]. - -

-

Also completer can be run in async mode if it accepts two arguments: - -

-

function completer(linePartial, callback) { - callback(null, [['123'], linePartial]); - } - -

-

createInterface is commonly used with process.stdin and -process.stdout in order to accept user input: - -

-
var readline = require('readline'),
-  rl = readline.createInterface(process.stdin, process.stdout);
-

Class: Interface#

-

The class that represents a readline interface with a stdin and stdout -stream. - -

-

rl.setPrompt(prompt, length)#

-

Sets the prompt, for example when you run node on the command line, you see -> , which is node's prompt. - -

-

rl.prompt()#

-

Readies readline for input from the user, putting the current setPrompt -options on a new line, giving the user a new spot to write. - -

-

rl.question(query, callback)#

-

Prepends the prompt with query and invokes callback with the user's -response. Displays the query to the user, and then invokes callback with the -user's response after it has been typed. - -

-

Example usage: - -

-
interface.question('What is your favorite food?', function(answer) {
-  console.log('Oh, so your favorite food is ' + answer);
-});
-

rl.close()#

-

Closes tty. - -

-

rl.pause()#

-

Pauses tty. - -

-

rl.resume()#

-

Resumes tty. - -

-

rl.write()#

-

Writes to tty. - -

-

Event: 'line'#

-

function (line) {} - -

-

Emitted whenever the in stream receives a \n, usually received when the -user hits enter, or return. This is a good hook to listen for user input. - -

-

Example of listening for line: - -

-
rl.on('line', function (cmd) {
-  console.log('You just typed: '+cmd);
-});
-

Event: 'close'#

-

function () {} - -

-

Emitted whenever the in stream receives a ^C or ^D, respectively known -as SIGINT and EOT. This is a good way to know the user is finished using -your program. - -

-

Example of listening for close, and exiting the program afterward: - -

-
rl.on('close', function() {
-  console.log('goodbye!');
-  process.exit(0);
-});
-

Here's an example of how to use all these together to craft a tiny command -line interface: - -

-
var readline = require('readline'),
-  rl = readline.createInterface(process.stdin, process.stdout),
-  prefix = 'OHAI> ';
-
-rl.on('line', function(line) {
-  switch(line.trim()) {
-    case 'hello':
-      console.log('world!');
-      break;
-    default:
-      console.log('Say what? I might have heard `' + line.trim() + '`');
-      break;
-  }
-  rl.setPrompt(prefix, prefix.length);
-  rl.prompt();
-}).on('close', function() {
-  console.log('Have a great day!');
-  process.exit(0);
-});
-console.log(prefix + 'Good to see you. Try typing stuff.');
-rl.setPrompt(prefix, prefix.length);
-rl.prompt();
-

Take a look at this slightly more complicated -example, and -http-console for a real-life use -case. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/readline.json +++ /dev/null @@ -1,154 +0,0 @@ -{ - "source": "doc/api/readline.markdown", - "modules": [ - { - "textRaw": "Readline", - "name": "readline", - "stability": 3, - "stabilityText": "Stable", - "desc": "

To use this module, do require('readline'). Readline allows reading of a\nstream (such as STDIN) on a line-by-line basis.\n\n

\n

Note that once you've invoked this module, your node program will not\nterminate until you've closed the interface, and the STDIN stream. Here's how\nto allow your program to gracefully terminate:\n\n

\n
var rl = require('readline');\n\nvar i = rl.createInterface(process.stdin, process.stdout, null);\ni.question("What do you think of node.js?", function(answer) {\n  // TODO: Log the answer in a database\n  console.log("Thank you for your valuable feedback.");\n\n  // These two lines together allow the program to terminate. Without\n  // them, it would run forever.\n  i.close();\n  process.stdin.destroy();\n});
\n", - "methods": [ - { - "textRaw": "rl.createInterface(input, output, completer)", - "type": "method", - "name": "createInterface", - "desc": "

Takes two streams and creates a readline interface. The completer function\nis used for autocompletion. When given a substring, it returns [[substr1,\nsubstr2, ...], originalsubstring].\n\n

\n

Also completer can be run in async mode if it accepts two arguments:\n\n

\n

function completer(linePartial, callback) {\n callback(null, [['123'], linePartial]);\n }\n\n

\n

createInterface is commonly used with process.stdin and\nprocess.stdout in order to accept user input:\n\n

\n
var readline = require('readline'),\n  rl = readline.createInterface(process.stdin, process.stdout);
\n", - "signatures": [ - { - "params": [ - { - "name": "input" - }, - { - "name": "output" - }, - { - "name": "completer" - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: Interface", - "type": "class", - "name": "Interface", - "desc": "

The class that represents a readline interface with a stdin and stdout\nstream.\n\n

\n", - "methods": [ - { - "textRaw": "rl.setPrompt(prompt, length)", - "type": "method", - "name": "setPrompt", - "desc": "

Sets the prompt, for example when you run node on the command line, you see\n> , which is node's prompt.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "prompt" - }, - { - "name": "length" - } - ] - } - ] - }, - { - "textRaw": "rl.prompt()", - "type": "method", - "name": "prompt", - "desc": "

Readies readline for input from the user, putting the current setPrompt\noptions on a new line, giving the user a new spot to write.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "rl.question(query, callback)", - "type": "method", - "name": "question", - "desc": "

Prepends the prompt with query and invokes callback with the user's\nresponse. Displays the query to the user, and then invokes callback with the\nuser's response after it has been typed.\n\n

\n

Example usage:\n\n

\n
interface.question('What is your favorite food?', function(answer) {\n  console.log('Oh, so your favorite food is ' + answer);\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "query" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "rl.close()", - "type": "method", - "name": "close", - "desc": "

Closes tty.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "rl.pause()", - "type": "method", - "name": "pause", - "desc": "

Pauses tty.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "rl.resume()", - "type": "method", - "name": "resume", - "desc": "

Resumes tty.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "rl.write()", - "type": "method", - "name": "write", - "desc": "

Writes to tty.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ], - "events": [ - { - "textRaw": "Event: 'line'", - "type": "event", - "name": "line", - "desc": "

function (line) {}\n\n

\n

Emitted whenever the in stream receives a \\n, usually received when the\nuser hits enter, or return. This is a good hook to listen for user input.\n\n

\n

Example of listening for line:\n\n

\n
rl.on('line', function (cmd) {\n  console.log('You just typed: '+cmd);\n});
\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () {}\n\n

\n

Emitted whenever the in stream receives a ^C or ^D, respectively known\nas SIGINT and EOT. This is a good way to know the user is finished using\nyour program.\n\n

\n

Example of listening for close, and exiting the program afterward:\n\n

\n
rl.on('close', function() {\n  console.log('goodbye!');\n  process.exit(0);\n});
\n

Here's an example of how to use all these together to craft a tiny command\nline interface:\n\n

\n
var readline = require('readline'),\n  rl = readline.createInterface(process.stdin, process.stdout),\n  prefix = 'OHAI> ';\n\nrl.on('line', function(line) {\n  switch(line.trim()) {\n    case 'hello':\n      console.log('world!');\n      break;\n    default:\n      console.log('Say what? I might have heard `' + line.trim() + '`');\n      break;\n  }\n  rl.setPrompt(prefix, prefix.length);\n  rl.prompt();\n}).on('close', function() {\n  console.log('Have a great day!');\n  process.exit(0);\n});\nconsole.log(prefix + 'Good to see you. Try typing stuff.');\nrl.setPrompt(prefix, prefix.length);\nrl.prompt();
\n

Take a look at this slightly more complicated\nexample, and\nhttp-console for a real-life use\ncase.\n

\n", - "params": [] - } - ] - } - ], - "type": "module", - "displayName": "Readline" - } - ] -} --- a/doc/api/api/repl.html +++ /dev/null @@ -1,237 +0,0 @@ - - - - - REPL Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

REPL#

-

A Read-Eval-Print-Loop (REPL) is available both as a standalone program and easily -includable in other programs. REPL provides a way to interactively run -JavaScript and see the results. It can be used for debugging, testing, or -just trying things out. - -

-

By executing node without any arguments from the command-line you will be -dropped into the REPL. It has simplistic emacs line-editing. - -

-
mjr:~$ node
-Type '.help' for options.
-> a = [ 1, 2, 3];
-[ 1, 2, 3 ]
-> a.forEach(function (v) {
-...   console.log(v);
-...   });
-1
-2
-3
-

For advanced line-editors, start node with the environmental variable NODE_NO_READLINE=1. -This will start the REPL in canonical terminal settings which will allow you to use with rlwrap. - -

-

For example, you could add this to your bashrc file: - -

-
alias node="env NODE_NO_READLINE=1 rlwrap node"
-

repl.start([prompt], [stream], [eval], [useGlobal], [ignoreUndefined])#

-

Starts a REPL with prompt as the prompt and stream for all I/O. prompt -is optional and defaults to > . stream is optional and defaults to -process.stdin. eval is optional too and defaults to async wrapper for -eval(). - -

-

If useGlobal is set to true, then the repl will use the global object, -instead of running scripts in a separate context. Defaults to false. - -

-

If ignoreUndefined is set to true, then the repl will not output return value -of command if it's undefined. Defaults to false. - -

-

You can use your own eval function if it has following signature: - -

-
function eval(cmd, callback) {
-  callback(null, result);
-}
-

Multiple REPLs may be started against the same running instance of node. Each -will share the same global object but will have unique I/O. - -

-

Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket: - -

-
var net = require("net"),
-    repl = require("repl");
-
-connections = 0;
-
-repl.start("node via stdin> ");
-
-net.createServer(function (socket) {
-  connections += 1;
-  repl.start("node via Unix socket> ", socket);
-}).listen("/tmp/node-repl-sock");
-
-net.createServer(function (socket) {
-  connections += 1;
-  repl.start("node via TCP socket> ", socket);
-}).listen(5001);
-

Running this program from the command line will start a REPL on stdin. Other -REPL clients may connect through the Unix socket or TCP socket. telnet is useful -for connecting to TCP sockets, and socat can be used to connect to both Unix and -TCP sockets. - -

-

By starting a REPL from a Unix socket-based server instead of stdin, you can -connect to a long-running node process without restarting it. - - -

-

REPL Features#

- - -

Inside the REPL, Control+D will exit. Multi-line expressions can be input. -Tab completion is supported for both global and local variables. - -

-

The special variable _ (underscore) contains the result of the last expression. - -

-
> [ "a", "b", "c" ]
-[ 'a', 'b', 'c' ]
-> _.length
-3
-> _ += 1
-4
-

The REPL provides access to any variables in the global scope. You can expose -a variable to the REPL explicitly by assigning it to the context object -associated with each REPLServer. For example: - -

-
// repl_test.js
-var repl = require("repl"),
-    msg = "message";
-
-repl.start().context.m = msg;
-

Things in the context object appear as local within the REPL: - -

-
mjr:~$ node repl_test.js
-> m
-'message'
-

There are a few special REPL commands: - -

-
    -
  • .break - While inputting a multi-line expression, sometimes you get lost -or just don't care about completing it. .break will start over.
    • -
  • .clear - Resets the context object to an empty object and clears any -multi-line expression.
    • -
  • .exit - Close the I/O stream, which will cause the REPL to exit.
    • -
  • .help - Show this list of special commands.
    • -
  • .save - Save the current REPL session to a file
    -

    .save ./file/to/save.js

    -
    -
    • -
  • .load - Load a file into the current REPL session.
    -

    .load ./file/to/load.js

    -
    -
    • -
-

The following key combinations in the REPL have these special effects: - -

-
    -
  • <ctrl>C - Similar to the .break keyword. Terminates the current -command. Press twice on a blank line to forcibly exit.
    • -
  • <ctrl>D - Similar to the .exit keyword.
    • -
- -
-
-
- - - - - - - - - - --- a/doc/api/api/repl.json +++ /dev/null @@ -1,54 +0,0 @@ -{ - "source": "doc/api/repl.markdown", - "modules": [ - { - "textRaw": "REPL", - "name": "repl", - "desc": "

A Read-Eval-Print-Loop (REPL) is available both as a standalone program and easily\nincludable in other programs. REPL provides a way to interactively run\nJavaScript and see the results. It can be used for debugging, testing, or\njust trying things out.\n\n

\n

By executing node without any arguments from the command-line you will be\ndropped into the REPL. It has simplistic emacs line-editing.\n\n

\n
mjr:~$ node\nType '.help' for options.\n> a = [ 1, 2, 3];\n[ 1, 2, 3 ]\n> a.forEach(function (v) {\n...   console.log(v);\n...   });\n1\n2\n3
\n

For advanced line-editors, start node with the environmental variable NODE_NO_READLINE=1.\nThis will start the REPL in canonical terminal settings which will allow you to use with rlwrap.\n\n

\n

For example, you could add this to your bashrc file:\n\n

\n
alias node="env NODE_NO_READLINE=1 rlwrap node"
\n", - "methods": [ - { - "textRaw": "repl.start([prompt], [stream], [eval], [useGlobal], [ignoreUndefined])", - "type": "method", - "name": "start", - "desc": "

Starts a REPL with prompt as the prompt and stream for all I/O. prompt\nis optional and defaults to > . stream is optional and defaults to\nprocess.stdin. eval is optional too and defaults to async wrapper for\neval().\n\n

\n

If useGlobal is set to true, then the repl will use the global object,\ninstead of running scripts in a separate context. Defaults to false.\n\n

\n

If ignoreUndefined is set to true, then the repl will not output return value\nof command if it's undefined. Defaults to false.\n\n

\n

You can use your own eval function if it has following signature:\n\n

\n
function eval(cmd, callback) {\n  callback(null, result);\n}
\n

Multiple REPLs may be started against the same running instance of node. Each\nwill share the same global object but will have unique I/O.\n\n

\n

Here is an example that starts a REPL on stdin, a Unix socket, and a TCP socket:\n\n

\n
var net = require("net"),\n    repl = require("repl");\n\nconnections = 0;\n\nrepl.start("node via stdin> ");\n\nnet.createServer(function (socket) {\n  connections += 1;\n  repl.start("node via Unix socket> ", socket);\n}).listen("/tmp/node-repl-sock");\n\nnet.createServer(function (socket) {\n  connections += 1;\n  repl.start("node via TCP socket> ", socket);\n}).listen(5001);
\n

Running this program from the command line will start a REPL on stdin. Other\nREPL clients may connect through the Unix socket or TCP socket. telnet is useful\nfor connecting to TCP sockets, and socat can be used to connect to both Unix and\nTCP sockets.\n\n

\n

By starting a REPL from a Unix socket-based server instead of stdin, you can\nconnect to a long-running node process without restarting it.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "prompt", - "optional": true - }, - { - "name": "stream", - "optional": true - }, - { - "name": "eval", - "optional": true - }, - { - "name": "useGlobal", - "optional": true - }, - { - "name": "ignoreUndefined", - "optional": true - } - ] - } - ] - } - ], - "miscs": [ - { - "textRaw": "REPL Features", - "name": "REPL Features", - "type": "misc", - "desc": "

Inside the REPL, Control+D will exit. Multi-line expressions can be input.\nTab completion is supported for both global and local variables.\n\n

\n

The special variable _ (underscore) contains the result of the last expression.\n\n

\n
> [ "a", "b", "c" ]\n[ 'a', 'b', 'c' ]\n> _.length\n3\n> _ += 1\n4
\n

The REPL provides access to any variables in the global scope. You can expose\na variable to the REPL explicitly by assigning it to the context object\nassociated with each REPLServer. For example:\n\n

\n
// repl_test.js\nvar repl = require("repl"),\n    msg = "message";\n\nrepl.start().context.m = msg;
\n

Things in the context object appear as local within the REPL:\n\n

\n
mjr:~$ node repl_test.js\n> m\n'message'
\n

There are a few special REPL commands:\n\n

\n
    \n
  • .break - While inputting a multi-line expression, sometimes you get lost\nor just don't care about completing it. .break will start over.
    • \n
  • .clear - Resets the context object to an empty object and clears any\nmulti-line expression.
    • \n
  • .exit - Close the I/O stream, which will cause the REPL to exit.
    • \n
  • .help - Show this list of special commands.
    • \n
  • .save - Save the current REPL session to a file
    \n

    .save ./file/to/save.js

    \n
    \n
    • \n
  • .load - Load a file into the current REPL session.
    \n

    .load ./file/to/load.js

    \n
    \n
    • \n
\n

The following key combinations in the REPL have these special effects:\n\n

\n
    \n
  • <ctrl>C - Similar to the .break keyword. Terminates the current\ncommand. Press twice on a blank line to forcibly exit.
    • \n
  • <ctrl>D - Similar to the .exit keyword.
    • \n
\n" - } - ], - "type": "module", - "displayName": "REPL" - } - ] -} --- a/doc/api/api/stdio.html +++ /dev/null @@ -1,159 +0,0 @@ - - - - - console Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

console#

-
Stability: 4 - API Frozen
-
    -
  • {Object}
    • -
- - -

For printing to stdout and stderr. Similar to the console object functions -provided by most web browsers, here the output is sent to stdout or stderr. - - -

-

console.log()#

-

Prints to stdout with newline. This function can take multiple arguments in a -printf()-like way. Example: - -

-
console.log('count: %d', count);
-

If formatting elements are not found in the first string then util.inspect -is used on each argument. -See util.format() for more information. - -

-

console.info()#

-

Same as console.log. - -

-

console.warn()#

-

console.error()#

-

Same as console.log but prints to stderr. - -

-

console.dir(obj)#

-

Uses util.inspect on obj and prints resulting string to stderr. - -

-

console.time(label)#

-

Mark a time. - - -

-

console.timeEnd(label)#

-

Finish timer, record output. Example - -

-
console.time('100-elements');
-for (var i = 0; i < 100; i++) {
-  ;
-}
-console.timeEnd('100-elements');
-

console.trace()#

-

Print a stack trace to stderr of the current position. - -

-

console.assert()#

-

Same as assert.ok(). - -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/stdio.json +++ /dev/null @@ -1,129 +0,0 @@ -{ - "source": "doc/api/stdio.markdown", - "globals": [ - { - "textRaw": "console", - "name": "console", - "stability": 4, - "stabilityText": "API Frozen", - "type": "global", - "desc": "

For printing to stdout and stderr. Similar to the console object functions\nprovided by most web browsers, here the output is sent to stdout or stderr.\n\n\n

\n", - "methods": [ - { - "textRaw": "console.log()", - "type": "method", - "name": "log", - "desc": "

Prints to stdout with newline. This function can take multiple arguments in a\nprintf()-like way. Example:\n\n

\n
console.log('count: %d', count);
\n

If formatting elements are not found in the first string then util.inspect\nis used on each argument.\nSee util.format() for more information.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.info()", - "type": "method", - "name": "info", - "desc": "

Same as console.log.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.warn()", - "type": "method", - "name": "warn", - "desc": "

Same as console.log but prints to stderr.\n\n

\n", - "signatures": [ - { - "params": [] - }, - { - "params": [] - } - ] - }, - { - "textRaw": "console.error()", - "type": "method", - "name": "error", - "desc": "

Same as console.log but prints to stderr.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.dir(obj)", - "type": "method", - "name": "dir", - "desc": "

Uses util.inspect on obj and prints resulting string to stderr.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "obj" - } - ] - } - ] - }, - { - "textRaw": "console.time(label)", - "type": "method", - "name": "time", - "desc": "

Mark a time.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "label" - } - ] - } - ] - }, - { - "textRaw": "console.timeEnd(label)", - "type": "method", - "name": "timeEnd", - "desc": "

Finish timer, record output. Example\n\n

\n
console.time('100-elements');\nfor (var i = 0; i < 100; i++) {\n  ;\n}\nconsole.timeEnd('100-elements');
\n", - "signatures": [ - { - "params": [ - { - "name": "label" - } - ] - } - ] - }, - { - "textRaw": "console.trace()", - "type": "method", - "name": "trace", - "desc": "

Print a stack trace to stderr of the current position.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "console.assert()", - "type": "method", - "name": "assert", - "desc": "

Same as assert.ok().\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - } - ] -} --- a/doc/api/api/stream.html +++ /dev/null @@ -1,310 +0,0 @@ - - - - - Stream Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Stream#

-
Stability: 2 - Unstable
-

A stream is an abstract interface implemented by various objects in Node. -For example a request to an HTTP server is a stream, as is stdout. Streams -are readable, writable, or both. All streams are instances of EventEmitter. - -

-

You can load up the Stream base class by doing require('stream'). - -

-

Readable Stream#

- - -

A Readable Stream has the following methods, members, and events. - -

-

Event: 'data'#

-

function (data) { } - -

-

The 'data' event emits either a Buffer (by default) or a string if -setEncoding() was used. - -

-

Note that the data will be lost if there is no listener when a -Readable Stream emits a 'data' event. - -

-

Event: 'end'#

-

function () { } - -

-

Emitted when the stream has received an EOF (FIN in TCP terminology). -Indicates that no more 'data' events will happen. If the stream is also -writable, it may be possible to continue writing. - -

-

Event: 'error'#

-

function (exception) { } - -

-

Emitted if there was an error receiving data. - -

-

Event: 'close'#

-

function () { } - -

-

Emitted when the underlying file descriptor has been closed. Not all streams -will emit this. (For example, an incoming HTTP request will not emit -'close'.) - -

-

stream.readable#

-

A boolean that is true by default, but turns false after an 'error' -occurred, the stream came to an 'end', or destroy() was called. - -

-

stream.setEncoding(encoding)#

-

Makes the data event emit a string instead of a Buffer. encoding can be -'utf8', 'ascii', or 'base64'. - -

-

stream.pause()#

-

Pauses the incoming 'data' events. - -

-

stream.resume()#

-

Resumes the incoming 'data' events after a pause(). - -

-

stream.destroy()#

-

Closes the underlying file descriptor. Stream will not emit any more events. - -

-

stream.pipe(destination, [options])#

-

This is a Stream.prototype method available on all Streams. - -

-

Connects this read stream to destination WriteStream. Incoming -data on this stream gets written to destination. The destination and source -streams are kept in sync by pausing and resuming as necessary. - -

-

This function returns the destination stream. - -

-

Emulating the Unix cat command: - -

-
process.stdin.resume();
-process.stdin.pipe(process.stdout);
-

By default end() is called on the destination when the source stream emits -end, so that destination is no longer writable. Pass { end: false } as -options to keep the destination stream open. - -

-

This keeps process.stdout open so that "Goodbye" can be written at the end. - -

-
process.stdin.resume();
-
-process.stdin.pipe(process.stdout, { end: false });
-
-process.stdin.on("end", function() {
-  process.stdout.write("Goodbye\n");
-});
-

Writable Stream#

- - -

A Writable Stream has the following methods, members, and events. - -

-

Event: 'drain'#

-

function () { } - -

-

After a write() method returned false, this event is emitted to -indicate that it is safe to write again. - -

-

Event: 'error'#

-

function (exception) { } - -

-

Emitted on error with the exception exception. - -

-

Event: 'close'#

-

function () { } - -

-

Emitted when the underlying file descriptor has been closed. - -

-

Event: 'pipe'#

-

function (src) { } - -

-

Emitted when the stream is passed to a readable stream's pipe method. - -

-

stream.writable#

-

A boolean that is true by default, but turns false after an 'error' -occurred or end() / destroy() was called. - -

-

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)#

-

Same as the above except with a raw buffer. - -

-

stream.end()#

-

Terminates the stream with EOF or FIN. -This call will allow queued write data to be sent before closing the stream. - -

-

stream.end(string, encoding)#

-

Sends string with the given encoding and terminates the stream with EOF -or FIN. This is useful to reduce the number of packets sent. - -

-

stream.end(buffer)#

-

Same as above but with a buffer. - -

-

stream.destroy()#

-

Closes the underlying file descriptor. Stream will not emit any more events. -Any queued write data will not be sent. - -

-

stream.destroySoon()#

-

After the write queue is drained, close the file descriptor. destroySoon() -can still destroy straight away, as long as there is no data left in the queue -for writes. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/stream.json +++ /dev/null @@ -1,277 +0,0 @@ -{ - "source": "doc/api/stream.markdown", - "modules": [ - { - "textRaw": "Stream", - "name": "stream", - "stability": 2, - "stabilityText": "Unstable", - "desc": "

A stream is an abstract interface implemented by various objects in Node.\nFor example a request to an HTTP server is a stream, as is stdout. Streams\nare readable, writable, or both. All streams are instances of EventEmitter.\n\n

\n

You can load up the Stream base class by doing require('stream').\n\n

\n", - "classes": [ - { - "textRaw": "Readable Stream", - "name": "Readable Stream", - "type": "class", - "desc": "

A Readable Stream has the following methods, members, and events.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'data'", - "type": "event", - "name": "data", - "desc": "

function (data) { }\n\n

\n

The 'data' event emits either a Buffer (by default) or a string if\nsetEncoding() was used.\n\n

\n

Note that the data will be lost if there is no listener when a\nReadable Stream emits a 'data' event.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'end'", - "type": "event", - "name": "end", - "desc": "

function () { }\n\n

\n

Emitted when the stream has received an EOF (FIN in TCP terminology).\nIndicates that no more 'data' events will happen. If the stream is also\nwritable, it may be possible to continue writing.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "desc": "

function (exception) { }\n\n

\n

Emitted if there was an error receiving data.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () { }\n\n

\n

Emitted when the underlying file descriptor has been closed. Not all streams\nwill emit this. (For example, an incoming HTTP request will not emit\n'close'.)\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "stream.readable", - "name": "readable", - "desc": "

A boolean that is true by default, but turns false after an 'error'\noccurred, the stream came to an 'end', or destroy() was called.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "stream.setEncoding(encoding)", - "type": "method", - "name": "setEncoding", - "desc": "

Makes the data event emit a string instead of a Buffer. encoding can be\n'utf8', 'ascii', or 'base64'.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "encoding" - } - ] - } - ] - }, - { - "textRaw": "stream.pause()", - "type": "method", - "name": "pause", - "desc": "

Pauses the incoming 'data' events.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "stream.resume()", - "type": "method", - "name": "resume", - "desc": "

Resumes the incoming 'data' events after a pause().\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "stream.destroy()", - "type": "method", - "name": "destroy", - "desc": "

Closes the underlying file descriptor. Stream will not emit any more events.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "stream.pipe(destination, [options])", - "type": "method", - "name": "pipe", - "desc": "

This is a Stream.prototype method available on all Streams.\n\n

\n

Connects this read stream to destination WriteStream. Incoming\ndata on this stream gets written to destination. The destination and source\nstreams are kept in sync by pausing and resuming as necessary.\n\n

\n

This function returns the destination stream.\n\n

\n

Emulating the Unix cat command:\n\n

\n
process.stdin.resume();\nprocess.stdin.pipe(process.stdout);
\n

By default end() is called on the destination when the source stream emits\nend, so that destination is no longer writable. Pass { end: false } as\noptions to keep the destination stream open.\n\n

\n

This keeps process.stdout open so that "Goodbye" can be written at the end.\n\n

\n
process.stdin.resume();\n\nprocess.stdin.pipe(process.stdout, { end: false });\n\nprocess.stdin.on("end", function() {\n  process.stdout.write("Goodbye\\n");\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "destination" - }, - { - "name": "options", - "optional": true - } - ] - } - ] - } - ] - }, - { - "textRaw": "Writable Stream", - "name": "Writable Stream", - "type": "class", - "desc": "

A Writable Stream has the following methods, members, and events.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'drain'", - "type": "event", - "name": "drain", - "desc": "

function () { }\n\n

\n

After a write() method returned false, this event is emitted to\nindicate that it is safe to write again.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'error'", - "type": "event", - "name": "error", - "desc": "

function (exception) { }\n\n

\n

Emitted on error with the exception exception.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'close'", - "type": "event", - "name": "close", - "desc": "

function () { }\n\n

\n

Emitted when the underlying file descriptor has been closed.\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'pipe'", - "type": "event", - "name": "pipe", - "desc": "

function (src) { }\n\n

\n

Emitted when the stream is passed to a readable stream's pipe method.\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "stream.writable", - "name": "writable", - "desc": "

A boolean that is true by default, but turns false after an 'error'\noccurred or end() / destroy() was called.\n\n

\n" - } - ], - "methods": [ - { - "textRaw": "stream.write(string, [encoding], [fd])", - "type": "method", - "name": "write", - "desc": "

Writes string with the given encoding to the stream. Returns true if\nthe string has been flushed to the kernel buffer. Returns false to\nindicate that the kernel buffer is full, and the data will be sent out in\nthe future. The 'drain' event will indicate when the kernel buffer is\nempty again. The encoding defaults to 'utf8'.\n\n

\n

If the optional fd parameter is specified, it is interpreted as an integral\nfile descriptor to be sent over the stream. This is only supported for UNIX\nstreams, and is silently ignored otherwise. When writing a file descriptor in\nthis manner, closing the descriptor before the stream drains risks sending an\ninvalid (closed) FD.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "string" - }, - { - "name": "encoding", - "optional": true - }, - { - "name": "fd", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "stream.write(buffer)", - "type": "method", - "name": "write", - "desc": "

Same as the above except with a raw buffer.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buffer" - } - ] - } - ] - }, - { - "textRaw": "stream.end()", - "type": "method", - "name": "end", - "desc": "

Terminates the stream with EOF or FIN.\nThis call will allow queued write data to be sent before closing the stream.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "stream.end(string, encoding)", - "type": "method", - "name": "end", - "desc": "

Sends string with the given encoding and terminates the stream with EOF\nor FIN. This is useful to reduce the number of packets sent.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "string" - }, - { - "name": "encoding" - } - ] - } - ] - }, - { - "textRaw": "stream.end(buffer)", - "type": "method", - "name": "end", - "desc": "

Same as above but with a buffer.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buffer" - } - ] - } - ] - }, - { - "textRaw": "stream.destroy()", - "type": "method", - "name": "destroy", - "desc": "

Closes the underlying file descriptor. Stream will not emit any more events.\nAny queued write data will not be sent.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "stream.destroySoon()", - "type": "method", - "name": "destroySoon", - "desc": "

After the write queue is drained, close the file descriptor. destroySoon()\ncan still destroy straight away, as long as there is no data left in the queue\nfor writes.\n

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - } - ], - "type": "module", - "displayName": "Stream" - } - ] -} --- a/doc/api/api/string_decoder.html +++ /dev/null @@ -1,87 +0,0 @@ - - - - - Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- -
-

Table of Contents

- -
- -
- -
-
-
- - - - - - - - - - --- a/doc/api/api/string_decoder.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "source": "doc/api/string_decoder.markdown" -} --- a/doc/api/api/synopsis.html +++ /dev/null @@ -1,113 +0,0 @@ - - - - - Synopsis Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- -
-

Table of Contents

- - -
- -
-

Synopsis#

- - -

An example of a web server written with Node which responds with 'Hello -World': - -

-
var http = require('http');
-
-http.createServer(function (request, response) {
-  response.writeHead(200, {'Content-Type': 'text/plain'});
-  response.end('Hello World\n');
-}).listen(8124);
-
-console.log('Server running at http://127.0.0.1:8124/');
-

To run the server, put the code into a file called example.js and execute -it with the node program - -

-
> node example.js
-Server running at http://127.0.0.1:8124/
-

All of the examples in the documentation can be run similarly. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/synopsis.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "source": "doc/api/synopsis.markdown", - "miscs": [ - { - "textRaw": "Synopsis", - "name": "Synopsis", - "type": "misc", - "desc": "

An example of a web server written with Node which responds with 'Hello\nWorld':\n\n

\n
var http = require('http');\n\nhttp.createServer(function (request, response) {\n  response.writeHead(200, {'Content-Type': 'text/plain'});\n  response.end('Hello World\\n');\n}).listen(8124);\n\nconsole.log('Server running at http://127.0.0.1:8124/');
\n

To run the server, put the code into a file called example.js and execute\nit with the node program\n\n

\n
> node example.js\nServer running at http://127.0.0.1:8124/
\n

All of the examples in the documentation can be run similarly.\n

\n" - } - ] -} --- a/doc/api/api/timers.html +++ /dev/null @@ -1,127 +0,0 @@ - - - - - Timers Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Timers#

-
Stability: 5 - Locked
-

All of the timer functions are globals. You do not need to require() -this module in order to use them. - -

-

setTimeout(callback, delay, [arg], [...])#

-

To schedule execution of a one-time callback after delay milliseconds. Returns a -timeoutId for possible use with clearTimeout(). Optionally you can -also pass arguments to the callback. - -

-

It is important to note that your callback will probably not be called in exactly -delay milliseconds - Node.js makes no guarantees about the exact timing of when -the callback will fire, nor of the ordering things will fire in. The callback will -be called as close as possible to the time specified. - -

-

clearTimeout(timeoutId)#

-

Prevents a timeout from triggering. - -

-

setInterval(callback, delay, [arg], [...])#

-

To schedule the repeated execution of callback every delay milliseconds. -Returns a intervalId for possible use with clearInterval(). Optionally -you can also pass arguments to the callback. - -

-

clearInterval(intervalId)#

-

Stops a interval from triggering. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/timers.json +++ /dev/null @@ -1,98 +0,0 @@ -{ - "source": "doc/api/timers.markdown", - "modules": [ - { - "textRaw": "Timers", - "name": "timers", - "stability": 5, - "stabilityText": "Locked", - "desc": "

All of the timer functions are globals. You do not need to require()\nthis module in order to use them.\n\n

\n", - "methods": [ - { - "textRaw": "setTimeout(callback, delay, [arg], [...])", - "type": "method", - "name": "setTimeout", - "desc": "

To schedule execution of a one-time callback after delay milliseconds. Returns a\ntimeoutId for possible use with clearTimeout(). Optionally you can\nalso pass arguments to the callback.\n\n

\n

It is important to note that your callback will probably not be called in exactly\ndelay milliseconds - Node.js makes no guarantees about the exact timing of when\nthe callback will fire, nor of the ordering things will fire in. The callback will\nbe called as close as possible to the time specified.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "callback" - }, - { - "name": "delay" - }, - { - "name": "arg", - "optional": true - }, - { - "name": "...", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "clearTimeout(timeoutId)", - "type": "method", - "name": "clearTimeout", - "desc": "

Prevents a timeout from triggering.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "timeoutId" - } - ] - } - ] - }, - { - "textRaw": "setInterval(callback, delay, [arg], [...])", - "type": "method", - "name": "setInterval", - "desc": "

To schedule the repeated execution of callback every delay milliseconds.\nReturns a intervalId for possible use with clearInterval(). Optionally\nyou can also pass arguments to the callback.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "callback" - }, - { - "name": "delay" - }, - { - "name": "arg", - "optional": true - }, - { - "name": "...", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "clearInterval(intervalId)", - "type": "method", - "name": "clearInterval", - "desc": "

Stops a interval from triggering.\n

\n", - "signatures": [ - { - "params": [ - { - "name": "intervalId" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "Timers" - } - ] -} --- a/doc/api/api/tls.html +++ /dev/null @@ -1,599 +0,0 @@ - - - - - TLS (SSL) Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

TLS (SSL)#

-
Stability: 3 - Stable
-

Use require('tls') to access this module. - -

-

The tls module uses OpenSSL to provide Transport Layer Security and/or -Secure Socket Layer: encrypted stream communication. - -

-

TLS/SSL is a public/private key infrastructure. Each client and each -server must have a private key. A private key is created like this - -

-
openssl genrsa -out ryans-key.pem 1024
-

All severs and some clients need to have a certificate. Certificates are public -keys signed by a Certificate Authority or self-signed. The first step to -getting a certificate is to create a "Certificate Signing Request" (CSR) -file. This is done with: - -

-
openssl req -new -key ryans-key.pem -out ryans-csr.pem
-

To create a self-signed certificate with the CSR, do this: - -

-
openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem
-

Alternatively you can send the CSR to a Certificate Authority for signing. - -

-

(TODO: docs on creating a CA, for now interested users should just look at -test/fixtures/keys/Makefile in the Node source code) - -

-

To create .pfx or .p12, do this: - -

-
openssl pkcs12 -export -in agent5-cert.pem -inkey agent5-key.pem \
-    -certfile ca-cert.pem -out agent5.pfx
-
    -
  • in: certificate
    • -
  • inkey: private key
    • -
  • certfile: all CA certs concatenated in one file like -cat ca1-cert.pem ca2-cert.pem > ca-cert.pem
    • -
-

Client-initiated renegotiation attack mitigation#

- - -

The TLS protocol lets the client renegotiate certain aspects of the TLS session. -Unfortunately, session renegotiation requires a disproportional amount of -server-side resources, which makes it a potential vector for denial-of-service -attacks. - -

-

To mitigate this, renegotiations are limited to three times every 10 minutes. An -error is emitted on the CleartextStream instance when -the threshold is exceeded. The limits are configurable: - -

-
    -

  • tls.CLIENT_RENEG_LIMIT: renegotiation limit, default is 3.

    -
    • -

  • tls.CLIENT_RENEG_WINDOW: renegotiation window in seconds, default is

    -
                           10 minutes.
    -
    • -
-

Don't change the defaults unless you know what you are doing. - -

-

To test your server, connect to it with openssl s_client -connect address:port -and tap R<CR> (that's the letter R followed by a carriage return) a few -times. - - -

-

NPN and SNI#

- - -

NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS -handshake extensions allowing you: - -

-
    -
  • NPN - to use one TLS server for multiple protocols (HTTP, SPDY)
    • -
  • SNI - to use one TLS server for multiple hostnames with different SSL -certificates.
    • -
-

tls.createServer(options, [secureConnectionListener])#

-

Creates a new tls.Server. -The connectionListener argument is automatically set as a listener for the -secureConnection event. -The options object has these possibilities: - -

-
    -

  • pfx: A string or Buffer containing the private key, certificate and -CA certs of the server in PFX or PKCS12 format. (Mutually exclusive with -the key, cert and ca options.)

    -
    • -

  • key: A string or Buffer containing the private key of the server in -PEM format. (Required)

    -
    • -

  • passphrase: A string of passphrase for the private key or pfx.

    -
    • -

  • cert: A string or Buffer containing the certificate key of the server in -PEM format. (Required)

    -
    • -

  • ca: An array of strings or Buffers of trusted certificates. If this is -omitted several well known "root" CAs will be used, like VeriSign. -These are used to authorize connections.

    -
    • -

  • ciphers: A string describing the ciphers to use or exclude. Consult -http://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for -details on the format.

    -
    • -

  • requestCert: If true the server will request a certificate from -clients that connect and attempt to verify that certificate. Default: -false.

    -
    • -

  • rejectUnauthorized: If true the server will reject any connection -which is not authorized with the list of supplied CAs. This option only -has an effect if requestCert is true. Default: false.

    -
    • -

  • NPNProtocols: An array or Buffer of possible NPN protocols. (Protocols -should be ordered by their priority).

    -
    • -

  • SNICallback: A function that will be called if client supports SNI TLS -extension. Only one argument will be passed to it: servername. And -SNICallback should return SecureContext instance. -(You can use crypto.createCredentials(...).context to get proper -SecureContext). If SNICallback wasn't provided - default callback with -high-level API will be used (see below).

    -
    • -

  • sessionIdContext: A string containing a opaque identifier for session -resumption. If requestCert is true, the default is MD5 hash value -generated from command-line. Otherwise, the default is not provided.

    -
    • -
-

Here is a simple example echo server: - -

-
var tls = require('tls');
-var fs = require('fs');
-
-var options = {
-  key: fs.readFileSync('server-key.pem'),
-  cert: fs.readFileSync('server-cert.pem'),
-
-  // This is necessary only if using the client certificate authentication.
-  requestCert: true,
-
-  // This is necessary only if the client uses the self-signed certificate.
-  ca: [ fs.readFileSync('client-cert.pem') ]
-};
-
-var server = tls.createServer(options, function(cleartextStream) {
-  console.log('server connected',
-              cleartextStream.authorized ? 'authorized' : 'unauthorized');
-  cleartextStream.write("welcome!\n");
-  cleartextStream.setEncoding('utf8');
-  cleartextStream.pipe(cleartextStream);
-});
-server.listen(8000, function() {
-  console.log('server bound');
-});
-

Or - -

-
var tls = require('tls');
-var fs = require('fs');
-
-var options = {
-  pfx: fs.readFileSync('server.pfx'),
-
-  // This is necessary only if using the client certificate authentication.
-  requestCert: true,
-
-};
-
-var server = tls.createServer(options, function(cleartextStream) {
-  console.log('server connected',
-              cleartextStream.authorized ? 'authorized' : 'unauthorized');
-  cleartextStream.write("welcome!\n");
-  cleartextStream.setEncoding('utf8');
-  cleartextStream.pipe(cleartextStream);
-});
-server.listen(8000, function() {
-  console.log('server bound');
-});
-

You can test this server by connecting to it with openssl s_client: - - -

-
openssl s_client -connect 127.0.0.1:8000
-

tls.connect(port, [host], [options], [secureConnectListener])#

-

Creates a new client connection to the given port and host. (If host -defaults to localhost.) options should be an object which specifies - -

-
    -

  • pfx: A string or Buffer containing the private key, certificate and -CA certs of the server in PFX or PKCS12 format.

    -
    • -

  • key: A string or Buffer containing the private key of the client in -PEM format.

    -
    • -

  • passphrase: A string of passphrase for the private key or pfx.

    -
    • -

  • cert: A string or Buffer containing the certificate key of the client in -PEM format.

    -
    • -

  • ca: An array of strings or Buffers of trusted certificates. If this is -omitted several well known "root" CAs will be used, like VeriSign. -These are used to authorize connections.

    -
    • -

  • NPNProtocols: An array of string or Buffer containing supported NPN -protocols. Buffer should have following format: 0x05hello0x05world, -where first byte is next protocol name's length. (Passing array should -usually be much simpler: ['hello', 'world'].)

    -
    • -

  • servername: Servername for SNI (Server Name Indication) TLS extension.

    -
    • -

  • socket: Establish secure connection on a given socket rather than -creating a new socket. If this option is specified, host and port -are ignored. This is intended FOR INTERNAL USE ONLY. As with all -undocumented APIs in Node, they should not be used.

    -
    • -
-

The secureConnectListener parameter will be added as a listener for the -'secureConnect' event. - -

-

tls.connect() returns a CleartextStream object. - -

-

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

-
var tls = require('tls');
-var fs = require('fs');
-
-var options = {
-  // These are necessary only if using the client certificate authentication
-  key: fs.readFileSync('client-key.pem'),
-  cert: fs.readFileSync('client-cert.pem'),
-
-  // This is necessary only if the server uses the self-signed certificate
-  ca: [ fs.readFileSync('server-cert.pem') ]
-};
-
-var cleartextStream = tls.connect(8000, options, function() {
-  console.log('client connected',
-              cleartextStream.authorized ? 'authorized' : 'unauthorized');
-  process.stdin.pipe(cleartextStream);
-  process.stdin.resume();
-});
-cleartextStream.setEncoding('utf8');
-cleartextStream.on('data', function(data) {
-  console.log(data);
-});
-cleartextStream.on('end', function() {
-  server.close();
-});
-

Or - -

-
var tls = require('tls');
-var fs = require('fs');
-
-var options = {
-  pfx: fs.readFileSync('client.pfx')
-};
-
-var cleartextStream = tls.connect(8000, options, function() {
-  console.log('client connected',
-              cleartextStream.authorized ? 'authorized' : 'unauthorized');
-  process.stdin.pipe(cleartextStream);
-  process.stdin.resume();
-});
-cleartextStream.setEncoding('utf8');
-cleartextStream.on('data', function(data) {
-  console.log(data);
-});
-cleartextStream.on('end', function() {
-  server.close();
-});
-

tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])#

-

Creates a new secure pair object with two streams, one of which reads/writes -encrypted data, and one reads/writes cleartext data. -Generally the encrypted one is piped to/from an incoming encrypted data stream, -and the cleartext one is used as a replacement for the initial encrypted stream. - -

-
    -

  • credentials: A credentials object from crypto.createCredentials( ... )

    -
    • -

  • isServer: A boolean indicating whether this tls connection should be -opened as a server or a client.

    -
    • -

  • requestCert: A boolean indicating whether a server should request a -certificate from a connecting client. Only applies to server connections.

    -
    • -

  • rejectUnauthorized: A boolean indicating whether a server should -automatically reject clients with invalid certificates. Only applies to -servers with requestCert enabled.

    -
    • -
-

tls.createSecurePair() returns a SecurePair object with -cleartext and encrypted stream properties. - -

-

Class: SecurePair#

-

Returned by tls.createSecurePair. - -

-

Event: 'secure'#

-

The event is emitted from the SecurePair once the pair has successfully -established a secure connection. - -

-

Similarly to the checking for the server 'secureConnection' event, -pair.cleartext.authorized should be checked to confirm whether the certificate -used properly authorized. - -

-

Class: tls.Server#

-

This class is a subclass of net.Server and has the same methods on it. -Instead of accepting just raw TCP connections, this accepts encrypted -connections using TLS or SSL. - -

-

Event: 'secureConnection'#

-

function (cleartextStream) {} - -

-

This event is emitted after a new connection has been successfully -handshaked. The argument is a instance of -CleartextStream. It has all the common stream methods -and events. - -

-

cleartextStream.authorized is a boolean value which indicates if the -client has verified by one of the supplied certificate authorities for the -server. If cleartextStream.authorized is false, then -cleartextStream.authorizationError is set to describe how authorization -failed. Implied but worth mentioning: depending on the settings of the TLS -server, you unauthorized connections may be accepted. -cleartextStream.npnProtocol is a string containing selected NPN protocol. -cleartextStream.servername is a string containing servername requested with -SNI. - - -

-

Event: 'clientError'#

-

function (exception) { } - -

-

When a client connection emits an 'error' event before secure connection is -established - it will be forwarded here. - - -

-

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

-

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). - -

-

This function is asynchronous. The last parameter callback will be called -when the server has been bound. - -

-

See net.Server for more information. - - -

-

server.close()#

-

Stops the server from accepting new connections. This function is -asynchronous, the server is finally closed when the server emits a 'close' -event. - -

-

server.address()#

-

Returns the bound address and port of the server as reported by the operating -system. -See net.Server.address() for more information. - -

-

server.addContext(hostname, credentials)#

-

Add secure context that will be used if client request's SNI hostname is -matching passed hostname (wildcards can be used). credentials can contain -key, cert and ca. - -

-

server.maxConnections#

-

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

-

server.connections#

-

The number of concurrent connections on the server. - - -

-

Class: tls.CleartextStream#

-

This is a stream on top of the Encrypted stream that makes it possible to -read/write an encrypted data as a cleartext data. - -

-

This instance implements a duplex Stream interfaces. -It has all the common stream methods and events. - -

-

A ClearTextStream is the clear member of a SecurePair object. - -

-

Event: 'secureConnect'#

-

This event is emitted after a new connection has been successfully handshaked. -The listener will be called no matter if the server's certificate was -authorized or not. It is up to the user to test cleartextStream.authorized -to see if the server certificate was signed by one of the specified CAs. -If cleartextStream.authorized === false then the error can be found in -cleartextStream.authorizationError. Also if NPN was used - you can check -cleartextStream.npnProtocol for negotiated protocol. - -

-

cleartextStream.authorized#

-

A boolean that is true if the peer certificate was signed by one of the -specified CAs, otherwise false - -

-

cleartextStream.authorizationError#

-

The reason why the peer's certificate has not been verified. This property -becomes available only when cleartextStream.authorized === false. - -

-

cleartextStream.getPeerCertificate()#

-

Returns an object representing the peer's certificate. The returned object has -some properties corresponding to the field of the certificate. - -

-

Example: - -

-
{ subject: 
-   { C: 'UK',
-     ST: 'Acknack Ltd',
-     L: 'Rhys Jones',
-     O: 'node.js',
-     OU: 'Test TLS Certificate',
-     CN: 'localhost' },
-  issuer: 
-   { C: 'UK',
-     ST: 'Acknack Ltd',
-     L: 'Rhys Jones',
-     O: 'node.js',
-     OU: 'Test TLS Certificate',
-     CN: 'localhost' },
-  valid_from: 'Nov 11 09:52:22 2009 GMT',
-  valid_to: 'Nov  6 09:52:22 2029 GMT',
-  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF' }
-

If the peer does not provide a certificate, it returns null or an empty -object. - -

-

cleartextStream.address()#

-

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

-

cleartextStream.remoteAddress#

-

The string representation of the remote IP address. For example, -'74.125.127.100' or '2001:4860:a005::68'. - -

-

cleartextStream.remotePort#

-

The numeric representation of the remote port. For example, 443. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/tls.json +++ /dev/null @@ -1,281 +0,0 @@ -{ - "source": "doc/api/tls.markdown", - "modules": [ - { - "textRaw": "TLS (SSL)", - "name": "tls_(ssl)", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Use require('tls') to access this module.\n\n

\n

The tls module uses OpenSSL to provide Transport Layer Security and/or\nSecure Socket Layer: encrypted stream communication.\n\n

\n

TLS/SSL is a public/private key infrastructure. Each client and each\nserver must have a private key. A private key is created like this\n\n

\n
openssl genrsa -out ryans-key.pem 1024
\n

All severs and some clients need to have a certificate. Certificates are public\nkeys signed by a Certificate Authority or self-signed. The first step to\ngetting a certificate is to create a "Certificate Signing Request" (CSR)\nfile. This is done with:\n\n

\n
openssl req -new -key ryans-key.pem -out ryans-csr.pem
\n

To create a self-signed certificate with the CSR, do this:\n\n

\n
openssl x509 -req -in ryans-csr.pem -signkey ryans-key.pem -out ryans-cert.pem
\n

Alternatively you can send the CSR to a Certificate Authority for signing.\n\n

\n

(TODO: docs on creating a CA, for now interested users should just look at\ntest/fixtures/keys/Makefile in the Node source code)\n\n

\n

To create .pfx or .p12, do this:\n\n

\n
openssl pkcs12 -export -in agent5-cert.pem -inkey agent5-key.pem \\\n    -certfile ca-cert.pem -out agent5.pfx
\n
    \n
  • in: certificate
    • \n
  • inkey: private key
    • \n
  • certfile: all CA certs concatenated in one file like\ncat ca1-cert.pem ca2-cert.pem > ca-cert.pem
    • \n
\n", - "miscs": [ - { - "textRaw": "Client-initiated renegotiation attack mitigation", - "name": "Client-initiated renegotiation attack mitigation", - "type": "misc", - "desc": "

The TLS protocol lets the client renegotiate certain aspects of the TLS session.\nUnfortunately, session renegotiation requires a disproportional amount of\nserver-side resources, which makes it a potential vector for denial-of-service\nattacks.\n\n

\n

To mitigate this, renegotiations are limited to three times every 10 minutes. An\nerror is emitted on the CleartextStream instance when\nthe threshold is exceeded. The limits are configurable:\n\n

\n
    \n

  • tls.CLIENT_RENEG_LIMIT: renegotiation limit, default is 3.

    \n
    • \n

  • tls.CLIENT_RENEG_WINDOW: renegotiation window in seconds, default is

    \n
                           10 minutes.
    \n
    • \n
\n

Don't change the defaults unless you know what you are doing.\n\n

\n

To test your server, connect to it with openssl s_client -connect address:port\nand tap R<CR> (that's the letter R followed by a carriage return) a few\ntimes.\n\n\n

\n" - }, - { - "textRaw": "NPN and SNI", - "name": "NPN and SNI", - "type": "misc", - "desc": "

NPN (Next Protocol Negotiation) and SNI (Server Name Indication) are TLS\nhandshake extensions allowing you:\n\n

\n
    \n
  • NPN - to use one TLS server for multiple protocols (HTTP, SPDY)
    • \n
  • SNI - to use one TLS server for multiple hostnames with different SSL\ncertificates.
    • \n
\n" - } - ], - "methods": [ - { - "textRaw": "tls.createServer(options, [secureConnectionListener])", - "type": "method", - "name": "createServer", - "desc": "

Creates a new tls.Server.\nThe connectionListener argument is automatically set as a listener for the\nsecureConnection event.\nThe options object has these possibilities:\n\n

\n
    \n

  • pfx: A string or Buffer containing the private key, certificate and\nCA certs of the server in PFX or PKCS12 format. (Mutually exclusive with\nthe key, cert and ca options.)

    \n
    • \n

  • key: A string or Buffer containing the private key of the server in\nPEM format. (Required)

    \n
    • \n

  • passphrase: A string of passphrase for the private key or pfx.

    \n
    • \n

  • cert: A string or Buffer containing the certificate key of the server in\nPEM format. (Required)

    \n
    • \n

  • ca: An array of strings or Buffers of trusted certificates. If this is\nomitted several well known "root" CAs will be used, like VeriSign.\nThese are used to authorize connections.

    \n
    • \n

  • ciphers: A string describing the ciphers to use or exclude. Consult\nhttp://www.openssl.org/docs/apps/ciphers.html#CIPHER_LIST_FORMAT for\ndetails on the format.

    \n
    • \n

  • requestCert: If true the server will request a certificate from\nclients that connect and attempt to verify that certificate. Default:\nfalse.

    \n
    • \n

  • rejectUnauthorized: If true the server will reject any connection\nwhich is not authorized with the list of supplied CAs. This option only\nhas an effect if requestCert is true. Default: false.

    \n
    • \n

  • NPNProtocols: An array or Buffer of possible NPN protocols. (Protocols\nshould be ordered by their priority).

    \n
    • \n

  • SNICallback: A function that will be called if client supports SNI TLS\nextension. Only one argument will be passed to it: servername. And\nSNICallback should return SecureContext instance.\n(You can use crypto.createCredentials(...).context to get proper\nSecureContext). If SNICallback wasn't provided - default callback with\nhigh-level API will be used (see below).

    \n
    • \n

  • sessionIdContext: A string containing a opaque identifier for session\nresumption. If requestCert is true, the default is MD5 hash value\ngenerated from command-line. Otherwise, the default is not provided.

    \n
    • \n
\n

Here is a simple example echo server:\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  key: fs.readFileSync('server-key.pem'),\n  cert: fs.readFileSync('server-cert.pem'),\n\n  // This is necessary only if using the client certificate authentication.\n  requestCert: true,\n\n  // This is necessary only if the client uses the self-signed certificate.\n  ca: [ fs.readFileSync('client-cert.pem') ]\n};\n\nvar server = tls.createServer(options, function(cleartextStream) {\n  console.log('server connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  cleartextStream.write("welcome!\\n");\n  cleartextStream.setEncoding('utf8');\n  cleartextStream.pipe(cleartextStream);\n});\nserver.listen(8000, function() {\n  console.log('server bound');\n});
\n

Or\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('server.pfx'),\n\n  // This is necessary only if using the client certificate authentication.\n  requestCert: true,\n\n};\n\nvar server = tls.createServer(options, function(cleartextStream) {\n  console.log('server connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  cleartextStream.write("welcome!\\n");\n  cleartextStream.setEncoding('utf8');\n  cleartextStream.pipe(cleartextStream);\n});\nserver.listen(8000, function() {\n  console.log('server bound');\n});
\n

You can test this server by connecting to it with openssl s_client:\n\n\n

\n
openssl s_client -connect 127.0.0.1:8000
\n", - "signatures": [ - { - "params": [ - { - "name": "options" - }, - { - "name": "secureConnectionListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "tls.connect(port, [host], [options], [secureConnectListener])", - "type": "method", - "name": "connect", - "desc": "

Creates a new client connection to the given port and host. (If host\ndefaults to localhost.) options should be an object which specifies\n\n

\n
    \n

  • pfx: A string or Buffer containing the private key, certificate and\nCA certs of the server in PFX or PKCS12 format.

    \n
    • \n

  • key: A string or Buffer containing the private key of the client in\nPEM format.

    \n
    • \n

  • passphrase: A string of passphrase for the private key or pfx.

    \n
    • \n

  • cert: A string or Buffer containing the certificate key of the client in\nPEM format.

    \n
    • \n

  • ca: An array of strings or Buffers of trusted certificates. If this is\nomitted several well known "root" CAs will be used, like VeriSign.\nThese are used to authorize connections.

    \n
    • \n

  • NPNProtocols: An array of string or Buffer containing supported NPN\nprotocols. Buffer should have following format: 0x05hello0x05world,\nwhere first byte is next protocol name's length. (Passing array should\nusually be much simpler: ['hello', 'world'].)

    \n
    • \n

  • servername: Servername for SNI (Server Name Indication) TLS extension.

    \n
    • \n

  • socket: Establish secure connection on a given socket rather than\ncreating a new socket. If this option is specified, host and port\nare ignored. This is intended FOR INTERNAL USE ONLY. As with all\nundocumented APIs in Node, they should not be used.

    \n
    • \n
\n

The secureConnectListener parameter will be added as a listener for the\n'secureConnect' event.\n\n

\n

tls.connect() returns a CleartextStream object.\n\n

\n

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

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  // These are necessary only if using the client certificate authentication\n  key: fs.readFileSync('client-key.pem'),\n  cert: fs.readFileSync('client-cert.pem'),\n\n  // This is necessary only if the server uses the self-signed certificate\n  ca: [ fs.readFileSync('server-cert.pem') ]\n};\n\nvar cleartextStream = tls.connect(8000, options, function() {\n  console.log('client connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  process.stdin.pipe(cleartextStream);\n  process.stdin.resume();\n});\ncleartextStream.setEncoding('utf8');\ncleartextStream.on('data', function(data) {\n  console.log(data);\n});\ncleartextStream.on('end', function() {\n  server.close();\n});
\n

Or\n\n

\n
var tls = require('tls');\nvar fs = require('fs');\n\nvar options = {\n  pfx: fs.readFileSync('client.pfx')\n};\n\nvar cleartextStream = tls.connect(8000, options, function() {\n  console.log('client connected',\n              cleartextStream.authorized ? 'authorized' : 'unauthorized');\n  process.stdin.pipe(cleartextStream);\n  process.stdin.resume();\n});\ncleartextStream.setEncoding('utf8');\ncleartextStream.on('data', function(data) {\n  console.log(data);\n});\ncleartextStream.on('end', function() {\n  server.close();\n});
\n", - "signatures": [ - { - "params": [ - { - "name": "port" - }, - { - "name": "host", - "optional": true - }, - { - "name": "options", - "optional": true - }, - { - "name": "secureConnectListener", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "tls.createSecurePair([credentials], [isServer], [requestCert], [rejectUnauthorized])", - "type": "method", - "name": "createSecurePair", - "desc": "

Creates a new secure pair object with two streams, one of which reads/writes\nencrypted data, and one reads/writes cleartext data.\nGenerally the encrypted one is piped to/from an incoming encrypted data stream,\nand the cleartext one is used as a replacement for the initial encrypted stream.\n\n

\n
    \n

  • credentials: A credentials object from crypto.createCredentials( ... )

    \n
    • \n

  • isServer: A boolean indicating whether this tls connection should be\nopened as a server or a client.

    \n
    • \n

  • requestCert: A boolean indicating whether a server should request a\ncertificate from a connecting client. Only applies to server connections.

    \n
    • \n

  • rejectUnauthorized: A boolean indicating whether a server should\nautomatically reject clients with invalid certificates. Only applies to\nservers with requestCert enabled.

    \n
    • \n
\n

tls.createSecurePair() returns a SecurePair object with\ncleartext and encrypted stream properties.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "credentials", - "optional": true - }, - { - "name": "isServer", - "optional": true - }, - { - "name": "requestCert", - "optional": true - }, - { - "name": "rejectUnauthorized", - "optional": true - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: SecurePair", - "type": "class", - "name": "SecurePair", - "desc": "

Returned by tls.createSecurePair.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'secure'", - "type": "event", - "name": "secure", - "desc": "

The event is emitted from the SecurePair once the pair has successfully\nestablished a secure connection.\n\n

\n

Similarly to the checking for the server 'secureConnection' event,\npair.cleartext.authorized should be checked to confirm whether the certificate\nused properly authorized.\n\n

\n", - "params": [] - } - ] - }, - { - "textRaw": "Class: tls.Server", - "type": "class", - "name": "tls.Server", - "desc": "

This class is a subclass of net.Server and has the same methods on it.\nInstead of accepting just raw TCP connections, this accepts encrypted\nconnections using TLS or SSL.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'secureConnection'", - "type": "event", - "name": "secureConnection", - "desc": "

function (cleartextStream) {}\n\n

\n

This event is emitted after a new connection has been successfully\nhandshaked. The argument is a instance of\nCleartextStream. It has all the common stream methods\nand events.\n\n

\n

cleartextStream.authorized is a boolean value which indicates if the\nclient has verified by one of the supplied certificate authorities for the\nserver. If cleartextStream.authorized is false, then\ncleartextStream.authorizationError is set to describe how authorization\nfailed. Implied but worth mentioning: depending on the settings of the TLS\nserver, you unauthorized connections may be accepted.\ncleartextStream.npnProtocol is a string containing selected NPN protocol.\ncleartextStream.servername is a string containing servername requested with\nSNI.\n\n\n

\n", - "params": [] - }, - { - "textRaw": "Event: 'clientError'", - "type": "event", - "name": "clientError", - "desc": "

function (exception) { }\n\n

\n

When a client connection emits an 'error' event before secure connection is\nestablished - it will be forwarded here.\n\n\n

\n", - "params": [] - } - ], - "methods": [ - { - "textRaw": "server.listen(port, [host], [callback])", - "type": "method", - "name": "listen", - "desc": "

Begin accepting connections on the specified port and host. If the\nhost is omitted, the server will accept connections directed to any\nIPv4 address (INADDR_ANY).\n\n

\n

This function is asynchronous. The last parameter callback will be called\nwhen the server has been bound.\n\n

\n

See net.Server for more information.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "port" - }, - { - "name": "host", - "optional": true - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "server.close()", - "type": "method", - "name": "close", - "desc": "

Stops the server from accepting new connections. This function is\nasynchronous, the server is finally closed when the server emits a 'close'\nevent.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "server.address()", - "type": "method", - "name": "address", - "desc": "

Returns the bound address and port of the server as reported by the operating\nsystem.\nSee net.Server.address() for more information.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "server.addContext(hostname, credentials)", - "type": "method", - "name": "addContext", - "desc": "

Add secure context that will be used if client request's SNI hostname is\nmatching passed hostname (wildcards can be used). credentials can contain\nkey, cert and ca.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "hostname" - }, - { - "name": "credentials" - } - ] - } - ] - } - ], - "properties": [ - { - "textRaw": "server.maxConnections", - "name": "maxConnections", - "desc": "

Set this property to reject connections when the server's connection count\ngets high.\n\n

\n" - }, - { - "textRaw": "server.connections", - "name": "connections", - "desc": "

The number of concurrent connections on the server.\n\n\n

\n" - } - ] - }, - { - "textRaw": "Class: tls.CleartextStream", - "type": "class", - "name": "tls.CleartextStream", - "desc": "

This is a stream on top of the Encrypted stream that makes it possible to\nread/write an encrypted data as a cleartext data.\n\n

\n

This instance implements a duplex Stream interfaces.\nIt has all the common stream methods and events.\n\n

\n

A ClearTextStream is the clear member of a SecurePair object.\n\n

\n", - "events": [ - { - "textRaw": "Event: 'secureConnect'", - "type": "event", - "name": "secureConnect", - "desc": "

This event is emitted after a new connection has been successfully handshaked. \nThe listener will be called no matter if the server's certificate was\nauthorized or not. It is up to the user to test cleartextStream.authorized\nto see if the server certificate was signed by one of the specified CAs.\nIf cleartextStream.authorized === false then the error can be found in\ncleartextStream.authorizationError. Also if NPN was used - you can check\ncleartextStream.npnProtocol for negotiated protocol.\n\n

\n", - "params": [] - } - ], - "properties": [ - { - "textRaw": "cleartextStream.authorized", - "name": "authorized", - "desc": "

A boolean that is true if the peer certificate was signed by one of the\nspecified CAs, otherwise false\n\n

\n" - }, - { - "textRaw": "cleartextStream.authorizationError", - "name": "authorizationError", - "desc": "

The reason why the peer's certificate has not been verified. This property\nbecomes available only when cleartextStream.authorized === false.\n\n

\n" - }, - { - "textRaw": "cleartextStream.remoteAddress", - "name": "remoteAddress", - "desc": "

The string representation of the remote IP address. For example,\n'74.125.127.100' or '2001:4860:a005::68'.\n\n

\n" - }, - { - "textRaw": "cleartextStream.remotePort", - "name": "remotePort", - "desc": "

The numeric representation of the remote port. For example, 443.\n

\n" - } - ], - "methods": [ - { - "textRaw": "cleartextStream.getPeerCertificate()", - "type": "method", - "name": "getPeerCertificate", - "desc": "

Returns an object representing the peer's certificate. The returned object has\nsome properties corresponding to the field of the certificate.\n\n

\n

Example:\n\n

\n
{ subject: \n   { C: 'UK',\n     ST: 'Acknack Ltd',\n     L: 'Rhys Jones',\n     O: 'node.js',\n     OU: 'Test TLS Certificate',\n     CN: 'localhost' },\n  issuer: \n   { C: 'UK',\n     ST: 'Acknack Ltd',\n     L: 'Rhys Jones',\n     O: 'node.js',\n     OU: 'Test TLS Certificate',\n     CN: 'localhost' },\n  valid_from: 'Nov 11 09:52:22 2009 GMT',\n  valid_to: 'Nov  6 09:52:22 2029 GMT',\n  fingerprint: '2A:7A:C2:DD:E5:F9:CC:53:72:35:99:7A:02:5A:71:38:52:EC:8A:DF' }
\n

If the peer does not provide a certificate, it returns null or an empty\nobject.\n\n

\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "cleartextStream.address()", - "type": "method", - "name": "address", - "desc": "

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

\n", - "signatures": [ - { - "params": [] - } - ] - } - ] - } - ], - "type": "module", - "displayName": "TLS (SSL)" - } - ] -} --- a/doc/api/api/tty.html +++ /dev/null @@ -1,121 +0,0 @@ - - - - - TTY Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- -
-

Table of Contents

- - -
- -
-

TTY#

-
Stability: 3 - Stable
-

Use require('tty') to access this module. - -

-

Example: - -

-
var tty = require('tty');
-process.stdin.resume();
-tty.setRawMode(true);
-process.stdin.on('keypress', function(char, key) {
-  if (key && key.ctrl && key.name == 'c') {
-    console.log('graceful exit');
-    process.exit()
-  }
-});
-

tty.isatty(fd)#

-

Returns true or false depending on if the fd is associated with a -terminal. - - -

-

tty.setRawMode(mode)#

-

mode should be true or false. This sets the properties of the current -process's stdin fd to act either as a raw device or default. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/tty.json +++ /dev/null @@ -1,46 +0,0 @@ -{ - "source": "doc/api/tty.markdown", - "modules": [ - { - "textRaw": "TTY", - "name": "tty", - "stability": 3, - "stabilityText": "Stable", - "desc": "

Use require('tty') to access this module.\n\n

\n

Example:\n\n

\n
var tty = require('tty');\nprocess.stdin.resume();\ntty.setRawMode(true);\nprocess.stdin.on('keypress', function(char, key) {\n  if (key && key.ctrl && key.name == 'c') {\n    console.log('graceful exit');\n    process.exit()\n  }\n});
\n", - "methods": [ - { - "textRaw": "tty.isatty(fd)", - "type": "method", - "name": "isatty", - "desc": "

Returns true or false depending on if the fd is associated with a\nterminal.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "fd" - } - ] - } - ] - }, - { - "textRaw": "tty.setRawMode(mode)", - "type": "method", - "name": "setRawMode", - "desc": "

mode should be true or false. This sets the properties of the current\nprocess's stdin fd to act either as a raw device or default.\n

\n", - "signatures": [ - { - "params": [ - { - "name": "mode" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "TTY" - } - ] -} --- a/doc/api/api/url.html +++ /dev/null @@ -1,192 +0,0 @@ - - - - - URL Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

URL#

-
Stability: 3 - Stable
-

This module has utilities for URL resolution and parsing. -Call require('url') to use it. - -

-

Parsed URL objects have some or all of the following fields, depending on -whether or not they exist in the URL string. Any parts that are not in the URL -string will not be in the parsed object. Examples are shown for the URL - -

-

'http://user:pass@host.com:8080/p/a/t/h?query=string#hash' - -

-
    -

  • href: The full URL that was originally parsed. Both the protocol and host are lowercased.

    -

    Example: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

    -
    • -

  • protocol: The request protocol, lowercased.

    -

    Example: 'http:'

    -
    • -

  • host: The full lowercased host portion of the URL, including port -information.

    -

    Example: 'host.com:8080'

    -
    • -

  • auth: The authentication information portion of a URL.

    -

    Example: 'user:pass'

    -
    • -

  • hostname: Just the lowercased hostname portion of the host.

    -

    Example: 'host.com'

    -
    • -

  • port: The port number portion of the host.

    -

    Example: '8080'

    -
    • -

  • pathname: The path section of the URL, that comes after the host and -before the query, including the initial slash if present.

    -

    Example: '/p/a/t/h'

    -
    • -

  • search: The 'query string' portion of the URL, including the leading -question mark.

    -

    Example: '?query=string'

    -
    • -

  • path: Concatenation of pathname and search.

    -

    Example: '/p/a/t/h?query=string'

    -
    • -

  • query: Either the 'params' portion of the query string, or a -querystring-parsed object.

    -

    Example: 'query=string' or {'query':'string'}

    -
    • -

  • hash: The 'fragment' portion of the URL including the pound-sign.

    -

    Example: '#hash'

    -
    • -
-

The following methods are provided by the URL module: - -

-

url.parse(urlStr, [parseQueryString], [slashesDenoteHost])#

-

Take a URL string, and return an object. - -

-

Pass true as the second argument to also parse -the query string using the querystring module. -Defaults to false. - -

-

Pass true as the third argument to treat //foo/bar as -{ host: 'foo', pathname: '/bar' } rather than -{ pathname: '//foo/bar' }. Defaults to false. - -

-

url.format(urlObj)#

-

Take a parsed URL object, and return a formatted URL string. - -

-
    -
  • href will be ignored.
    • -
  • protocolis treated the same with or without the trailing : (colon).
      -
    • The protocols http, https, ftp, gopher, file will be -postfixed with :// (colon-slash-slash).
      • -
    • All other protocols mailto, xmpp, aim, sftp, foo, etc will -be postfixed with : (colon)
      • -
    -
    • -
  • auth will be used if present.
    • -
  • hostname will only be used if host is absent.
    • -
  • port will only be used if host is absent.
    • -
  • host will be used in place of auth, hostname, and port
    • -
  • pathname is treated the same with or without the leading / (slash)
    • -
  • search will be used in place of query
    • -
  • query (object; see querystring) will only be used if search is absent.
    • -
  • search is treated the same with or without the leading ? (question mark)
    • -
  • hash is treated the same with or without the leading # (pound sign, anchor)
    • -
-

url.resolve(from, to)#

-

Take a base URL, and a href URL, and resolve them as a browser would for -an anchor tag. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/url.json +++ /dev/null @@ -1,72 +0,0 @@ -{ - "source": "doc/api/url.markdown", - "modules": [ - { - "textRaw": "URL", - "name": "url", - "stability": 3, - "stabilityText": "Stable", - "desc": "

This module has utilities for URL resolution and parsing.\nCall require('url') to use it.\n\n

\n

Parsed URL objects have some or all of the following fields, depending on\nwhether or not they exist in the URL string. Any parts that are not in the URL\nstring will not be in the parsed object. Examples are shown for the URL\n\n

\n

'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'\n\n

\n
    \n

  • href: The full URL that was originally parsed. Both the protocol and host are lowercased.

    \n

    Example: 'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

    \n
    • \n

  • protocol: The request protocol, lowercased.

    \n

    Example: 'http:'

    \n
    • \n

  • host: The full lowercased host portion of the URL, including port\ninformation.

    \n

    Example: 'host.com:8080'

    \n
    • \n

  • auth: The authentication information portion of a URL.

    \n

    Example: 'user:pass'

    \n
    • \n

  • hostname: Just the lowercased hostname portion of the host.

    \n

    Example: 'host.com'

    \n
    • \n

  • port: The port number portion of the host.

    \n

    Example: '8080'

    \n
    • \n

  • pathname: The path section of the URL, that comes after the host and\nbefore the query, including the initial slash if present.

    \n

    Example: '/p/a/t/h'

    \n
    • \n

  • search: The 'query string' portion of the URL, including the leading\nquestion mark.

    \n

    Example: '?query=string'

    \n
    • \n

  • path: Concatenation of pathname and search.

    \n

    Example: '/p/a/t/h?query=string'

    \n
    • \n

  • query: Either the 'params' portion of the query string, or a\nquerystring-parsed object.

    \n

    Example: 'query=string' or {'query':'string'}

    \n
    • \n

  • hash: The 'fragment' portion of the URL including the pound-sign.

    \n

    Example: '#hash'

    \n
    • \n
\n

The following methods are provided by the URL module:\n\n

\n", - "methods": [ - { - "textRaw": "url.parse(urlStr, [parseQueryString], [slashesDenoteHost])", - "type": "method", - "name": "parse", - "desc": "

Take a URL string, and return an object.\n\n

\n

Pass true as the second argument to also parse\nthe query string using the querystring module.\nDefaults to false.\n\n

\n

Pass true as the third argument to treat //foo/bar as\n{ host: 'foo', pathname: '/bar' } rather than\n{ pathname: '//foo/bar' }. Defaults to false.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "urlStr" - }, - { - "name": "parseQueryString", - "optional": true - }, - { - "name": "slashesDenoteHost", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "url.format(urlObj)", - "type": "method", - "name": "format", - "desc": "

Take a parsed URL object, and return a formatted URL string.\n\n

\n
    \n
  • href will be ignored.
    • \n
  • protocolis treated the same with or without the trailing : (colon).
      \n
    • The protocols http, https, ftp, gopher, file will be\npostfixed with :// (colon-slash-slash).
      • \n
    • All other protocols mailto, xmpp, aim, sftp, foo, etc will\nbe postfixed with : (colon)
      • \n
    \n
    • \n
  • auth will be used if present.
    • \n
  • hostname will only be used if host is absent.
    • \n
  • port will only be used if host is absent.
    • \n
  • host will be used in place of auth, hostname, and port
    • \n
  • pathname is treated the same with or without the leading / (slash)
    • \n
  • search will be used in place of query
    • \n
  • query (object; see querystring) will only be used if search is absent.
    • \n
  • search is treated the same with or without the leading ? (question mark)
    • \n
  • hash is treated the same with or without the leading # (pound sign, anchor)
    • \n
\n", - "signatures": [ - { - "params": [ - { - "name": "urlObj" - } - ] - } - ] - }, - { - "textRaw": "url.resolve(from, to)", - "type": "method", - "name": "resolve", - "desc": "

Take a base URL, and a href URL, and resolve them as a browser would for\nan anchor tag.\n

\n", - "signatures": [ - { - "params": [ - { - "name": "from" - }, - { - "name": "to" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "URL" - } - ] -} --- a/doc/api/api/util.html +++ /dev/null @@ -1,271 +0,0 @@ - - - - - util Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

util#

-
Stability: 5 - Locked
-

These functions are in the module 'util'. Use require('util') to access -them. - - -

-

util.format()#

-

Returns a formatted string using the first argument as a printf-like format. - -

-

The first argument is a string that contains zero or more placeholders. -Each placeholder is replaced with the converted value from its corresponding -argument. Supported placeholders are: - -

-
    -
  • %s - String.
    • -
  • %d - Number (both integer and float).
    • -
  • %j - JSON.
    • -
  • %% - single percent sign ('%'). This does not consume an argument.
    • -
-

If the placeholder does not have a corresponding argument, the placeholder is -not replaced. - -

-
util.format('%s:%s', 'foo'); // 'foo:%s'
-

If there are more arguments than placeholders, the extra arguments are -converted to strings with util.inspect() and these strings are concatenated, -delimited by a space. - -

-
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
-

If the first argument is not a format string then util.format() returns -a string that is the concatenation of all its arguments separated by spaces. -Each argument is converted to a string with util.inspect(). - -

-
util.format(1, 2, 3); // '1 2 3'
-

util.debug(string)#

-

A synchronous output function. Will block the process and -output string immediately to stderr. - -

-
require('util').debug('message on stderr');
-

util.log(string)#

-

Output with timestamp on stdout. - -

-
require('util').log('Timestamped message.');
-

util.inspect(object, [showHidden], [depth], [colors])#

-

Return a string representation of object, which is useful for debugging. - -

-

If showHidden is true, then the object's non-enumerable properties will be -shown too. Defaults to false. - -

-

If depth is provided, it tells inspect how many times to recurse while -formatting the object. This is useful for inspecting large complicated objects. - -

-

The default is to only recurse twice. To make it recurse indefinitely, pass -in null for depth. - -

-

If colors is true, the output will be styled with ANSI color codes. -Defaults to false. - -

-

Example of inspecting all properties of the util object: - -

-
var util = require('util');
-
-console.log(util.inspect(util, true, null));
-

util.isArray(object)#

-

Returns true if the given "object" is an Array. false otherwise. - -

-
var util = require('util');
-
-util.isArray([])
-  // true
-util.isArray(new Array)
-  // true
-util.isArray({})
-  // false
-

util.isRegExp(object)#

-

Returns true if the given "object" is a RegExp. false otherwise. - -

-
var util = require('util');
-
-util.isRegExp(/some regexp/)
-  // true
-util.isRegExp(new RegExp('another regexp'))
-  // true
-util.isRegExp({})
-  // false
-

util.isDate(object)#

-

Returns true if the given "object" is a Date. false otherwise. - -

-
var util = require('util');
-
-util.isDate(new Date())
-  // true
-util.isDate(Date())
-  // false (without 'new' returns a String)
-util.isDate({})
-  // false
-

util.isError(object)#

-

Returns true if the given "object" is an Error. false otherwise. - -

-
var util = require('util');
-
-util.isError(new Error())
-  // true
-util.isError(new TypeError())
-  // true
-util.isError({ name: 'Error', message: 'an error occurred' })
-  // false
-

util.pump(readableStream, writableStream, [callback])#

-

Experimental - -

-

Read the data from readableStream and send it to the writableStream. -When writableStream.write(data) returns false readableStream will be -paused until the drain event occurs on the writableStream. callback gets -an error as its only argument and is called when writableStream is closed or -when an error occurs. - - -

-

util.inherits(constructor, superConstructor)#

-

Inherit the prototype methods from one -constructor -into another. The prototype of constructor will be set to a new -object created from superConstructor. - -

-

As an additional convenience, superConstructor will be accessible -through the constructor.super_ property. - -

-
var util = require("util");
-var events = require("events");
-
-function MyStream() {
-    events.EventEmitter.call(this);
-}
-
-util.inherits(MyStream, events.EventEmitter);
-
-MyStream.prototype.write = function(data) {
-    this.emit("data", data);
-}
-
-var stream = new MyStream();
-
-console.log(stream instanceof events.EventEmitter); // true
-console.log(MyStream.super_ === events.EventEmitter); // true
-
-stream.on("data", function(data) {
-    console.log('Received data: "' + data + '"');
-})
-stream.write("It works!"); // Received data: "It works!"
- -
-
-
- - - - - - - - - - --- a/doc/api/api/util.json +++ /dev/null @@ -1,184 +0,0 @@ -{ - "source": "doc/api/util.markdown", - "modules": [ - { - "textRaw": "util", - "name": "util", - "stability": 5, - "stabilityText": "Locked", - "desc": "

These functions are in the module 'util'. Use require('util') to access\nthem.\n\n\n

\n", - "methods": [ - { - "textRaw": "util.format()", - "type": "method", - "name": "format", - "desc": "

Returns a formatted string using the first argument as a printf-like format.\n\n

\n

The first argument is a string that contains zero or more placeholders.\nEach placeholder is replaced with the converted value from its corresponding\nargument. Supported placeholders are:\n\n

\n
    \n
  • %s - String.
    • \n
  • %d - Number (both integer and float).
    • \n
  • %j - JSON.
    • \n
  • %% - single percent sign ('%'). This does not consume an argument.
    • \n
\n

If the placeholder does not have a corresponding argument, the placeholder is\nnot replaced.\n\n

\n
util.format('%s:%s', 'foo'); // 'foo:%s'
\n

If there are more arguments than placeholders, the extra arguments are\nconverted to strings with util.inspect() and these strings are concatenated,\ndelimited by a space.\n\n

\n
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
\n

If the first argument is not a format string then util.format() returns\na string that is the concatenation of all its arguments separated by spaces.\nEach argument is converted to a string with util.inspect().\n\n

\n
util.format(1, 2, 3); // '1 2 3'
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "util.debug(string)", - "type": "method", - "name": "debug", - "desc": "

A synchronous output function. Will block the process and\noutput string immediately to stderr.\n\n

\n
require('util').debug('message on stderr');
\n", - "signatures": [ - { - "params": [ - { - "name": "string" - } - ] - } - ] - }, - { - "textRaw": "util.log(string)", - "type": "method", - "name": "log", - "desc": "

Output with timestamp on stdout.\n\n

\n
require('util').log('Timestamped message.');
\n", - "signatures": [ - { - "params": [ - { - "name": "string" - } - ] - } - ] - }, - { - "textRaw": "util.inspect(object, [showHidden], [depth], [colors])", - "type": "method", - "name": "inspect", - "desc": "

Return a string representation of object, which is useful for debugging.\n\n

\n

If showHidden is true, then the object's non-enumerable properties will be\nshown too. Defaults to false.\n\n

\n

If depth is provided, it tells inspect how many times to recurse while\nformatting the object. This is useful for inspecting large complicated objects.\n\n

\n

The default is to only recurse twice. To make it recurse indefinitely, pass\nin null for depth.\n\n

\n

If colors is true, the output will be styled with ANSI color codes.\nDefaults to false.\n\n

\n

Example of inspecting all properties of the util object:\n\n

\n
var util = require('util');\n\nconsole.log(util.inspect(util, true, null));
\n", - "signatures": [ - { - "params": [ - { - "name": "object" - }, - { - "name": "showHidden", - "optional": true - }, - { - "name": "depth", - "optional": true - }, - { - "name": "colors", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "util.isArray(object)", - "type": "method", - "name": "isArray", - "desc": "

Returns true if the given "object" is an Array. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isArray([])\n  // true\nutil.isArray(new Array)\n  // true\nutil.isArray({})\n  // false
\n", - "signatures": [ - { - "params": [ - { - "name": "object" - } - ] - } - ] - }, - { - "textRaw": "util.isRegExp(object)", - "type": "method", - "name": "isRegExp", - "desc": "

Returns true if the given "object" is a RegExp. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isRegExp(/some regexp/)\n  // true\nutil.isRegExp(new RegExp('another regexp'))\n  // true\nutil.isRegExp({})\n  // false
\n", - "signatures": [ - { - "params": [ - { - "name": "object" - } - ] - } - ] - }, - { - "textRaw": "util.isDate(object)", - "type": "method", - "name": "isDate", - "desc": "

Returns true if the given "object" is a Date. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isDate(new Date())\n  // true\nutil.isDate(Date())\n  // false (without 'new' returns a String)\nutil.isDate({})\n  // false
\n", - "signatures": [ - { - "params": [ - { - "name": "object" - } - ] - } - ] - }, - { - "textRaw": "util.isError(object)", - "type": "method", - "name": "isError", - "desc": "

Returns true if the given "object" is an Error. false otherwise.\n\n

\n
var util = require('util');\n\nutil.isError(new Error())\n  // true\nutil.isError(new TypeError())\n  // true\nutil.isError({ name: 'Error', message: 'an error occurred' })\n  // false
\n", - "signatures": [ - { - "params": [ - { - "name": "object" - } - ] - } - ] - }, - { - "textRaw": "util.pump(readableStream, writableStream, [callback])", - "type": "method", - "name": "pump", - "desc": "

Experimental\n\n

\n

Read the data from readableStream and send it to the writableStream.\nWhen writableStream.write(data) returns false readableStream will be\npaused until the drain event occurs on the writableStream. callback gets\nan error as its only argument and is called when writableStream is closed or\nwhen an error occurs.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "readableStream" - }, - { - "name": "writableStream" - }, - { - "name": "callback", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "util.inherits(constructor, superConstructor)", - "type": "method", - "name": "inherits", - "desc": "

Inherit the prototype methods from one\nconstructor\ninto another. The prototype of constructor will be set to a new\nobject created from superConstructor.\n\n

\n

As an additional convenience, superConstructor will be accessible\nthrough the constructor.super_ property.\n\n

\n
var util = require("util");\nvar events = require("events");\n\nfunction MyStream() {\n    events.EventEmitter.call(this);\n}\n\nutil.inherits(MyStream, events.EventEmitter);\n\nMyStream.prototype.write = function(data) {\n    this.emit("data", data);\n}\n\nvar stream = new MyStream();\n\nconsole.log(stream instanceof events.EventEmitter); // true\nconsole.log(MyStream.super_ === events.EventEmitter); // true\n\nstream.on("data", function(data) {\n    console.log('Received data: "' + data + '"');\n})\nstream.write("It works!"); // Received data: "It works!"
\n", - "signatures": [ - { - "params": [ - { - "name": "constructor" - }, - { - "name": "superConstructor" - } - ] - } - ] - } - ], - "type": "module", - "displayName": "util" - } - ] -} --- a/doc/api/api/vm.html +++ /dev/null @@ -1,291 +0,0 @@ - - - - - Executing JavaScript Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Executing JavaScript#

-
Stability: 3 - Stable
- - -

You can access this module with: - -

-
var vm = require('vm');
-

JavaScript code can be compiled and run immediately or compiled, saved, and run later. - - -

-

vm.runInThisContext(code, [filename])#

-

vm.runInThisContext() compiles code, runs it and returns the result. Running -code does not have access to local scope. filename is optional, it's used only -in stack traces. - -

-

Example of using vm.runInThisContext and eval to run the same code: - -

-
var localVar = 123,
-    usingscript, evaled,
-    vm = require('vm');
-
-usingscript = vm.runInThisContext('localVar = 1;',
-  'myfile.vm');
-console.log('localVar: ' + localVar + ', usingscript: ' +
-  usingscript);
-evaled = eval('localVar = 1;');
-console.log('localVar: ' + localVar + ', evaled: ' +
-  evaled);
-
-// localVar: 123, usingscript: 1
-// localVar: 1, evaled: 1
-

vm.runInThisContext does not have access to the local scope, so localVar is unchanged. -eval does have access to the local scope, so localVar is changed. - -

-

In case of syntax error in code, vm.runInThisContext emits the syntax error to stderr -and throws an exception. - - -

-

vm.runInNewContext(code, [sandbox], [filename])#

-

vm.runInNewContext compiles code, then runs it in sandbox and returns the -result. Running code does not have access to local scope. The object sandbox -will be used as the global object for code. -sandbox and filename are optional, filename is only used in stack traces. - -

-

Example: compile and execute code that increments a global variable and sets a new one. -These globals are contained in the sandbox. - -

-
var util = require('util'),
-    vm = require('vm'),
-    sandbox = {
-      animal: 'cat',
-      count: 2
-    };
-
-vm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');
-console.log(util.inspect(sandbox));
-
-// { animal: 'cat', count: 3, name: 'kitty' }
-

Note that running untrusted code is a tricky business requiring great care. To prevent accidental -global variable leakage, vm.runInNewContext is quite useful, but safely running untrusted code -requires a separate process. - -

-

In case of syntax error in code, vm.runInNewContext emits the syntax error to stderr -and throws an exception. - -

-

vm.runInContext(code, context, [filename])#

-

vm.runInContext compiles code, then runs it in context and returns the -result. A (V8) context comprises a global object, together with a set of -built-in objects and functions. Running code does not have access to local scope -and the global object held within context will be used as the global object -for code. -filename is optional, it's used only in stack traces. - -

-

Example: compile and execute code in a existing context. - -

-
var util = require('util'),
-    vm = require('vm'),
-    initSandbox = {
-      animal: 'cat',
-      count: 2
-    },
-    context = vm.createContext(initSandbox);
-
-vm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');
-console.log(util.inspect(context));
-
-// { animal: 'cat', count: 3, name: 'CATT' }
-

Note that createContext will perform a shallow clone of the supplied sandbox object in order to -initialise the global object of the freshly constructed context. - -

-

Note that running untrusted code is a tricky business requiring great care. To prevent accidental -global variable leakage, vm.runInContext is quite useful, but safely running untrusted code -requires a separate process. - -

-

In case of syntax error in code, vm.runInContext emits the syntax error to stderr -and throws an exception. - -

-

vm.createContext([initSandbox])#

-

vm.createContext creates a new context which is suitable for use as the 2nd argument of a subsequent -call to vm.runInContext. A (V8) context comprises a global object together with a set of -build-in objects and functions. The optional argument initSandbox will be shallow-copied -to seed the initial contents of the global object used by the context. - -

-

vm.createScript(code, [filename])#

-

createScript compiles code but does not run it. Instead, it returns a -vm.Script object representing this compiled code. This script can be run -later many times using methods below. The returned script is not bound to any -global object. It is bound before each run, just for that run. filename is -optional, it's only used in stack traces. - -

-

In case of syntax error in code, createScript prints the syntax error to stderr -and throws an exception. - - -

-

Class: Script#

-

A class for running scripts. Returned by vm.createScript. - -

-

script.runInThisContext()#

-

Similar to vm.runInThisContext but a method of a precompiled Script object. -script.runInThisContext runs the code of script and returns the result. -Running code does not have access to local scope, but does have access to the global object -(v8: in actual context). - -

-

Example of using script.runInThisContext to compile code once and run it multiple times: - -

-
var vm = require('vm');
-
-globalVar = 0;
-
-var script = vm.createScript('globalVar += 1', 'myfile.vm');
-
-for (var i = 0; i < 1000 ; i += 1) {
-  script.runInThisContext();
-}
-
-console.log(globalVar);
-
-// 1000
-

script.runInNewContext([sandbox])#

-

Similar to vm.runInNewContext a method of a precompiled Script object. -script.runInNewContext runs the code of script with sandbox as the global object and returns the result. -Running code does not have access to local scope. sandbox is optional. - -

-

Example: compile code that increments a global variable and sets one, then execute this code multiple times. -These globals are contained in the sandbox. - -

-
var util = require('util'),
-    vm = require('vm'),
-    sandbox = {
-      animal: 'cat',
-      count: 2
-    };
-
-var script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');
-
-for (var i = 0; i < 10 ; i += 1) {
-  script.runInNewContext(sandbox);
-}
-
-console.log(util.inspect(sandbox));
-
-// { animal: 'cat', count: 12, name: 'kitty' }
-

Note that running untrusted code is a tricky business requiring great care. To prevent accidental -global variable leakage, script.runInNewContext is quite useful, but safely running untrusted code -requires a separate process. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/vm.json +++ /dev/null @@ -1,152 +0,0 @@ -{ - "source": "doc/api/vm.markdown", - "modules": [ - { - "textRaw": "Executing JavaScript", - "name": "vm", - "stability": 3, - "stabilityText": "Stable", - "desc": "

You can access this module with:\n\n

\n
var vm = require('vm');
\n

JavaScript code can be compiled and run immediately or compiled, saved, and run later.\n\n\n

\n", - "methods": [ - { - "textRaw": "vm.runInThisContext(code, [filename])", - "type": "method", - "name": "runInThisContext", - "desc": "

vm.runInThisContext() compiles code, runs it and returns the result. Running\ncode does not have access to local scope. filename is optional, it's used only\nin stack traces.\n\n

\n

Example of using vm.runInThisContext and eval to run the same code:\n\n

\n
var localVar = 123,\n    usingscript, evaled,\n    vm = require('vm');\n\nusingscript = vm.runInThisContext('localVar = 1;',\n  'myfile.vm');\nconsole.log('localVar: ' + localVar + ', usingscript: ' +\n  usingscript);\nevaled = eval('localVar = 1;');\nconsole.log('localVar: ' + localVar + ', evaled: ' +\n  evaled);\n\n// localVar: 123, usingscript: 1\n// localVar: 1, evaled: 1
\n

vm.runInThisContext does not have access to the local scope, so localVar is unchanged.\neval does have access to the local scope, so localVar is changed.\n\n

\n

In case of syntax error in code, vm.runInThisContext emits the syntax error to stderr\nand throws an exception.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code" - }, - { - "name": "filename", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "vm.runInNewContext(code, [sandbox], [filename])", - "type": "method", - "name": "runInNewContext", - "desc": "

vm.runInNewContext compiles code, then runs it in sandbox and returns the\nresult. Running code does not have access to local scope. The object sandbox\nwill be used as the global object for code.\nsandbox and filename are optional, filename is only used in stack traces.\n\n

\n

Example: compile and execute code that increments a global variable and sets a new one.\nThese globals are contained in the sandbox.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    sandbox = {\n      animal: 'cat',\n      count: 2\n    };\n\nvm.runInNewContext('count += 1; name = "kitty"', sandbox, 'myfile.vm');\nconsole.log(util.inspect(sandbox));\n\n// { animal: 'cat', count: 3, name: 'kitty' }
\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, vm.runInNewContext is quite useful, but safely running untrusted code\nrequires a separate process.\n\n

\n

In case of syntax error in code, vm.runInNewContext emits the syntax error to stderr\nand throws an exception.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code" - }, - { - "name": "sandbox", - "optional": true - }, - { - "name": "filename", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "vm.runInContext(code, context, [filename])", - "type": "method", - "name": "runInContext", - "desc": "

vm.runInContext compiles code, then runs it in context and returns the\nresult. A (V8) context comprises a global object, together with a set of\nbuilt-in objects and functions. Running code does not have access to local scope\nand the global object held within context will be used as the global object\nfor code.\nfilename is optional, it's used only in stack traces.\n\n

\n

Example: compile and execute code in a existing context.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    initSandbox = {\n      animal: 'cat',\n      count: 2\n    },\n    context = vm.createContext(initSandbox);\n\nvm.runInContext('count += 1; name = "CATT"', context, 'myfile.vm');\nconsole.log(util.inspect(context));\n\n// { animal: 'cat', count: 3, name: 'CATT' }
\n

Note that createContext will perform a shallow clone of the supplied sandbox object in order to\ninitialise the global object of the freshly constructed context.\n\n

\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, vm.runInContext is quite useful, but safely running untrusted code\nrequires a separate process.\n\n

\n

In case of syntax error in code, vm.runInContext emits the syntax error to stderr\nand throws an exception.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code" - }, - { - "name": "context" - }, - { - "name": "filename", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "vm.createContext([initSandbox])", - "type": "method", - "name": "createContext", - "desc": "

vm.createContext creates a new context which is suitable for use as the 2nd argument of a subsequent\ncall to vm.runInContext. A (V8) context comprises a global object together with a set of\nbuild-in objects and functions. The optional argument initSandbox will be shallow-copied\nto seed the initial contents of the global object used by the context.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "initSandbox", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "vm.createScript(code, [filename])", - "type": "method", - "name": "createScript", - "desc": "

createScript compiles code but does not run it. Instead, it returns a\nvm.Script object representing this compiled code. This script can be run\nlater many times using methods below. The returned script is not bound to any\nglobal object. It is bound before each run, just for that run. filename is\noptional, it's only used in stack traces.\n\n

\n

In case of syntax error in code, createScript prints the syntax error to stderr\nand throws an exception.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "code" - }, - { - "name": "filename", - "optional": true - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: Script", - "type": "class", - "name": "Script", - "desc": "

A class for running scripts. Returned by vm.createScript.\n\n

\n", - "methods": [ - { - "textRaw": "script.runInThisContext()", - "type": "method", - "name": "runInThisContext", - "desc": "

Similar to vm.runInThisContext but a method of a precompiled Script object.\nscript.runInThisContext runs the code of script and returns the result.\nRunning code does not have access to local scope, but does have access to the global object\n(v8: in actual context).\n\n

\n

Example of using script.runInThisContext to compile code once and run it multiple times:\n\n

\n
var vm = require('vm');\n\nglobalVar = 0;\n\nvar script = vm.createScript('globalVar += 1', 'myfile.vm');\n\nfor (var i = 0; i < 1000 ; i += 1) {\n  script.runInThisContext();\n}\n\nconsole.log(globalVar);\n\n// 1000
\n", - "signatures": [ - { - "params": [] - } - ] - }, - { - "textRaw": "script.runInNewContext([sandbox])", - "type": "method", - "name": "runInNewContext", - "desc": "

Similar to vm.runInNewContext a method of a precompiled Script object.\nscript.runInNewContext runs the code of script with sandbox as the global object and returns the result.\nRunning code does not have access to local scope. sandbox is optional.\n\n

\n

Example: compile code that increments a global variable and sets one, then execute this code multiple times.\nThese globals are contained in the sandbox.\n\n

\n
var util = require('util'),\n    vm = require('vm'),\n    sandbox = {\n      animal: 'cat',\n      count: 2\n    };\n\nvar script = vm.createScript('count += 1; name = "kitty"', 'myfile.vm');\n\nfor (var i = 0; i < 10 ; i += 1) {\n  script.runInNewContext(sandbox);\n}\n\nconsole.log(util.inspect(sandbox));\n\n// { animal: 'cat', count: 12, name: 'kitty' }
\n

Note that running untrusted code is a tricky business requiring great care. To prevent accidental\nglobal variable leakage, script.runInNewContext is quite useful, but safely running untrusted code\nrequires a separate process.\n

\n", - "signatures": [ - { - "params": [ - { - "name": "sandbox", - "optional": true - } - ] - } - ] - } - ] - } - ], - "type": "module", - "displayName": "vm" - } - ] -} --- a/doc/api/api/zlib.html +++ /dev/null @@ -1,395 +0,0 @@ - - - - - Zlib Node.js v0.6.18 Manual & Documentation - - - - - -
- - - -
-
- - -
-
-

Node.js v0.6.18 Manual & Documentation

- -
-
- - - -
-

Zlib#

-
Stability: 3 - Stable
-

You can access this module with: - -

-
var zlib = require('zlib');
-

This provides bindings to Gzip/Gunzip, Deflate/Inflate, and -DeflateRaw/InflateRaw classes. Each class takes the same options, and -is a readable/writable Stream. - -

-

Examples#

-

Compressing or decompressing a file can be done by piping an -fs.ReadStream into a zlib stream, then into an fs.WriteStream. - -

-
var gzip = zlib.createGzip();
-var fs = require('fs');
-var inp = fs.createReadStream('input.txt');
-var out = fs.createWriteStream('input.txt.gz');
-
-inp.pipe(gzip).pipe(out);
-

Compressing or decompressing data in one step can be done by using -the convenience methods. - -

-
var input = '.................................';
-zlib.deflate(input, function(err, buffer) {
-  if (!err) {
-    console.log(buffer.toString('base64'));
-  }
-});
-
-var buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');
-zlib.unzip(buffer, function(err, buffer) {
-  if (!err) {
-    console.log(buffer.toString());
-  }
-});
-

To use this module in an HTTP client or server, use the -accept-encoding -on requests, and the -content-encoding -header on responses. - -

-

Note: these examples are drastically simplified to show -the basic concept. Zlib encoding can be expensive, and the results -ought to be cached. See Memory Usage Tuning -below for more information on the speed/memory/compression -tradeoffs involved in zlib usage. - -

-
// client request example
-var zlib = require('zlib');
-var http = require('http');
-var fs = require('fs');
-var request = http.get({ host: 'izs.me',
-                         path: '/',
-                         port: 80,
-                         headers: { 'accept-encoding': 'gzip,deflate' } });
-request.on('response', function(response) {
-  var output = fs.createWriteStream('izs.me_index.html');
-
-  switch (response.headers['content-encoding']) {
-    // or, just use zlib.createUnzip() to handle both cases
-    case 'gzip':
-      response.pipe(zlib.createGunzip()).pipe(output);
-      break;
-    case 'deflate':
-      response.pipe(zlib.createInflate()).pipe(output);
-      break;
-    default:
-      response.pipe(output);
-      break;
-  }
-});
-
-// server example
-// Running a gzip operation on every request is quite expensive.
-// It would be much more efficient to cache the compressed buffer.
-var zlib = require('zlib');
-var http = require('http');
-var fs = require('fs');
-http.createServer(function(request, response) {
-  var raw = fs.createReadStream('index.html');
-  var acceptEncoding = request.headers['accept-encoding'];
-  if (!acceptEncoding) {
-    acceptEncoding = '';
-  }
-
-  // Note: this is not a conformant accept-encoding parser.
-  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
-  if (acceptEncoding.match(/\bdeflate\b/)) {
-    response.writeHead(200, { 'content-encoding': 'deflate' });
-    raw.pipe(zlib.createDeflate()).pipe(response);
-  } else if (acceptEncoding.match(/\bgzip\b/)) {
-    response.writeHead(200, { 'content-encoding': 'gzip' });
-    raw.pipe(zlib.createGzip()).pipe(response);
-  } else {
-    response.writeHead(200, {});
-    raw.pipe(response);
-  }
-}).listen(1337);
-

Constants#

- - -

All of the constants defined in zlib.h are also defined on -require('zlib'). They are described in more detail in the zlib -documentation. See http://zlib.net/manual.html#Constants -for more details. - -

-

zlib.createGzip([options])#

-

Returns a new Gzip object with an options. - -

-

zlib.createGunzip([options])#

-

Returns a new Gunzip object with an options. - -

-

zlib.createDeflate([options])#

-

Returns a new Deflate object with an options. - -

-

zlib.createInflate([options])#

-

Returns a new Inflate object with an options. - -

-

zlib.createDeflateRaw([options])#

-

Returns a new DeflateRaw object with an options. - -

-

zlib.createInflateRaw([options])#

-

Returns a new InflateRaw object with an options. - -

-

zlib.createUnzip([options])#

-

Returns a new Unzip object with an options. - - -

-

Class: zlib.Gzip#

-

Compress data using gzip. - -

-

Class: zlib.Gunzip#

-

Decompress a gzip stream. - -

-

Class: zlib.Deflate#

-

Compress data using deflate. - -

-

Class: zlib.Inflate#

-

Decompress a deflate stream. - -

-

Class: zlib.DeflateRaw#

-

Compress data using deflate, and do not append a zlib header. - -

-

Class: zlib.InflateRaw#

-

Decompress a raw deflate stream. - -

-

Class: zlib.Unzip#

-

Decompress either a Gzip- or Deflate-compressed stream by auto-detecting -the header. - -

-

Convenience Methods#

- - -

All of these take a string or buffer as the first argument, and call the -supplied callback with callback(error, result). The -compression/decompression engine is created using the default settings -in all convenience methods. To supply different options, use the -zlib classes directly. - -

-

zlib.deflate(buf, callback)#

-

Compress a string with Deflate. - -

-

zlib.deflateRaw(buf, callback)#

-

Compress a string with DeflateRaw. - -

-

zlib.gzip(buf, callback)#

-

Compress a string with Gzip. - -

-

zlib.gunzip(buf, callback)#

-

Decompress a raw Buffer with Gunzip. - -

-

zlib.inflate(buf, callback)#

-

Decompress a raw Buffer with Inflate. - -

-

zlib.inflateRaw(buf, callback)#

-

Decompress a raw Buffer with InflateRaw. - -

-

zlib.unzip(buf, callback)#

-

Decompress a raw Buffer with Unzip. - -

-

Options#

- - -

Each class takes an options object. All options are optional. (The -convenience methods use the default settings for all options.) - -

-

Note that some options are only -relevant when compressing, and are ignored by the decompression classes. - -

-
    -
  • chunkSize (default: 16*1024)
    • -
  • windowBits
    • -
  • level (compression only)
    • -
  • memLevel (compression only)
    • -
  • strategy (compression only)
    • -
-

See the description of deflateInit2 and inflateInit2 at -

-

http://zlib.net/manual.html#Advanced for more information on these. - -

-

Memory Usage Tuning#

- - -

From zlib/zconf.h, modified to node's usage: - -

-

The memory requirements for deflate are (in bytes): - -

-
(1 << (windowBits+2)) +  (1 << (memLevel+9))
-

that is: 128K for windowBits=15 + 128K for memLevel = 8 -(default values) plus a few kilobytes for small objects. - -

-

For example, if you want to reduce -the default memory requirements from 256K to 128K, set the options to: - -

-
{ windowBits: 14, memLevel: 7 }
-

Of course this will generally degrade compression (there's no free lunch). - -

-

The memory requirements for inflate are (in bytes) - -

-
1 << windowBits
-

that is, 32K for windowBits=15 (default value) plus a few kilobytes -for small objects. - -

-

This is in addition to a single internal output slab buffer of size -chunkSize, which defaults to 16K. - -

-

The speed of zlib compression is affected most dramatically by the -level setting. A higher level will result in better compression, but -will take longer to complete. A lower level will result in less -compression, but will be much faster. - -

-

In general, greater memory usage options will mean that node has to make -fewer calls to zlib, since it'll be able to process more data in a -single write operation. So, this is another factor that affects the -speed, at the cost of memory usage. -

- -
-
-
- - - - - - - - - - --- a/doc/api/api/zlib.json +++ /dev/null @@ -1,324 +0,0 @@ -{ - "source": "doc/api/zlib.markdown", - "modules": [ - { - "textRaw": "Zlib", - "name": "zlib", - "stability": 3, - "stabilityText": "Stable", - "desc": "

You can access this module with:\n\n

\n
var zlib = require('zlib');
\n

This provides bindings to Gzip/Gunzip, Deflate/Inflate, and\nDeflateRaw/InflateRaw classes. Each class takes the same options, and\nis a readable/writable Stream.\n\n

\n

Examples

\n

Compressing or decompressing a file can be done by piping an\nfs.ReadStream into a zlib stream, then into an fs.WriteStream.\n\n

\n
var gzip = zlib.createGzip();\nvar fs = require('fs');\nvar inp = fs.createReadStream('input.txt');\nvar out = fs.createWriteStream('input.txt.gz');\n\ninp.pipe(gzip).pipe(out);
\n

Compressing or decompressing data in one step can be done by using\nthe convenience methods.\n\n

\n
var input = '.................................';\nzlib.deflate(input, function(err, buffer) {\n  if (!err) {\n    console.log(buffer.toString('base64'));\n  }\n});\n\nvar buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');\nzlib.unzip(buffer, function(err, buffer) {\n  if (!err) {\n    console.log(buffer.toString());\n  }\n});
\n

To use this module in an HTTP client or server, use the\naccept-encoding\non requests, and the\ncontent-encoding\nheader on responses.\n\n

\n

Note: these examples are drastically simplified to show\nthe basic concept. Zlib encoding can be expensive, and the results\nought to be cached. See Memory Usage Tuning\nbelow for more information on the speed/memory/compression\ntradeoffs involved in zlib usage.\n\n

\n
// client request example\nvar zlib = require('zlib');\nvar http = require('http');\nvar fs = require('fs');\nvar request = http.get({ host: 'izs.me',\n                         path: '/',\n                         port: 80,\n                         headers: { 'accept-encoding': 'gzip,deflate' } });\nrequest.on('response', function(response) {\n  var output = fs.createWriteStream('izs.me_index.html');\n\n  switch (response.headers['content-encoding']) {\n    // or, just use zlib.createUnzip() to handle both cases\n    case 'gzip':\n      response.pipe(zlib.createGunzip()).pipe(output);\n      break;\n    case 'deflate':\n      response.pipe(zlib.createInflate()).pipe(output);\n      break;\n    default:\n      response.pipe(output);\n      break;\n  }\n});\n\n// server example\n// Running a gzip operation on every request is quite expensive.\n// It would be much more efficient to cache the compressed buffer.\nvar zlib = require('zlib');\nvar http = require('http');\nvar fs = require('fs');\nhttp.createServer(function(request, response) {\n  var raw = fs.createReadStream('index.html');\n  var acceptEncoding = request.headers['accept-encoding'];\n  if (!acceptEncoding) {\n    acceptEncoding = '';\n  }\n\n  // Note: this is not a conformant accept-encoding parser.\n  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3\n  if (acceptEncoding.match(/\\bdeflate\\b/)) {\n    response.writeHead(200, { 'content-encoding': 'deflate' });\n    raw.pipe(zlib.createDeflate()).pipe(response);\n  } else if (acceptEncoding.match(/\\bgzip\\b/)) {\n    response.writeHead(200, { 'content-encoding': 'gzip' });\n    raw.pipe(zlib.createGzip()).pipe(response);\n  } else {\n    response.writeHead(200, {});\n    raw.pipe(response);\n  }\n}).listen(1337);
\n", - "miscs": [ - { - "textRaw": "Constants", - "name": "Constants", - "type": "misc", - "desc": "

All of the constants defined in zlib.h are also defined on\nrequire('zlib'). They are described in more detail in the zlib\ndocumentation. See http://zlib.net/manual.html#Constants\nfor more details.\n\n

\n" - }, - { - "textRaw": "Convenience Methods", - "name": "Convenience Methods", - "type": "misc", - "desc": "

All of these take a string or buffer as the first argument, and call the\nsupplied callback with callback(error, result). The\ncompression/decompression engine is created using the default settings\nin all convenience methods. To supply different options, use the\nzlib classes directly.\n\n

\n" - }, - { - "textRaw": "Options", - "name": "Options", - "type": "misc", - "desc": "

Each class takes an options object. All options are optional. (The\nconvenience methods use the default settings for all options.)\n\n

\n

Note that some options are only\nrelevant when compressing, and are ignored by the decompression classes.\n\n

\n
    \n
  • chunkSize (default: 16*1024)
    • \n
  • windowBits
    • \n
  • level (compression only)
    • \n
  • memLevel (compression only)
    • \n
  • strategy (compression only)
    • \n
\n

See the description of deflateInit2 and inflateInit2 at\n

\n

http://zlib.net/manual.html#Advanced for more information on these.\n\n

\n" - }, - { - "textRaw": "Memory Usage Tuning", - "name": "Memory Usage Tuning", - "type": "misc", - "desc": "

From zlib/zconf.h, modified to node's usage:\n\n

\n

The memory requirements for deflate are (in bytes):\n\n

\n
(1 << (windowBits+2)) +  (1 << (memLevel+9))
\n

that is: 128K for windowBits=15 + 128K for memLevel = 8\n(default values) plus a few kilobytes for small objects.\n\n

\n

For example, if you want to reduce\nthe default memory requirements from 256K to 128K, set the options to:\n\n

\n
{ windowBits: 14, memLevel: 7 }
\n

Of course this will generally degrade compression (there's no free lunch).\n\n

\n

The memory requirements for inflate are (in bytes)\n\n

\n
1 << windowBits
\n

that is, 32K for windowBits=15 (default value) plus a few kilobytes\nfor small objects.\n\n

\n

This is in addition to a single internal output slab buffer of size\nchunkSize, which defaults to 16K.\n\n

\n

The speed of zlib compression is affected most dramatically by the\nlevel setting. A higher level will result in better compression, but\nwill take longer to complete. A lower level will result in less\ncompression, but will be much faster.\n\n

\n

In general, greater memory usage options will mean that node has to make\nfewer calls to zlib, since it'll be able to process more data in a\nsingle write operation. So, this is another factor that affects the\nspeed, at the cost of memory usage.\n

\n" - } - ], - "methods": [ - { - "textRaw": "zlib.createGzip([options])", - "type": "method", - "name": "createGzip", - "desc": "

Returns a new Gzip object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createGunzip([options])", - "type": "method", - "name": "createGunzip", - "desc": "

Returns a new Gunzip object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createDeflate([options])", - "type": "method", - "name": "createDeflate", - "desc": "

Returns a new Deflate object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createInflate([options])", - "type": "method", - "name": "createInflate", - "desc": "

Returns a new Inflate object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createDeflateRaw([options])", - "type": "method", - "name": "createDeflateRaw", - "desc": "

Returns a new DeflateRaw object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createInflateRaw([options])", - "type": "method", - "name": "createInflateRaw", - "desc": "

Returns a new InflateRaw object with an options.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.createUnzip([options])", - "type": "method", - "name": "createUnzip", - "desc": "

Returns a new Unzip object with an options.\n\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "options", - "optional": true - } - ] - } - ] - }, - { - "textRaw": "zlib.deflate(buf, callback)", - "type": "method", - "name": "deflate", - "desc": "

Compress a string with Deflate.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.deflateRaw(buf, callback)", - "type": "method", - "name": "deflateRaw", - "desc": "

Compress a string with DeflateRaw.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.gzip(buf, callback)", - "type": "method", - "name": "gzip", - "desc": "

Compress a string with Gzip.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.gunzip(buf, callback)", - "type": "method", - "name": "gunzip", - "desc": "

Decompress a raw Buffer with Gunzip.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.inflate(buf, callback)", - "type": "method", - "name": "inflate", - "desc": "

Decompress a raw Buffer with Inflate.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.inflateRaw(buf, callback)", - "type": "method", - "name": "inflateRaw", - "desc": "

Decompress a raw Buffer with InflateRaw.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - }, - { - "textRaw": "zlib.unzip(buf, callback)", - "type": "method", - "name": "unzip", - "desc": "

Decompress a raw Buffer with Unzip.\n\n

\n", - "signatures": [ - { - "params": [ - { - "name": "buf" - }, - { - "name": "callback" - } - ] - } - ] - } - ], - "classes": [ - { - "textRaw": "Class: zlib.Gzip", - "type": "class", - "name": "zlib.Gzip", - "desc": "

Compress data using gzip.\n\n

\n" - }, - { - "textRaw": "Class: zlib.Gunzip", - "type": "class", - "name": "zlib.Gunzip", - "desc": "

Decompress a gzip stream.\n\n

\n" - }, - { - "textRaw": "Class: zlib.Deflate", - "type": "class", - "name": "zlib.Deflate", - "desc": "

Compress data using deflate.\n\n

\n" - }, - { - "textRaw": "Class: zlib.Inflate", - "type": "class", - "name": "zlib.Inflate", - "desc": "

Decompress a deflate stream.\n\n

\n" - }, - { - "textRaw": "Class: zlib.DeflateRaw", - "type": "class", - "name": "zlib.DeflateRaw", - "desc": "

Compress data using deflate, and do not append a zlib header.\n\n

\n" - }, - { - "textRaw": "Class: zlib.InflateRaw", - "type": "class", - "name": "zlib.InflateRaw", - "desc": "

Decompress a raw deflate stream.\n\n

\n" - }, - { - "textRaw": "Class: zlib.Unzip", - "type": "class", - "name": "zlib.Unzip", - "desc": "

Decompress either a Gzip- or Deflate-compressed stream by auto-detecting\nthe header.\n\n

\n" - } - ], - "type": "module", - "displayName": "Zlib" - } - ] -} --- a/doc/api/api/assets/sh.css +++ /dev/null @@ -1,23 +0,0 @@ -.sh_sourceCode { - font-weight: normal; - font-style: normal; -} - -.sh_sourceCode .sh_symbol , .sh_sourceCode .sh_cbracket { - color: #333; -} - -.sh_sourceCode .sh_keyword { - color: #c96; -} - -.sh_sourceCode .sh_string, .sh_sourceCode .sh_regexp, .sh_sourceCode .sh_number, -.sh_sourceCode .sh_specialchar -{ - color: #690; -} - -.sh_sourceCode .sh_comment { - color: #666; -} - --- a/doc/api/api/assets/style.css +++ /dev/null @@ -1,493 +0,0 @@ -/*--------------------- Layout and Typography ----------------------------*/ -html { - -webkit-font-smoothing: antialiased; -} - -body { - font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif; - font-size: 14px; - line-height: 180%; - color: black; - margin: 0; padding: 49px 0 0 0; - border-top: 6px #8CC84B solid; -} -a { - color: #480; - text-decoration: underline; -} - a:visited { - color: #46483e; - text-decoration: underline; - } - a:hover, a:focus { - text-decoration: none; - } - - code a:hover { - background: none; - color: #b950b7; - } - -#changelog #gtoc { - display: none; -} - -#gtoc p { - margin:0; - font-size:18px; - line-height: 30px; -} - -#gtoc a { - font-family: Georgia, FreeSerif, Times, serif; - text-decoration: none; - color: #46483e; -} - -#gtoc a:hover { - color: #669900; - text-decoration: underline; -} - -.notice { - display: block; - padding: 1em; - margin: 1.4667em 0 2.9334em; - background:#FFF6BF; - color:#514721; - border:1px solid #FFD324; -} - .notice p { - margin: 0; - } - -ul.plain { - list-style: none; -} - -abbr { - border-bottom: 1px dotted #454545; -} - -p { - margin: 0 0 1.4667em 0; - position: relative; - text-rendering: optimizeLegibility; -} - -.apidoc #apicontent p, .apidoc #apicontent li { - font-size: 15px; - line-height: 22px; - color: #000; - font-family: Georgia, FreeSerif, Times, serif; -} - -ol, ul, dl { - margin: 0 0 1em 0; - padding: 0; -} - -ol ul, ol ol, ol dl, -ul ul, ul ol, ul dl, -dl ul, dl ol, dl dl { - margin-bottom: 0; -} - -ol p:first-child, ul p:first-child, dl p:first-child { - margin-bottom: 0; -} - -ul, ol { - margin-left: 2em; -} - - -dl dt { - position: relative; - margin: 1.5em 0 0; -} - -dl dd { - position: relative; - margin: 0 1em 0; -} - -dd + dt.pre { - margin-top: 1.6em; -} - -h1, h2, h3, h4, h5, h6 { - font-family: Helvetica, Arial, sans-serif; - color: #000; - text-rendering: optimizeLegibility; - position: relative; -} - -header h1 { - font-family: Georgia, FreeSerif, Times, serif; - font-size: 30px; - font-weight: normal; - line-height: 36px; - color: #480; - margin: 15px 0 11px; -} - -h1 { - font-size: 29px; - line-height: 33px; - margin: 2em 0 15px; -} - -#toc + h1 { - margin-top:1em; - padding-top:0; -} - -h2 { - font-size: 1.4em; - line-height: 1.0909em; - margin: 1.5em 0 0.5em; -} - -h2 + h2 { - margin: 0 0 0.5em; -} - -h3 { - font-size: 1.3em; - line-height: 1.1282em; - margin: 2.2em 0 0.5em; -} - -h3 + h3 { - margin: 0 0 0.5em; -} - - h2, h3, h4 { - position:relative; - padding-right:40px; - } - h1 span, h2 span, h3 span, h4 span { - font-size:25px; - position:absolute; - display:block; - top:0; - right:0; - opacity: 0.3; - } - h1 span:hover, h2 span:hover, h3 span:hover, h4 span:hover { - opacity: 1; - } - h1 span a, h2 span a, h3 span a, h4 span a { - font-size: 0.8em; - color: #000; - text-decoration: none; - font-family: Helvetica, Arial, sans-serif; - font-weight:bold; - } - - h1 span a.top, h3 span a.top, h3 span a.top, h4 span a.top { - /* XXX Get an image and clean up these two links - * so that they look nice next to one another. - * http://www.chrisglass.com/work/nodejs/website/v05/docs.html - * -isaacs - */ - display:none; - } - -h5 { - font-size: 1.125em; - line-height: 1.4em; -} - -h6 { - font-size: 1em; - line-height: 1.4667em; -} - - pre, tt, code { - font-size: 14px; - line-height: 1.5438em; - font-family: Monaco, Consolas, "Lucida Console", monospace; - margin: 0; padding: 0; - } - - .pre { - font-family: Monaco, Consolas, "Lucida Console", monospace; - line-height: 1.5438em; - font-size: 0.95em; - } - - pre { - padding: 1em 1.6em 1em 1.2em; - vertical-align: top; - background: #f8f8f8; - border: 1px solid #e8e8e8; - border-width: 1px 1px 1px 6px; - margin: -0.5em 0 1.1em; - overflow-x:auto; - } - - pre + h3 { - margin-top: 2.225em; - } - -code.pre { - white-space: pre; -} - -#intro { - width: 775px; - margin: 0 auto; - text-align: center; - color: #d2d8ba; - - /* preload platform-icons.png */ - background-image: url(http://nodejs.org/images/platform-icons.png); - background-repeat: no-repeat; - background-position: -999em -999em; -} - -#intro.interior #logo { - margin-left: -298px; - border:0; -} - -hr { - background: none; - border: medium none; - border-bottom: 1px solid #ccc; - margin: 1em 0; -} - -#toc { - font-size:15px; - line-height:1.5em; - line-height: 22px; - padding-top:4px; -} - - #toc h2 { - font-size: 15px; - line-height: 21px; - margin: 0 0 0.5em; - } - - #toc h2 a { - float: right; - } - - #toc hr { - margin: 1em 0 2em; - } - - #toc ul, #api-section-index #apicontent ul li, #api-section-index #apicontent ul { - font-family: Georgia, FreeSerif, Times, serif; - color:#666!important; - } - - #toc ul a { - text-decoration:none; - border-bottom:1px dotted #480; - } - #toc ul a:hover, #toc ul a:focus { - border-bottom:1px dotted #fff; - color:#000; - } - - -p tt, p code { - background: #f8f8ff; - border: 1px solid #dedede; - padding: 0 0.2em; -} - -#content { - width: 953px; - margin: 0 auto; - overflow: visible; - clear: both; - display: block; -} - -#column1.interior { - width: 749px; - float: right; - padding-top: 7px; - padding-top: 11px; - font-size:18px; -} - -#column2.interior { - width: 140px; - float: left; - margin-top: -55px; - overflow: visible; -} - -#column2.interior ul { - margin-left: 0; -} - -#column2.interior li { - list-style-type: none; -} - -#column2.interior li a { - display: block; - padding: 0 0 0 35px; - color: #878b78; - text-transform: uppercase; - text-decoration: none; - font-size: 11px; - line-height: 23px; -} - -#column2.interior li a.home { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px 3px; } -#column2.interior li a.download { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -21px; } -#column2.interior li a.about { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -45px; } -#column2.interior li a.npm { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -69px; } -#column2.interior li a.docs { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -93px; } -#column2.interior li a.blog { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -117px; } -#column2.interior li a.community { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -141px; } -#column2.interior li a.logos { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -165px; } -#column2.interior li a.jobs { background: url(http://nodejs.org/images/icons-interior.png) no-repeat -156px -189px; } - -#column2.interior li a.home.current { background-position: 2px 3px; } -#column2.interior li a.download.current { background-position: 2px -21px; } -#column2.interior li a.about.current { background-position: 2px -45px; } -#column2.interior li a.npm.current { background-position: 2px -69px; } -#column2.interior li a.docs.current { background-position: 2px -93px; } -#column2.interior li a.blog.current { background-position: 2px -117px; } -#column2.interior li a.community.current { background-position: 2px -141px; } -#column2.interior li a.logos.current { background-position: 2px -165px; } -#column2.interior li a.jobs.current { background-position: 2px -189px; } -#column2.interior li a.current { color: #8cc84b; font-weight: bold; } - -#column2.interior li a.home:hover { background-position: -331px 3px; } -#column2.interior li a.download:hover { background-position: -331px -21px; } -#column2.interior li a.about:hover { background-position: -331px -45px; } -#column2.interior li a.npm:hover { background-position: -331px -69px; } -#column2.interior li a.docs:hover { background-position: -331px -93px; } -#column2.interior li a.blog:hover { background-position: -331px -117px; } -#column2.interior li a.community:hover { background-position: -331px -141px; } -#column2.interior li a.logos:hover { background-position: -331px -165px; } -#column2.interior li a.jobs:hover { background-position: -331px -189px; } -#column2.interior li a:hover { color: #000000; text-decoration: none; } - -#column2.interior li + li { - border-top: 1px solid #c1c7ac; -} -#column2.interior p.twitter { - padding-top: 20px; -} - -#column2.interior p.twitter a { - background: url(http://nodejs.org/images/twitter-bird.png) no-repeat 0 4px; - padding-left: 37px; - text-decoration: none; -} - -#column2.interior p.twitter a:hover { - text-decoration: underline; -} - -a.totop { - font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif; - font-weight: bold; - text-indent: -9999999px; - background: url(http://nodejs.org/images/anchor.png) no-repeat top left; - margin-right: 7px; - display: block; - width: 13px; - border-bottom: 1px solid #cccccc; -} - -a.anchor { - font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif; - font-weight: bold; - text-indent: -9999999px; - background: url(http://nodejs.org/images/anchor.png) no-repeat top right; - display: block; - width: 13px; - border-bottom: 1px solid #cccccc; -} -#footer { - width: 942px; - margin: 150px auto 55px auto; - padding:0; -} - -#footer p { - font-size: 11px; - line-height:1em; - padding: 0 0 0 195px; - color: #666; -} - -#footer p, #footer li { - font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif; -} - -#footer a { - text-decoration:none; - border:none; - color: #480; -} -#footer a:hover { - color:#000; -} - -#footer p a { - border-bottom:1px dotted #480; - color: #878b78; -} - -#footer ul { - background: url(http://nodejs.org/images/footer-logo-alt.png) left 17px no-repeat; - padding: 23px 0 0 195px; - height: 26px; - margin-left: -1px; - border-top: 1px solid #626557; -} - -#footer ul li { - list-style-type: none; - float: left; - font-size: 12px; - margin:0!important; - padding:0; - height: 12px; -} - -#footer ul li a { - margin: 0; - padding: 0 6px 0 0; - display: block; - height:12px; - line-height:12px; -} - -#footer ul li + li { - margin-left: 3px; -} - -#footer ul li + li a { - padding: 0 6px 0 6px; - border-left: 1px solid #878b78; -} - -#footer ul li a.twitter { - background: url(http://nodejs.org/images/twitter-bird.png) no-repeat 5px 0px; - padding-left: 25px; -} - -/* simpler clearfix */ -.clearfix:after { - content: "."; - display: block; - height: 0; - clear: both; - visibility: hidden; -} - debian/patches/2005_expected_failing_tests.patch0000644000000000000000000000271112004014454017013 0ustar Description: Expected failing tests There are three categories of failing tests: 1 - because of build server without external network access 2 - the test itself is buggy (race condition under heavy load, problem with the external command that is called) 3 - the test is legitimately failing, but no one knows why and that prevents the package from being updated. That last type was #660802 and has been fixed. Forwarded: not-needed Author: Jérémy Lal Last-Update: 2012-06-06 --- a/test/simple/simple.status +++ b/test/simple/simple.status @@ -1 +1,24 @@ prefix simple + +# only fail when some network resources are not available +test-http-dns-fail: PASS || FAIL +test-net-connect-timeout: PASS || FAIL +test-dgram-multicast-multi-process: PASS || FAIL +test-dgram-broadcast-multi-process: PASS || FAIL + +# sometimes these tests TIMEOUT or FAIL +test-dgram-pingpong: PASS || FAIL || TIMEOUT +test-stream-pipe-multi: PASS || TIMEOUT + +# http://bugs.debian.org/660802 +test-cluster-kill-workers: PASS || FAIL + +# 512 bits keys fail with openssl 1.0.1 - node tests will use 1024 bits +# keys : https://github.com/joyent/node/commit/ef046bf4 +# Meanwhile, allow this test to fail +test-tls-server-verify: PASS || FAIL + +# https://buildd.debian.org/status/fetch.php?pkg=nodejs&arch=armhf&ver=0.6.19~dfsg1-1&stamp=1339013006 +test-debugger-repl-utf8: PASS || TIMEOUT +test-debugger-repl: PASS || TIMEOUT +test-debugger-client: PASS || TIMEOUT debian/patches/2012_fix_v8_3_10.patch0000644000000000000000000000070012004014454014216 0ustar Description: Fix build with v8 3.10 Node calls V8::Dispose on exit, and that makes v8 crash. Author: Jérémy Lal Forwarded: https://github.com/joyent/node/issues/3184#issuecomment-6297038 Last-Update: 2012-06-12 --- a/src/node.cc +++ b/src/node.cc @@ -2645,7 +2645,7 @@ #ifndef NDEBUG // Clean up. context.Dispose(); - V8::Dispose(); + // V8::Dispose(); // this call crashes v8 3.10 #endif // NDEBUG return 0; debian/patches/2001_FHS_paths_for_nodejs.patch0000644000000000000000000000371112004014454016323 0ustar Description: FHS paths for nodejs Use /usr/lib/nodejs for packaged modules. Add /usr/local/lib/nodejs for user-installed modules. Use /usr/include/nodejs for headers. Forwarded: not-needed Author: Jérémy Lal Last-Update: 2011-09-11 --- a/src/node_config.h.in +++ b/src/node_config.h.in @@ -22,7 +22,7 @@ #ifndef NODE_CONFIG_H #define NODE_CONFIG_H -#define NODE_CFLAGS "@CCFLAGS@ @CPPFLAGS@ -I@PREFIX@/include/node" +#define NODE_CFLAGS "@CCFLAGS@ @CPPFLAGS@ -I@PREFIX@/include/nodejs" #define NODE_PREFIX "@PREFIX@" #endif /* NODE_CONFIG_H */ --- a/tools/wafadmin/Tools/node_addon.py +++ b/tools/wafadmin/Tools/node_addon.py @@ -28,7 +28,7 @@ lib = join(prefix, 'lib') conf.env['LIBPATH_NODE'] = lib - conf.env['CPPPATH_NODE'] = join(prefix, 'include', 'node') + conf.env['CPPPATH_NODE'] = join(prefix, 'include', 'nodejs') conf.env.append_value('CPPFLAGS_NODE', '-D_GNU_SOURCE') @@ -63,7 +63,7 @@ nodePath = None if not os.environ.has_key('NODE_PATH'): if not os.environ.has_key('HOME'): - nodePath = join(get_prefix(), 'lib', 'node') + nodePath = join(get_prefix(), 'lib', 'nodejs') else: nodePath = join(os.environ['HOME'], '.node_libraries') else: --- a/tools/node-waf +++ b/tools/node-waf @@ -3,9 +3,11 @@ join = os.path.join -bindir = os.path.dirname(os.path.realpath(__file__)) -prefix = join(bindir, "..") -wafdir = join(prefix, "lib", "node") +if os.environ.has_key('PREFIX_NODE'): + prefix = os.environ['PREFIX_NODE'] +else: + prefix = "/usr" +wafdir = join(prefix, "share", "nodejs") w = join(wafdir, 'wafadmin') t = join(w, 'Tools') --- a/lib/module.js +++ b/lib/module.js @@ -485,7 +485,7 @@ }; Module._initPaths = function() { - var paths = [path.resolve(process.execPath, '..', '..', 'lib', 'node')]; + var paths = ['/usr/lib/nodejs']; if (process.env['HOME']) { paths.unshift(path.resolve(process.env['HOME'], '.node_libraries')); debian/patches/2002_build_without_libv8_debug.patch0000644000000000000000000000111212004014454017422 0ustar Description: Build node_g without libv8 debug version libv8 package does not provide it. Forwarded: not-needed Author: Jérémy Lal Last-Update: 2010-01-01 --- a/wscript +++ b/wscript @@ -435,7 +435,7 @@ conf.fatal("Cannot find v8") if o.debug: - if not conf.check_cxx(lib=o.shared_v8_libname + '_g', header_name='v8.h', + if not conf.check_cxx(lib=o.shared_v8_libname, header_name='v8.h', uselib_store='V8_G', includes=v8_includes, libpath=v8_libpath): debian/patches/1001_align_fast_buffers_8byte_boundary.patch0000644000000000000000000000077512004014454021143 0ustar Description: align fast buffers on 8 byte boundary Fixes http://bugs.debian.org/660802 Origin: upstream,https://github.com/joyent/node/commit/285d8c65 Forwarded: not-needed Author: Jérémy Lal Last-Update: 2012-03-29 --- a/lib/buffer.js +++ b/lib/buffer.js @@ -250,6 +250,7 @@ this.parent = pool; this.offset = pool.used; pool.used += this.length; + if (pool.used & 7) pool.used = (pool.used + 8) & ~7; } // Treat array-ish objects as a byte array. debian/patches/2006_use_system_libeio.patch0000644000000000000000000000273212004014433016023 0ustar Description: Use system libeio Allows building against libeio package, ITP#629384 THIS PATCH IS NOT APPLIED YET. It will be when libeio is uploaded. Forwarded: no, unsure why would upstream need that kind of patch. Author: Jérémy Lal Last-Update: 2011-06-26 --- a/wscript +++ b/wscript @@ -363,7 +363,9 @@ if not conf.check(lib='kstat', uselib_store="KSTAT"): conf.fatal("Cannot find kstat library") - conf.sub_config('deps/libeio') + if not conf.check_cxx(lib='eio', header_name='eio.h', + uselib_store='EIO'): + conf.fatal("Cannot find libeio") if conf.env['USE_SHARED_V8']: v8_includes = []; @@ -635,7 +637,6 @@ print "Parallel Jobs: " + str(Options.options.jobs) print "Product type: " + product_type - bld.add_subdirs('deps/libeio') if not bld.env['USE_SHARED_V8']: build_v8(bld) if not bld.env['USE_SHARED_LIBEV']: bld.add_subdirs('deps/libev') @@ -797,8 +798,8 @@ node = bld.new_task_gen("cxx", product_type) node.name = "node" node.target = "node" - node.uselib = 'RT EV OPENSSL CARES EXECINFO DL KVM SOCKET NSL KSTAT UTIL OPROFILE' - node.add_objects = 'eio http_parser' + node.uselib = 'RT EIO EV OPENSSL CARES EXECINFO DL KVM SOCKET NSL KSTAT UTIL OPROFILE' + node.add_objects = 'http_parser' if product_type_is_lib: node.install_path = '${LIBDIR}' else: @@ -840,7 +841,6 @@ node.includes = """ src/ - deps/libeio deps/http_parser """ debian/patches/2004_relax_failing_test.patch0000644000000000000000000000075512004632614016153 0ustar Description: Relax test failing with recent v8 Author: Jérémy Lal Origin: http://lists.alioth.debian.org/pipermail/pkg-javascript-devel/2012-July/003951.html Last-Update: 2012-07-26 --- a/test/message/stack_overflow.out +++ b/test/message/stack_overflow.out @@ -1,6 +1,6 @@ before -*test*message*stack_overflow.js:31 -function stackOverflow() { - ^ +*test*message*stack_overflow.js:* +*function* +*^ RangeError: Maximum call stack size exceeded debian/patches/series0000644000000000000000000000064312004632677012044 0ustar 2001_FHS_paths_for_nodejs.patch 2002_build_without_libv8_debug.patch 2003_rename_node_to_nodejs.patch 2004_relax_failing_test.patch 2005_expected_failing_tests.patch 2007_fix_use_shared_zlib.patch 2008_fix_use_shared_cares.patch 2009_fix_shared_ev.patch 2011_enable_mipsel_build.patch 1001_align_fast_buffers_8byte_boundary.patch #1002_upstream_forgot_to_build_doc.patch 2012_fix_v8_3_10.patch 2013_waf_linkflags.patch debian/patches/2003_rename_node_to_nodejs.patch0000644000000000000000000000153212027336463016631 0ustar Description: Change shell command from node to nodejs Author: Jonas Smedegaard David Paleino Bug-Debian: http://bugs.debian.org/614907 Last-Update: 2012-09-20 --- a/doc/node.1 +++ b/doc/node.1 @@ -2,12 +2,12 @@ .SH "NAME" -node \- Server-side JavaScript +nodejs \- Server-side JavaScript .SH SYNOPSIS -.B node +.B nodejs [ .B \-v ] --- a/tools/wafadmin/Tools/node_addon.py +++ b/tools/wafadmin/Tools/node_addon.py @@ -49,7 +49,7 @@ def detect(conf): found = os.path.exists(conf.env['NODE_PATH']) conf.check_message('node path', '', found, conf.env['NODE_PATH']) - found = os.path.exists(join(prefix, 'bin', 'node')) + found = os.path.exists(join(prefix, 'bin', 'nodejs')) conf.check_message('node prefix', '', found, prefix) ## On Cygwin we need to link to the generated symbol definitions debian/patches/2009_fix_shared_ev.patch0000644000000000000000000001257112004724657015133 0ustar Description: Use system libev Author: Jérémy Lal Forwarded: not-needed Last-Update: 2012-02-17 --- a/wscript +++ b/wscript @@ -212,6 +212,26 @@ , dest='shared_cares_libpath' ) + opt.add_option('--shared-libev' + , action='store_true' + , default=False + , help='Link to a shared libev DLL instead of static linking' + , dest='shared_libev' + ) + + opt.add_option( '--shared-libev-includes' + , action='store' + , default=False + , help='Directory containing libev header files' + , dest='shared_libev_includes' + ) + + opt.add_option( '--shared-libev-libpath' + , action='store' + , default=False + , help='A directory to search for the shared libev DLL' + , dest='shared_libev_libpath' + ) opt.add_option( '--with-dtrace' , action='store_true' @@ -291,6 +311,7 @@ conf.env["USE_SHARED_V8"] = o.shared_v8 or o.shared_v8_includes or o.shared_v8_libpath or o.shared_v8_libname conf.env["USE_SHARED_CARES"] = o.shared_cares or o.shared_cares_includes or o.shared_cares_libpath + conf.env["USE_SHARED_LIBEV"] = o.shared_libev or o.shared_libev_includes or o.shared_libev_libpath conf.env["USE_SHARED_ZLIB"] = o.shared_zlib or o.shared_zlib_includes or o.shared_zlib_libpath conf.env["USE_GDBJIT"] = o.use_gdbjit @@ -453,6 +474,20 @@ libpath=cares_libpath): conf.fatal("Cannot find c-ares") + + if conf.env['USE_SHARED_LIBEV']: + libev_includes = []; + if o.shared_libev_includes: libev_includes.append(o.shared_libev_includes); + libev_libpath = []; + if o.shared_libev_libpath: libev_libpath.append(o.shared_libev_libpath); + if not conf.check_cxx(lib='ev', header_name='ev.h', + uselib_store='EV', + includes=libev_includes, + libpath=libev_libpath): + conf.fatal("Cannot find libev") + else: + conf.sub_config('deps/libev') + conf.define("HAVE_CONFIG_H", 1) if sys.platform.startswith("sunos"): @@ -894,7 +929,7 @@ node = bld.new_task_gen("cxx", product_type) node.name = "node" node.target = "node" - node.uselib = 'RT OPENSSL ZLIB CARES EXECINFO DL KVM SOCKET NSL KSTAT UTIL OPROFILE' + node.uselib = 'RT OPENSSL ZLIB CARES EV EXECINFO DL KVM SOCKET NSL KSTAT UTIL OPROFILE' node.add_objects = 'http_parser' if product_type_is_lib: node.install_path = '${LIBDIR}' --- a/src/node_signal_watcher.h +++ b/src/node_signal_watcher.h @@ -24,7 +24,7 @@ #include #include -#include +#include namespace node { --- a/src/node_stat_watcher.h +++ b/src/node_stat_watcher.h @@ -23,7 +23,7 @@ #define NODE_STAT_WATCHER_H_ #include -#include +#include namespace node { --- a/src/node_io_watcher.h +++ b/src/node_io_watcher.h @@ -23,7 +23,7 @@ #define NODE_IO_H_ #include -#include +#include namespace node { --- a/deps/uv/include/uv-private/uv-unix.h +++ b/deps/uv/include/uv-private/uv-unix.h @@ -24,7 +24,7 @@ #include "ngx-queue.h" -#include "ev.h" +#include #include "eio.h" #include --- a/deps/uv/config-unix.mk +++ b/deps/uv/config-unix.mk @@ -19,9 +19,8 @@ # IN THE SOFTWARE. E= -CSTDFLAG=--std=c89 -pedantic -Wall -Wextra -Wno-unused-parameter +CSTDFLAG=-pedantic -Wall -Wextra -Wno-unused-parameter CFLAGS += -g -CPPFLAGS += -Isrc/unix/ev LINKFLAGS=-lm CPPFLAGS += -D_LARGEFILE_SOURCE @@ -60,8 +59,7 @@ EV_CONFIG=config_linux.h EIO_CONFIG=config_linux.h CSTDFLAG += -D_GNU_SOURCE -CPPFLAGS += -I/usr/include -LINKFLAGS+=-lrt -lc-ares +LINKFLAGS+=-lrt -lc-ares -lev OBJS += src/unix/linux.o endif @@ -124,8 +122,8 @@ RUNNER_LIBS= RUNNER_SRC=test/runner-unix.c -uv.a: $(OBJS) src/uv-common.o src/unix/ev/ev.o src/unix/uv-eio.o src/unix/eio/eio.o - $(AR) rcs uv.a $(OBJS) src/uv-common.o src/unix/uv-eio.o src/unix/ev/ev.o src/unix/eio/eio.o +uv.a: $(OBJS) src/uv-common.o src/unix/uv-eio.o src/unix/eio/eio.o + $(AR) rcs uv.a $(OBJS) src/uv-common.o src/unix/uv-eio.o src/unix/eio/eio.o src/unix/%.o: src/unix/%.c include/uv.h include/uv-private/uv-unix.h src/unix/internal.h $(CC) $(CSTDFLAG) $(CPPFLAGS) -Isrc $(CFLAGS) -c $< -o $@ @@ -133,9 +131,6 @@ src/uv-common.o: src/uv-common.c include/uv.h include/uv-private/uv-unix.h $(CC) $(CSTDFLAG) $(CPPFLAGS) $(CFLAGS) -c src/uv-common.c -o src/uv-common.o -src/unix/ev/ev.o: src/unix/ev/ev.c - $(CC) $(CPPFLAGS) $(CFLAGS) -c src/unix/ev/ev.c -o src/unix/ev/ev.o -DEV_CONFIG_H=\"$(EV_CONFIG)\" - EIO_CPPFLAGS += $(CPPFLAGS) EIO_CPPFLAGS += -DEIO_CONFIG_H=\"$(EIO_CONFIG)\" --- a/deps/uv/include/uv.h +++ b/deps/uv/include/uv.h @@ -208,9 +208,6 @@ UV_EXTERN uv_loop_t* uv_loop_new(void); UV_EXTERN void uv_loop_delete(uv_loop_t*); -/* This is a debugging tool. It's NOT part of the official API. */ -UV_EXTERN int uv_loop_refcount(const uv_loop_t*); - /* * Returns the default loop. --- a/deps/uv/src/unix/core.c +++ b/deps/uv/src/unix/core.c @@ -179,10 +179,6 @@ } -int uv_loop_refcount(const uv_loop_t* loop) { - return ev_loop_refcount(loop->ev); -} - uv_loop_t* uv_default_loop(void) { if (!default_loop_ptr) { debian/nodejs-dev.bash-completion0000644000000000000000000000005112004014433014215 0ustar debian/node-waf.bash-completion node-waf debian/nodejs-dev.install0000644000000000000000000000031212004014433012577 0ustar debian/tmp/usr/bin/node-waf debian/tmp/usr/include/node/*.h usr/include/nodejs debian/tmp/usr/include/node/uv-private/*.h usr/include/nodejs/uv-private debian/tmp/usr/lib/node/wafadmin usr/share/nodejs debian/TODO0000644000000000000000000000006612004014433007647 0ustar * Support node shebang. Notice lintian maintainers? debian/nodejs.doc-base0000644000000000000000000000037512004014433012043 0ustar Document: nodejs-api Title: Node API Manual Author: Ryan Dahl Abstract: This manual describes the API and command-line usage of Node. Section: Programming Format: HTML Index: /usr/share/doc/nodejs/api/index.html Files: /usr/share/doc/nodejs/api/*.html debian/control0000644000000000000000000000657412054745017010612 0ustar Source: nodejs Section: web Priority: extra Maintainer: Debian Javascript Maintainers Uploaders: Jérémy Lal , Jonas Smedegaard DM-Upload-Allowed: yes Build-Depends: cdbs, devscripts, debhelper, dh-buildinfo, binutils, openssl (>= 1.0.0g), pkg-config, bash-completion, curl, procps, zlib1g-dev, python, libv8-dev (>= 3.7), libssl-dev (>= 1.0.0g), libev-dev (>= 1:4.11), libc-ares-dev (>= 1.7.5) Standards-Version: 3.9.3 Homepage: http://nodejs.org/ Vcs-Browser: http://git.debian.org/?p=collab-maint/nodejs.git Vcs-Git: git://git.debian.org/git/collab-maint/nodejs.git Package: nodejs-dev Section: devel Architecture: any Depends: ${cdbs:Depends}, ${misc:Depends}, nodejs (= ${binary:Version}) Description: Development files for Node.js Node.js provides an event-based server-side javascript engine. . It is similar in design to and influenced by systems like Ruby's Event Machine or Python's Twisted. . Node.js takes the event model a bit further - it presents the event loop as a language construct instead of as a library. . This package is needed to build plugins. Package: nodejs Architecture: any Depends: ${shlibs:Depends}, ${misc:Depends} Breaks: ${cdbs:Breaks} Description: Node.js event-based server-side javascript engine Node.js is similar in design to and influenced by systems like Ruby's Event Machine or Python's Twisted. . It takes the event model a bit further - it presents the event loop as a language construct instead of as a library. . Node.js is bundled with several useful libraries to handle server tasks : System, Events, Standard I/O, Modules, Timers, Child Processes, POSIX, HTTP, Multipart Parsing, TCP, DNS, Assert, Path, URL, Query Strings. Package: nodejs-dbg Section: debug Architecture: any Depends: ${misc:Depends}, nodejs (= ${binary:Version}) Suggests: libv8-dbg Description: Node.js event-based server-side javascript engine (debug) Node.js is similar in design to and influenced by systems like Ruby's Event Machine or Python's Twisted. . It takes the event model a bit further - it presents the event loop as a language construct instead of as a library. . Node.js is bundled with several useful libraries to handle server tasks : System, Events, Standard I/O, Modules, Timers, Child Processes, POSIX, HTTP, Multipart Parsing, TCP, DNS, Assert, Path, URL, Query Strings. . This package contains the debugging symbols. Package: nodejs-legacy Priority: extra Architecture: all Depends: ${misc:Depends}, nodejs (>= 0.6.19~dfsg1-3~) Conflicts: node Description: Node.js event-based server-side javascript engine (legacy symlink) Node.js is similar in design to and influenced by systems like Ruby's Event Machine or Python's Twisted. . It takes the event model a bit further - it presents the event loop as a language construct instead of as a library. . Node.js is bundled with several useful libraries to handle server tasks : System, Events, Standard I/O, Modules, Timers, Child Processes, POSIX, HTTP, Multipart Parsing, TCP, DNS, Assert, Path, URL, Query Strings. . This package contains a symlink for legacy Node.js code requiring binary to be /usr/bin/node (not /usr/bin/nodejs as provided in Debian). . No other Debian packages should depend on this package. For more information, see debian/source/0000755000000000000000000000000012004014454010460 5ustar debian/source/format0000644000000000000000000000001412004014433011663 0ustar 3.0 (quilt) debian/changelog0000644000000000000000000004466612054744617011072 0ustar nodejs (0.6.19~dfsg1-6) unstable; urgency=low * Update package relations: + Generally tighten breaks to relate to (backport of) first known working version (not last known broken version): node → nodejs transition now done for all dependent packages. + Relax needlesly tight breaks for node-bones. + Declare (build-)dependencies in rules file. * Sync rules and control.in with control: Provide binary package nodejs-legacy, and break all packages depending on old binary package node (not conflict directly with it). -- Jonas Smedegaard Mon, 26 Nov 2012 20:55:52 +0100 nodejs (0.6.19~dfsg1-5) unstable; urgency=low * Team upload. * Fix node-waf so that it correctly looks for "nodejs" instead of "node" (patched node_addon.py) -- David Paleino Fri, 21 Sep 2012 23:23:16 +0200 nodejs (0.6.19~dfsg1-4) unstable; urgency=medium * Update package relations: + Break only packages actually calling /usr/bin/node (directly or via env). + Tighten breaks for packages with fixed release. * Set urgency=medium as this change affects only packaging hints so should not need reset of aging timer in unstable. -- Jonas Smedegaard Mon, 06 Aug 2012 14:51:31 +0200 nodejs (0.6.19~dfsg1-3) unstable; urgency=low [ Jérémy Lal ] * debian/patches: + 2012_fix_v8_3_10.patch, fix crash on exit when building against libv8-3.10.8. + 2013_waf_linkflags.patch, waf must support LINKFLAGS, Closes: #678563. [ Jonas Smedegaard ] * Rename binary node → nodejs: + Adjust paths of binary and manpage. + Fix avoid bogus explicit installation of debug files. + Adjust install scripts and add cleanup for old alternative. + Patch manpage to adjust command name. + Have binary package nodejs break any packages in Debian that reference /usr/bin/node. + Add new binary package nodejs-legacy, and have that (not nodejs) conflict with node. + Add NEWS entry. Closes: bug#611698, #681360. See also bug#614907. Thanks to tech-ctte and everyone else helping to resolve this. * Work around upstream shipping docs in wrong subdir, and disable huge patch 1002 attempting same but causing FTBFS for me. Keep patch 1002 in source, to ease proof-reading by release team. * Add patch 2004 to fix FTBFS: Relax a test to work with slightly different output when linked against recent v8. -- Jonas Smedegaard Sat, 28 Jul 2012 11:19:38 +0200 nodejs (0.6.19~dfsg1-2) unstable; urgency=low * debian/patches: + 2005_expected_failing_tests.patch, more tests can timeout. + 1002_upstream_forgot_to_build_doc.patch, include docs from late release of version 0.6.19. * debian/nodejs.docs: + update path + include markdown files. -- Jérémy Lal Wed, 06 Jun 2012 23:35:37 +0200 nodejs (0.6.19~dfsg1-1) unstable; urgency=low * Upstream update. -- Jérémy Lal Wed, 06 Jun 2012 19:11:21 +0200 nodejs (0.6.18~dfsg1-1) unstable; urgency=low * Upstream update. * debian/patches: + 1002_make_test_not_weak.patch removed, applied upstream. + unfuzz patches. -- Jérémy Lal Wed, 16 May 2012 02:06:42 +0200 nodejs (0.6.17~dfsg1-1) unstable; urgency=low * Upstream update. * Update copyright file: add test/*/testcfg.py files. * debian/patches/1002_make_test_not_weak.patch fixes Makefile test target, otherwise it tries to install an unneeded npm module. -- Jérémy Lal Fri, 04 May 2012 22:38:30 +0200 nodejs (0.6.16~dfsg1-2) unstable; urgency=low * Allow test-dgram-pingpong failure on buildd servers. -- Jérémy Lal Mon, 30 Apr 2012 22:42:23 +0200 nodejs (0.6.16~dfsg1-1) unstable; urgency=low [ Jonas Smedegaard ] * Update copyright file: + Fix Files section for marked: Use asterisk for dir, and ignore symlink. + Tidy Files section for waf-light: Drop superfluous © mark and excess indentation, and sort by year and then name. [ Jonathan Nieder ] * Add /usr/bin/nodejs as a symlink to node and nodejs.1.gz as a symlink to the node(1) manpage. Explanation in README.Debian. Closes: #650343. * Include README.Debian in nodejs package instead of nodejs-dev. [ Jérémy Lal ] * Upstream update. * Fix dversionmangle in watch file. -- Jérémy Lal Mon, 30 Apr 2012 20:58:46 +0200 nodejs (0.6.14~dfsg1-1) unstable; urgency=low * debian/patches/2005_expected_failing_tests.patch: + test-cluster-kill-workers can fail on any arch, not only armel, because it is racey. + test-buffer is not failing. + test-tls-server-verify can fail with openssl 1.0.1 * debian/patches/1001_align_fast_buffers_8byte_boundary.patch fixes test-buffer.js failure on armel. Closes: bug#660800. * debian/patches/2011_enable_mipsel_build.patch: options.arch is useless and buggy. Closes: bug#664627. * Include tools/doc, now properly licensed. * Include tools/doc/node_modules/marked : there are several other markdown parsers in debian, but porting tools/doc/generate.js to one of them is not an easy task. * Update copyright file: + tools/doc is already covered by default + Add Files paragraph covering tools/doc/node_modules/marked. * Remove libv8-dev << 3.8. It is not necessary to conflict with next libv8 branch. * Remove source override: source-contains-waf-binary, fixed in lintian. -- Jérémy Lal Tue, 03 Apr 2012 08:41:15 +0200 nodejs (0.6.12~dfsg1-1) unstable; urgency=low * Update Standards-Version to 3.9.3. * Patch wscript to enable build on mipsel arch, libv8 being available. Upstream does not support that arch, failure expected. * test-cluster-kill-workers is expected to fail on armhf, Bug#660802 will be closed when test pass. * test-buffer is expected to fail on armel, Bug#660800 will be closed when test pass. * Add epoch to dependency on libev >= 1:4.11. Closes: bug#658441. * Remove tools/doc because node-doc-generator has no license for now. * Add copyright for doc/sh* files (shjs). * source.lintian-overrides : source-contains-waf-binary tools/node-waf it is simply not the case here. -- Jérémy Lal Tue, 13 Mar 2012 09:56:02 +0100 nodejs (0.6.11~dfsg1-2) unstable; urgency=low * test-stream-pipe-multi expected to timeout sometimes on busy builds. -- Jérémy Lal Mon, 20 Feb 2012 08:43:24 +0100 nodejs (0.6.11~dfsg1-1) unstable; urgency=low * New upstream release. * Remove upstream patches. * test-dgram-pingpong expected to timeout, the test itself is buggy. * test-buffer expected to fail on armel, allow building package to make it easier to find the cause of the failure. Closes: bug#639636. -- Jérémy Lal Sun, 19 Feb 2012 23:58:31 +0100 nodejs (0.6.10~dfsg2-2) unstable; urgency=low [ Jérémy Lal ] * Expect tests dgram-multicast and broadcast to fail. debian/patches/2005_expected_failing_tests.patch [ Jonas Smedegaard ] * Drop dpkg-source local-options: Defaults since dpkg-source 1.16.1. -- Jonas Smedegaard Fri, 17 Feb 2012 04:18:27 +0100 nodejs (0.6.10~dfsg2-1) unstable; urgency=low * New upstream release. * Depend on libev-dev 4.11, see bug#657080. * Bump dependency on openssl to 1.0.0g. * Remove useless uv_loop_refcount from libuv, refreshed 2009_fix_shared_ev.patch. * Apply to upstream patches landed after 0.6.10 release, to fix debugger repl and http client. -- Jérémy Lal Thu, 16 Feb 2012 23:52:16 +0100 nodejs (0.6.8~dfsg1-1) experimental; urgency=low * New upstream release. Closes:bug#650661 * Repackage to remove non-dfsg font files ./deps/npm/html/*/*.ttf * Remove unneeded bundled dependencies: lighter tarball, debian/copyright is easier to maintain. * Drop unneeded build-dependency on scons. * Depend on zlib1g, libc-ares, libev. Patches done to support building with those shared libs. * Fix DEB_UPSTREAM_URL in debian/rules, and debian/watch. * nodejs.pc file for pkgconfig is no more available. * Build-depend on procps package, a test is using /bin/ps. * Refreshed debian/patches/2005_expected_failing_tests.patch, only for tests that need networking. -- Jérémy Lal Tue, 24 Jan 2012 13:37:01 +0100 nodejs (0.4.12-3) unstable; urgency=low * Depend on libv8 3.6 (>= 3.6.6.14-2), because it fixes CVE-2011-5037. This breaks test/simple/test-sys.js, fixed by an upstream patch. -- Jérémy Lal Sun, 08 Jan 2012 12:00:02 +0100 nodejs (0.4.12-2) unstable; urgency=low * Port to libv8 3.5 branch and depend on it. * Force nodejs-dev to depend on libv8-dev << 3.6, to avoid API incompatibilities between nodejs-dev and libv8-dev. This will help fixing bug#650552, thanks to Jonas Smedegaard. * Do not search modules in /usr/local/lib/nodejs, see README.Debian. * Remove useless debian/patches/1006_version.patch * Drop unneeded dependency on Scons. * Build-Depends on openssl, some tests spawn /usr/bin/openssl. -- Jérémy Lal Mon, 05 Dec 2011 11:34:27 +0100 nodejs (0.4.12-1) unstable; urgency=low * New upstream release * Port to libv8 3.4 branch and depend on it. Closes:bug#642731. * debian/gbp.conf: fix syntax, filter 'doc/logos/*' or else pristine-tar will complain. -- Jérémy Lal Tue, 27 Sep 2011 16:10:10 +0200 nodejs (0.4.11-1) unstable; urgency=low * New upstream release * debian/gbp.conf: Filter out doc/logos, unused, too big, and upstream removed it from 0.5 tarballs. * debian/patches/1006_version.patch : upstream forgot to update VERSION flag in wscript. -- Jérémy Lal Thu, 18 Aug 2011 15:09:01 +0200 nodejs (0.4.10-1) unstable; urgency=low * New upstream release -- Jérémy Lal Wed, 20 Jul 2011 20:50:07 +0200 nodejs (0.4.9-1) unstable; urgency=low * New upstream release * Refresh debian/patches, remove 1001_no_ssl_v2.patch, applied upstream. * deps/http_parser.c based on expat-licensed work of Igor Sysoev. -- Jérémy Lal Wed, 29 Jun 2011 16:46:47 +0200 nodejs (0.4.8-1) unstable; urgency=low * New upstream release, Closes: bug#628148. * Depends on libv8 3.1.8.22 * Refresh debian/patches -- Jérémy Lal Sun, 26 Jun 2011 23:08:01 +0200 nodejs (0.4.7-1) unstable; urgency=low * New upstream release * Bump policy compliance to standards-version 3.9.2. * debian/watch : remove call to uupdate, it is annoying since updates are done with git-import-orig. -- Jérémy Lal Sat, 23 Apr 2011 18:42:42 +0200 nodejs (0.4.6-2) unstable; urgency=low * Expect some tests to fail when run without network. Closes: bug#623374. -- Jérémy Lal Tue, 19 Apr 2011 22:17:37 +0200 nodejs (0.4.6-1) unstable; urgency=low * New upstream release [ Jérémy Lal ] * Unfuzz patches. * Update debian/copyright, now copyright Joyent. * Drop SSL2 methods, see #589706. Closes: bug#622065. * Disable multicast test: Too dependent on network config. * Allow Debian-Maintainer uploads. [ Jonas Smedegaard ] * Update copyright file: + Fix relabel OpenBSD license as OpenBSD~Lucent: Disclaimer is derived. + Fix comma-delimit files, and (while at it) newline-delimit them for improved readability. + Compact and extend copyright years. * Enable copyright-check. Build-depend on devscripts. * Add copyright hints. -- Jonas Smedegaard Sun, 17 Apr 2011 05:05:30 +0200 nodejs (0.4.2-1) experimental; urgency=low * New upstream release [ Jérémy Lal ] * Enable regression tests, without failing when targeted experimental. * Unfuzz patches. * Tighten build-dependency on libev-dev, to match new upstream source. -- Jonas Smedegaard Sat, 12 Mar 2011 10:45:08 +0100 nodejs (0.2.6-5) unstable; urgency=low [ Jonas Smedegaard ] * Update team-maintainance: + Set Debian Javascript Maintainers as maintainer. + Set Jérémy Lal, Dave Beckett and myself as uploaders. * Bump policy compliance to standards-version 3.9.2. * Recompile against newer libv8. Closes: bug#622623. Thanks to Adrian Knoth. * Unfuzz patches. [ Jérémy Lal ] * Update git-buildpackage config : add commented lines explaining layout. * Allow Debian-Maintainer uploads. * Add patch 1001 to disable ssl2 methods. -- Jonas Smedegaard Fri, 15 Apr 2011 23:33:09 +0200 nodejs (0.2.6-4) unstable; urgency=low [ Jérémy Lal ] * Disable simple/test-buffer Buffer.unpack test that fails on ARM. The pack/unpack functions are deprecated, and not documented. [ Jonas Smedegaard ] * Drop done items from TODO. -- Jonas Smedegaard Mon, 07 Feb 2011 23:39:40 +0100 nodejs (0.2.6-3) experimental; urgency=low [ Jérémy Lal ] * Disable simple/test-dgram-multicast test that fails on sbuild. -- Jonas Smedegaard Tue, 25 Jan 2011 23:53:05 +0100 nodejs (0.2.6-2) experimental; urgency=low [ Jérémy Lal ] * Build-depends on libv8-2.5.9.9-2. (Closes: #610527, #607319, #605447, #597784) * Refactor patches, DEP-3 format. * Explain modules search paths in README.Debian. [ Jonas Smedegaard ] * Relax nodejs-dbg suggestion on libv8-dbg to be unversioned: already handled by library packages. -- Jonas Smedegaard Tue, 25 Jan 2011 22:11:05 +0100 nodejs (0.2.6-1) experimental; urgency=low [ Jérémy Lal ] * New upstream release. * nodejs is an alternative to js. (Closes: #597572) * Use upstream binary names for node and node-waf, conflicts with node package. (Closes: #597571) * Global modules search paths : /usr/local/lib/nodejs /usr/lib/nodejs Custom paths can be set through NODE_PATH. The reason is to support future npm package, giving higher priority to modules installed by npm as root. * Repackage using CDBS. Enable regression testing. * Add a note about importing upstream tarball in README.source. * Update TODO [ Jonas Smedegaard ] * Add myself as uploader. * Limit watch file to stable releases. * Enable CDBS build-dependency autoresolving. * Tighten build-dependency on cdbs to versions properly supporting debhelper compat level 7. * Tighten build-dependency on debhelper to versions fully supporting compat level 7. * Build-depend on dh-buildinfo to include buildinfo hints with binary packages for easier troubleshooting. * Build-depend on curl: Needed for regression tests (testing on loopback, so should be Policy compliant). * Newline-delimit package relations for improved readability. * Add patch 2001 to skip TTY-needing regression test. -- Jonas Smedegaard Fri, 21 Jan 2011 21:00:24 +0100 nodejs (0.2.2-1) experimental; urgency=low * New upstream release -- Jérémy Lal Fri, 17 Sep 2010 21:27:40 +0200 nodejs (0.2.0-1) unstable; urgency=low * New upstream release -- Jérémy Lal Fri, 20 Aug 2010 11:49:04 +0200 nodejs (0.1.104-1) unstable; urgency=low * New upstream release. (Closes: #593088) -- Jérémy Lal Mon, 16 Aug 2010 07:07:09 +0200 nodejs (0.1.102-1) unstable; urgency=low * New upstream release -- Jérémy Lal Tue, 27 Jul 2010 08:29:40 +0200 nodejs (0.1.101-2) unstable; urgency=low * Build-Depends on bash-completion for dh_bash-completion -- Jérémy Lal Wed, 21 Jul 2010 08:58:52 +0200 nodejs (0.1.101-1) unstable; urgency=low * New upstream release * Standards-Version 3.9.0 * Move BSD license in debian/copyright * nodejs-waf now accepts NODE_PATH environment variable, which defines where to install compiled modules. Defaults to ~/.node_libraries. * nodejs-waf bash-completion snippet * API Manual registered with doc-base. * Depends on libv8-2.2.24 -- Jérémy Lal Wed, 14 Jul 2010 13:52:07 +0200 nodejs (0.1.99-1) unstable; urgency=low * New upstream release * DNS module : MX support since c-ares 1.7.3 * nodejs-repl is replaced by invoking nodejs without file argument, rlwrap is no more needed. * Full upstream author name in debian/copyright. -- Jérémy Lal Tue, 29 Jun 2010 08:25:13 +0200 nodejs (0.1.97-1) unstable; urgency=low * New upstream release -- Jérémy Lal Sun, 30 May 2010 23:14:24 +0200 nodejs (0.1.95-1) unstable; urgency=low * New upstream release -- Jérémy Lal Fri, 14 May 2010 02:05:25 +0200 nodejs (0.1.94-2) unstable; urgency=low * Drop dependencies on libgnutls-dev, libgpg-error-dev. * Modules path moved to /usr/lib/nodejs (without /modules), to follow more closely upstream practice. * node-repl is now in /usr/share/nodejs because it is simply a js script file ; nodejs-repl still in /usr/bin -- Jérémy Lal Tue, 11 May 2010 19:52:12 +0200 nodejs (0.1.94-1) unstable; urgency=low * New upstream release * API has changed and will be more stable with 0.2 release * Fix dependency on libv8. (Closes: #579044) * Switched from gnutls to libssl. -- Jérémy Lal Thu, 06 May 2010 23:19:12 +0200 nodejs (0.1.92-1) unstable; urgency=low * New upstream release * Switch from udns to c-ares. -- Jérémy Lal Sat, 24 Apr 2010 09:12:06 +0200 nodejs (0.1.33-3) unstable; urgency=low * Fix wrong use of binary-indep target in debian/rules. (Closes: #575383) -- Jérémy Lal Mon, 05 Apr 2010 15:26:40 +0200 nodejs (0.1.33-2) unstable; urgency=low * Previous package was broken in some way. (Closes: #575383) -- Jérémy Lal Thu, 25 Mar 2010 12:24:06 +0100 nodejs (0.1.33-1) unstable; urgency=low * New upstream release. (Closes: #572023) * Debian package has the same license as upstream (MIT). * Include waf in source package and nodejs-dev package. (Closes: #571710) * Switch to dpkg-source 3.0 (quilt) format. * Place modules directory in usr/lib/nodejs/modules, and add it to nodejs module path. Documentation in README.Debian. * Architecture: any since the supported archs depends only on libv8. -- Jérémy Lal Mon, 22 Mar 2010 01:53:48 +0100 nodejs (0.1.27+dfsg-1) unstable; urgency=low * Initial release (Closes: #553514) -- Jérémy Lal Sun, 07 Feb 2010 01:16:07 +0100 debian/README.source0000644000000000000000000000030212004014454011332 0ustar git-buildpackage ================ debian/control.in ----------------- debian/control is generated from debian/control.in, to update it, run : DEB_MAINTAINER_MODE=1 fakeroot debian/rules clean debian/nodejs.docs0000644000000000000000000000001012004014454011303 0ustar doc/api debian/node-waf.bash-completion0000644000000000000000000000035312004014433013664 0ustar have node-waf && _node_waf() { cur=${COMP_WORDS[COMP_CWORD]} if [ $COMP_CWORD -ge 1 ]; then COMPREPLY=( $( compgen -W "distclean clean configure build install uninstall" $cur ) ) fi } complete -F _node_waf node-waf debian/nodejs-dev.dirs0000644000000000000000000000005412004014433012075 0ustar usr/include/nodejs usr/share/nodejs usr/bin debian/compat0000644000000000000000000000000212004014433010353 0ustar 7 debian/watch0000644000000000000000000000034712004014454010215 0ustar version=3 opts=downloadurlmangle=s/.*v(.*)\//http\:\/\/nodejs\.org\/dist\/v$1\/node\-v$1\.tar\.gz/,\ filenamemangle=s/.*v(.*)\/$/nodejs-$1\.tar\.gz/,\ dversionmangle=s/~dfsg\d+$// \ http://nodejs.org/dist v(\d+\.[02468]\.[.0-9]+)/ debian/copyright_hints0000644000000000000000000020177112054741630012340 0ustar Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Upstream-Name: FIXME Upstream-Contact: FIXME Source: FIXME Disclaimer: Autogenerated by CDBS Files: benchmark/next-tick-2.js lib/_debugger.js lib/_linklist.js lib/buffer.js lib/child_process.js lib/cluster.js lib/console.js lib/constants.js lib/crypto.js lib/dgram.js lib/dns.js lib/events.js lib/freelist.js lib/fs.js lib/http.js lib/https.js lib/module.js lib/net.js lib/os.js lib/path.js lib/querystring.js lib/readline.js lib/repl.js lib/stream.js lib/string_decoder.js lib/sys.js lib/timers.js lib/tls.js lib/tty.js lib/url.js lib/util.js lib/vm.js lib/zlib.js src/cares_wrap.cc src/fs_event_wrap.cc src/handle_wrap.cc src/handle_wrap.h src/node.cc src/node.d src/node.h src/node.js src/node_buffer.cc src/node_buffer.h src/node_config.h.in src/node_constants.cc src/node_constants.h src/node_crypto.h src/node_dtrace.cc src/node_dtrace.h src/node_extensions.cc src/node_extensions.h src/node_file.cc src/node_file.h src/node_http_parser.cc src/node_http_parser.h src/node_io_watcher.cc src/node_io_watcher.h src/node_javascript.cc src/node_javascript.h src/node_main.cc src/node_object_wrap.h src/node_os.cc src/node_os.h src/node_provider.d src/node_root_certs.h src/node_script.cc src/node_script.h src/node_signal_watcher.cc src/node_signal_watcher.h src/node_stat_watcher.cc src/node_stat_watcher.h src/node_string.cc src/node_string.h src/node_version.h src/node_zlib.cc src/pipe_wrap.cc src/pipe_wrap.h src/platform.h src/platform_darwin.cc src/platform_freebsd.cc src/platform_linux.cc src/platform_none.cc src/platform_openbsd.cc src/platform_sunos.cc src/platform_win32.cc src/platform_win32.h src/process_wrap.cc src/req_wrap.h src/stream_wrap.cc src/stream_wrap.h src/tcp_wrap.cc src/tcp_wrap.h src/timer_wrap.cc src/tty_wrap.cc src/udp_wrap.cc test/common.js test/disabled/GH-670.js test/disabled/test-cat.js test/disabled/test-child-process-custom-fds.js test/disabled/test-dgram-multicast.js test/disabled/test-dgram-unix-anon.js test/disabled/test-dgram-unix.js test/disabled/test-dns.js test/disabled/test-eio-race3.js test/disabled/test-fs-sendfile.js test/disabled/test-http-agent2.js test/disabled/test-http-big-proxy-responses.js test/disabled/test-http-default-port.js test/disabled/test-http-head-request.js test/disabled/test-http-stress.js test/disabled/test-http-tls.js test/disabled/test-https-loop-to-google.js test/disabled/test-idle-watcher.js test/disabled/test-net-fd-passing.js test/disabled/test-net-tls-pummel.js test/disabled/test-net-tls.js test/disabled/test-process-title.js test/disabled/test-readline.js test/disabled/test-remote-module-loading.js test/disabled/test-sendfd.js test/disabled/test-setuidgid.js test/disabled/test-tls-large-push.js test/disabled/test-tls-server.js test/disabled/test-tty-stdio.js test/disabled/tls-client.js test/disabled/tls_client.js test/disabled/tls_server.js test/fixtures/GH-1899-output.js test/fixtures/GH-892-request.js test/fixtures/a.js test/fixtures/a1.js test/fixtures/b/c.js test/fixtures/b/d.js test/fixtures/b/package/index.js test/fixtures/catch-stdout-error.js test/fixtures/child_process_should_emit_error.js test/fixtures/create-file.js test/fixtures/cycles/folder/foo.js test/fixtures/cycles/root.js test/fixtures/echo.js test/fixtures/exit.js test/fixtures/global/plain.js test/fixtures/module-load-order/file1.js test/fixtures/module-load-order/file2.js test/fixtures/module-load-order/file2/index.js test/fixtures/module-load-order/file3/index.js test/fixtures/module-load-order/file4/index.js test/fixtures/module-load-order/file5/index.js test/fixtures/module-load-order/file6/index.js test/fixtures/nested-index/one/hello.js test/fixtures/nested-index/one/index.js test/fixtures/nested-index/three.js test/fixtures/nested-index/three/index.js test/fixtures/nested-index/two/hello.js test/fixtures/nested-index/two/index.js test/fixtures/net-fd-passing-receiver.js test/fixtures/node_modules/asdf.js test/fixtures/node_modules/bar.js test/fixtures/node_modules/baz/index.js test/fixtures/node_modules/baz/node_modules/asdf.js test/fixtures/node_modules/foo.js test/fixtures/node_modules/node_modules/bar.js test/fixtures/not-main-module.js test/fixtures/packages/main-index/package-main-module/index.js test/fixtures/packages/main/package-main-module.js test/fixtures/print-10-lines.js test/fixtures/print-chars-from-buffer.js test/fixtures/print-chars.js test/fixtures/readdir/testing.js test/fixtures/recvfd.js test/fixtures/semicolon.js test/fixtures/should_exit.js test/fixtures/stdio-filter.js test/fixtures/test-init-index/index.js test/fixtures/test-init-native/fs.js test/fixtures/throws_error.js test/fixtures/throws_error1.js test/fixtures/throws_error2.js test/fixtures/throws_error3.js test/internet/test-dns.js test/message/2100bytes.js test/message/hello_world.js test/message/stack_overflow.js test/message/throw_custom_error.js test/message/throw_non_error.js test/message/undefined_reference_in_new_context.js test/pummel/test-child-process-spawn-loop.js test/pummel/test-debugger-debug-brk.js test/pummel/test-exec.js test/pummel/test-fs-watch-file.js test/pummel/test-http-client-reconnect-bug.js test/pummel/test-http-upload-timeout.js test/pummel/test-https-large-response.js test/pummel/test-keep-alive.js test/pummel/test-net-many-clients.js test/pummel/test-net-pause.js test/pummel/test-net-pingpong-delay.js test/pummel/test-net-pingpong.js test/pummel/test-net-throttle.js test/pummel/test-net-timeout.js test/pummel/test-net-timeout2.js test/pummel/test-net-write-callbacks.js test/pummel/test-next-tick-loops-quick.js test/pummel/test-process-uptime.js test/pummel/test-regress-GH-814.js test/pummel/test-regress-GH-814_2.js test/pummel/test-regress-GH-892.js test/pummel/test-timer-wrap.js test/pummel/test-timer-wrap2.js test/pummel/test-timers.js test/pummel/test-tls-ci-reneg-attack.js test/pummel/test-tls-throttle.js test/pummel/test-vm-memleak.js test/pummel/test-watch-file.js test/simple/path.js test/simple/test-assert.js test/simple/test-buffer-regress-GH-2659.js test/simple/test-buffer.js test/simple/test-c-ares.js test/simple/test-chdir.js test/simple/test-child-process-buffering.js test/simple/test-child-process-customfd-bounded.js test/simple/test-child-process-cwd.js test/simple/test-child-process-double-pipe.js test/simple/test-child-process-env.js test/simple/test-child-process-exec-cwd.js test/simple/test-child-process-exec-env.js test/simple/test-child-process-exit-code.js test/simple/test-child-process-fork-and-spawn.js test/simple/test-child-process-fork.js test/simple/test-child-process-fork2.js test/simple/test-child-process-fork3.js test/simple/test-child-process-ipc.js test/simple/test-child-process-kill.js test/simple/test-child-process-set-blocking.js test/simple/test-child-process-stdin.js test/simple/test-child-process-stdout-flush.js test/simple/test-cli-eval.js test/simple/test-cluster-kill-workers.js test/simple/test-cluster-uncaught-exception.js test/simple/test-cluster-worker-death.js test/simple/test-console-not-call-toString.js test/simple/test-console.js test/simple/test-crypto-ecb.js test/simple/test-crypto-random.js test/simple/test-crypto.js test/simple/test-debugger-client.js test/simple/test-debugger-repl-utf8.js test/simple/test-debugger-repl.js test/simple/test-delayed-require.js test/simple/test-dgram-broadcast-multi-process.js test/simple/test-dgram-close.js test/simple/test-dgram-multicast-multi-process.js test/simple/test-dgram-multicast-setTTL.js test/simple/test-dgram-pingpong.js test/simple/test-dgram-send-error.js test/simple/test-dgram-udp4.js test/simple/test-eio-race.js test/simple/test-eio-race2.js test/simple/test-eio-race4.js test/simple/test-error-reporting.js test/simple/test-eval-require.js test/simple/test-eval.js test/simple/test-event-emitter-add-listeners.js test/simple/test-event-emitter-check-listener-leaks.js test/simple/test-event-emitter-max-listeners.js test/simple/test-event-emitter-modify-in-emit.js test/simple/test-event-emitter-num-args.js test/simple/test-event-emitter-once.js test/simple/test-event-emitter-remove-all-listeners.js test/simple/test-event-emitter-remove-listeners.js test/simple/test-exception-handler.js test/simple/test-exception-handler2.js test/simple/test-exec-max-buffer.js test/simple/test-executable-path.js test/simple/test-file-read-noexist.js test/simple/test-file-write-stream.js test/simple/test-file-write-stream2.js test/simple/test-file-write-stream3.js test/simple/test-fs-chmod.js test/simple/test-fs-empty-readStream.js test/simple/test-fs-error-messages.js test/simple/test-fs-fsync.js test/simple/test-fs-largefile.js test/simple/test-fs-long-path.js test/simple/test-fs-mkdir.js test/simple/test-fs-open.js test/simple/test-fs-read-buffer.js test/simple/test-fs-read-file-sync-hostname.js test/simple/test-fs-read-file-sync.js test/simple/test-fs-read-stream-fd.js test/simple/test-fs-read-stream-resume.js test/simple/test-fs-read-stream.js test/simple/test-fs-read.js test/simple/test-fs-readfile-empty.js test/simple/test-fs-readfile-unlink.js test/simple/test-fs-realpath.js test/simple/test-fs-sir-writes-alot.js test/simple/test-fs-stat.js test/simple/test-fs-stream-double-close.js test/simple/test-fs-symlink.js test/simple/test-fs-sync-fd-leak.js test/simple/test-fs-utimes.js test/simple/test-fs-watch.js test/simple/test-fs-write-buffer.js test/simple/test-fs-write-file-buffer.js test/simple/test-fs-write-file.js test/simple/test-fs-write-stream-change-open.js test/simple/test-fs-write-stream-end.js test/simple/test-fs-write-stream.js test/simple/test-fs-write-sync.js test/simple/test-fs-write.js test/simple/test-global.js test/simple/test-http-1.0.js test/simple/test-http-304.js test/simple/test-http-abort-before-end.js test/simple/test-http-abort-client.js test/simple/test-http-agent.js test/simple/test-http-allow-req-after-204-res.js test/simple/test-http-bind-twice.js test/simple/test-http-blank-header.js test/simple/test-http-buffer-sanity.js test/simple/test-http-client-abort.js test/simple/test-http-client-abort2.js test/simple/test-http-client-agent.js test/simple/test-http-client-parse-error.js test/simple/test-http-client-race-2.js test/simple/test-http-client-race.js test/simple/test-http-client-timeout.js test/simple/test-http-client-upload-buf.js test/simple/test-http-client-upload.js test/simple/test-http-conn-reset.js test/simple/test-http-contentLength0.js test/simple/test-http-curl-chunk-problem.js test/simple/test-http-default-encoding.js test/simple/test-http-dns-error.js test/simple/test-http-dns-fail.js test/simple/test-http-eof-on-connect.js test/simple/test-http-exceptions.js test/simple/test-http-expect-continue.js test/simple/test-http-extra-response.js test/simple/test-http-full-response.js test/simple/test-http-get-pipeline-problem.js test/simple/test-http-head-request.js test/simple/test-http-head-response-has-no-body-end.js test/simple/test-http-head-response-has-no-body.js test/simple/test-http-header-read.js test/simple/test-http-host-headers.js test/simple/test-http-keep-alive-close-on-header.js test/simple/test-http-keep-alive.js test/simple/test-http-legacy.js test/simple/test-http-malformed-request.js test/simple/test-http-many-keep-alive-connections.js test/simple/test-http-multi-line-headers.js test/simple/test-http-mutable-headers.js test/simple/test-http-no-content-length.js test/simple/test-http-parser-free.js test/simple/test-http-parser.js test/simple/test-http-patch.js test/simple/test-http-pipe-fs.js test/simple/test-http-proxy.js test/simple/test-http-request-end-twice.js test/simple/test-http-request-end.js test/simple/test-http-res-write-end-dont-take-array.js test/simple/test-http-response-close.js test/simple/test-http-response-no-headers.js test/simple/test-http-response-readable.js test/simple/test-http-server-multiheaders.js test/simple/test-http-server.js test/simple/test-http-set-cookies.js test/simple/test-http-set-timeout.js test/simple/test-http-set-trailers.js test/simple/test-http-should-keep-alive.js test/simple/test-http-status-code.js test/simple/test-http-unix-socket.js test/simple/test-http-upgrade-agent.js test/simple/test-http-upgrade-client.js test/simple/test-http-upgrade-client2.js test/simple/test-http-upgrade-server.js test/simple/test-http-upgrade-server2.js test/simple/test-http-url.parse-auth-with-header-in-request.js test/simple/test-http-url.parse-auth.js test/simple/test-http-url.parse-basic.js test/simple/test-http-url.parse-https.request.js test/simple/test-http-url.parse-only-support-http-https-protocol.js test/simple/test-http-url.parse-path.js test/simple/test-http-url.parse-post.js test/simple/test-http-url.parse-search.js test/simple/test-http-wget.js test/simple/test-http-write-empty-string.js test/simple/test-http.js test/simple/test-https-agent.js test/simple/test-https-connecting-to-http.js test/simple/test-https-drain.js test/simple/test-https-eof-for-eom.js test/simple/test-https-foafssl.js test/simple/test-https-invalid-key.js test/simple/test-https-pfx.js test/simple/test-https-simple.js test/simple/test-init.js test/simple/test-memory-usage-emfile.js test/simple/test-memory-usage.js test/simple/test-mkdir-rmdir.js test/simple/test-module-load-list.js test/simple/test-module-loading.js test/simple/test-net-after-close.js test/simple/test-net-binary.js test/simple/test-net-bind-twice.js test/simple/test-net-bytes-stats.js test/simple/test-net-can-reset-timeout.js test/simple/test-net-connect-buffer.js test/simple/test-net-connect-handle-econnrefused.js test/simple/test-net-connect-timeout.js test/simple/test-net-create-connection.js test/simple/test-net-dns-error.js test/simple/test-net-eaddrinuse.js test/simple/test-net-isip.js test/simple/test-net-keepalive.js test/simple/test-net-large-string.js test/simple/test-net-listen-error.js test/simple/test-net-pingpong.js test/simple/test-net-pipe-connect-errors.js test/simple/test-net-reconnect.js test/simple/test-net-remote-address-port.js test/simple/test-net-server-bind.js test/simple/test-net-server-close.js test/simple/test-net-server-listen-remove-callback.js test/simple/test-net-server-max-connections.js test/simple/test-net-server-try-ports.js test/simple/test-net-settimeout.js test/simple/test-net-socket-destroy-twice.js test/simple/test-net-socket-timeout.js test/simple/test-net-stream.js test/simple/test-net-write-after-close.js test/simple/test-net-write-connect-write.js test/simple/test-net-write-slow.js test/simple/test-next-tick-doesnt-hang.js test/simple/test-next-tick-errors.js test/simple/test-next-tick-ordering.js test/simple/test-next-tick-ordering2.js test/simple/test-next-tick-starvation.js test/simple/test-next-tick.js test/simple/test-os.js test/simple/test-path-makelong.js test/simple/test-path.js test/simple/test-pipe-address.js test/simple/test-pipe-file-to-http.js test/simple/test-pipe-head.js test/simple/test-pipe-return-val.js test/simple/test-pipe-stream.js test/simple/test-pipe.js test/simple/test-process-env.js test/simple/test-process-exit.js test/simple/test-process-kill-null.js test/simple/test-process-next-tick.js test/simple/test-process-wrap.js test/simple/test-pump-file2tcp-noexist.js test/simple/test-pump-file2tcp.js test/simple/test-querystring.js test/simple/test-readdir.js test/simple/test-readdouble.js test/simple/test-readfloat.js test/simple/test-readint.js test/simple/test-readuint.js test/simple/test-regress-GH-1531.js test/simple/test-regress-GH-1697.js test/simple/test-regress-GH-1726.js test/simple/test-regress-GH-1899.js test/simple/test-regress-GH-746.js test/simple/test-regress-GH-784.js test/simple/test-regress-GH-819.js test/simple/test-regress-GH-877.js test/simple/test-regress-GH-897.js test/simple/test-regression-object-prototype.js test/simple/test-repl-.save.load.js test/simple/test-repl-tab-complete.js test/simple/test-repl.js test/simple/test-require-cache-without-stat.js test/simple/test-require-cache.js test/simple/test-require-exceptions.js test/simple/test-require-resolve.js test/simple/test-script-context.js test/simple/test-script-new.js test/simple/test-script-static-context.js test/simple/test-script-static-new.js test/simple/test-script-static-this.js test/simple/test-script-this.js test/simple/test-setproctitle.js test/simple/test-sigint-infinite-loop.js test/simple/test-signal-handler.js test/simple/test-signal-unregister.js test/simple/test-stdin-child-proc.js test/simple/test-stdin-from-file.js test/simple/test-stdin-hang.js test/simple/test-stdin-pause-resume.js test/simple/test-stdout-close-catch.js test/simple/test-stdout-to-file.js test/simple/test-stream-pipe-cleanup.js test/simple/test-stream-pipe-error-handling.js test/simple/test-stream-pipe-event.js test/simple/test-stream-pipe-multi.js test/simple/test-string-decoder.js test/simple/test-sync-fileread.js test/simple/test-sys.js test/simple/test-tcp-wrap-connect.js test/simple/test-tcp-wrap-listen.js test/simple/test-tcp-wrap.js test/simple/test-timers-linked-list.js test/simple/test-timers-uncaught-exception.js test/simple/test-timers-zero-timeout.js test/simple/test-tls-client-abort.js test/simple/test-tls-client-abort2.js test/simple/test-tls-client-resume.js test/simple/test-tls-client-verify.js test/simple/test-tls-connect-given-socket.js test/simple/test-tls-connect-simple.js test/simple/test-tls-connect.js test/simple/test-tls-ext-key-usage.js test/simple/test-tls-invalid-key.js test/simple/test-tls-junk-closes-server.js test/simple/test-tls-npn-server-client.js test/simple/test-tls-over-http-tunnel.js test/simple/test-tls-passphrase.js test/simple/test-tls-pause-close.js test/simple/test-tls-pause.js test/simple/test-tls-peer-certificate.js test/simple/test-tls-remote.js test/simple/test-tls-request-timeout.js test/simple/test-tls-securepair-client.js test/simple/test-tls-securepair-server.js test/simple/test-tls-server-verify.js test/simple/test-tls-session-cache.js test/simple/test-tls-set-ciphers.js test/simple/test-tls-set-encoding.js test/simple/test-tls-sni-server-client.js test/simple/test-tty-stdout-end.js test/simple/test-tty-wrap.js test/simple/test-typed-arrays-typenames.js test/simple/test-umask.js test/simple/test-utf8-scripts.js test/simple/test-util-format.js test/simple/test-util-inspect.js test/simple/test-util.js test/simple/test-vm-create-context-accessors.js test/simple/test-vm-create-context-circular-reference.js test/simple/test-writedouble.js test/simple/test-writefloat.js test/simple/test-writeint.js test/simple/test-writeuint.js test/simple/test-zerolengthbufferbug.js test/simple/test-zlib-from-gzip.js test/simple/test-zlib-from-string.js test/simple/test-zlib-invalid-input.js test/simple/test-zlib-random-byte-pipes.js tools/doc/generate.js tools/doc/html.js tools/doc/json.js wscript Copyright: HOLDERS BE LIABLE FOR ANY CLAIM Joyent, Inc. and other Node contributors License: MIT/X11 (BSD like) FIXME Files: deps/v8/LICENSE deps/v8/LICENSE.v8 deps/v8/Makefile deps/v8/SConstruct deps/v8/benchmarks/base.js deps/v8/benchmarks/regexp.js deps/v8/benchmarks/richards.js deps/v8/benchmarks/run.js deps/v8/benchmarks/splay.js deps/v8/build/armu.gypi deps/v8/build/common.gypi deps/v8/build/gyp_v8 deps/v8/build/standalone.gypi deps/v8/include/v8-debug.h deps/v8/include/v8-preparser.h deps/v8/include/v8-profiler.h deps/v8/include/v8-testing.h deps/v8/include/v8.h deps/v8/include/v8stdint.h deps/v8/preparser/SConscript deps/v8/preparser/preparser-process.cc deps/v8/preparser/preparser.gyp deps/v8/samples/SConscript deps/v8/samples/count-hosts.js deps/v8/samples/lineprocessor.cc deps/v8/samples/process.cc deps/v8/samples/samples.gyp deps/v8/samples/shell.cc deps/v8/src/SConscript deps/v8/src/accessors.cc deps/v8/src/accessors.h deps/v8/src/allocation-inl.h deps/v8/src/allocation.cc deps/v8/src/allocation.h deps/v8/src/api.cc deps/v8/src/api.h deps/v8/src/apinatives.js deps/v8/src/apiutils.h deps/v8/src/arguments.h deps/v8/src/arm/builtins-arm.cc deps/v8/src/arm/code-stubs-arm.cc deps/v8/src/arm/code-stubs-arm.h deps/v8/src/arm/codegen-arm.cc deps/v8/src/arm/codegen-arm.h deps/v8/src/arm/constants-arm.cc deps/v8/src/arm/constants-arm.h deps/v8/src/arm/cpu-arm.cc deps/v8/src/arm/debug-arm.cc deps/v8/src/arm/deoptimizer-arm.cc deps/v8/src/arm/disasm-arm.cc deps/v8/src/arm/frames-arm.cc deps/v8/src/arm/frames-arm.h deps/v8/src/arm/full-codegen-arm.cc deps/v8/src/arm/ic-arm.cc deps/v8/src/arm/lithium-arm.cc deps/v8/src/arm/lithium-arm.h deps/v8/src/arm/lithium-codegen-arm.cc deps/v8/src/arm/lithium-codegen-arm.h deps/v8/src/arm/lithium-gap-resolver-arm.cc deps/v8/src/arm/lithium-gap-resolver-arm.h deps/v8/src/arm/macro-assembler-arm.cc deps/v8/src/arm/macro-assembler-arm.h deps/v8/src/arm/regexp-macro-assembler-arm.cc deps/v8/src/arm/regexp-macro-assembler-arm.h deps/v8/src/arm/simulator-arm.cc deps/v8/src/arm/simulator-arm.h deps/v8/src/arm/stub-cache-arm.cc deps/v8/src/array.js deps/v8/src/ast-inl.h deps/v8/src/ast.cc deps/v8/src/ast.h deps/v8/src/atomicops.h deps/v8/src/atomicops_internals_arm_gcc.h deps/v8/src/atomicops_internals_mips_gcc.h deps/v8/src/atomicops_internals_x86_gcc.cc deps/v8/src/atomicops_internals_x86_gcc.h deps/v8/src/atomicops_internals_x86_macosx.h deps/v8/src/atomicops_internals_x86_msvc.h deps/v8/src/bignum-dtoa.cc deps/v8/src/bignum-dtoa.h deps/v8/src/bignum.cc deps/v8/src/bignum.h deps/v8/src/bootstrapper.cc deps/v8/src/bootstrapper.h deps/v8/src/builtins.cc deps/v8/src/builtins.h deps/v8/src/bytecodes-irregexp.h deps/v8/src/cached-powers.cc deps/v8/src/cached-powers.h deps/v8/src/char-predicates.h deps/v8/src/checks.cc deps/v8/src/checks.h deps/v8/src/circular-queue-inl.h deps/v8/src/circular-queue.cc deps/v8/src/circular-queue.h deps/v8/src/code-stubs.cc deps/v8/src/code-stubs.h deps/v8/src/code.h deps/v8/src/codegen.cc deps/v8/src/codegen.h deps/v8/src/compilation-cache.cc deps/v8/src/compilation-cache.h deps/v8/src/compiler.cc deps/v8/src/compiler.h deps/v8/src/contexts.cc deps/v8/src/contexts.h deps/v8/src/conversions-inl.h deps/v8/src/conversions.cc deps/v8/src/conversions.h deps/v8/src/counters.cc deps/v8/src/counters.h deps/v8/src/cpu-profiler-inl.h deps/v8/src/cpu-profiler.cc deps/v8/src/cpu-profiler.h deps/v8/src/cpu.h deps/v8/src/d8-debug.cc deps/v8/src/d8-debug.h deps/v8/src/d8-posix.cc deps/v8/src/d8-readline.cc deps/v8/src/d8-windows.cc deps/v8/src/d8.cc deps/v8/src/d8.gyp deps/v8/src/d8.h deps/v8/src/d8.js deps/v8/src/data-flow.cc deps/v8/src/data-flow.h deps/v8/src/date.js deps/v8/src/dateparser-inl.h deps/v8/src/dateparser.cc deps/v8/src/dateparser.h deps/v8/src/debug-agent.cc deps/v8/src/debug-agent.h deps/v8/src/debug-debugger.js deps/v8/src/debug.cc deps/v8/src/debug.h deps/v8/src/deoptimizer.cc deps/v8/src/deoptimizer.h deps/v8/src/disasm.h deps/v8/src/disassembler.cc deps/v8/src/disassembler.h deps/v8/src/diy-fp.cc deps/v8/src/diy-fp.h deps/v8/src/double.h deps/v8/src/dtoa.cc deps/v8/src/dtoa.h deps/v8/src/elements.cc deps/v8/src/elements.h deps/v8/src/execution.cc deps/v8/src/execution.h deps/v8/src/extensions/experimental/break-iterator.cc deps/v8/src/extensions/experimental/break-iterator.h deps/v8/src/extensions/experimental/collator.cc deps/v8/src/extensions/experimental/collator.h deps/v8/src/extensions/experimental/datetime-format.cc deps/v8/src/extensions/experimental/datetime-format.h deps/v8/src/extensions/experimental/experimental.gyp deps/v8/src/extensions/experimental/i18n-extension.cc deps/v8/src/extensions/experimental/i18n-extension.h deps/v8/src/extensions/experimental/i18n-locale.cc deps/v8/src/extensions/experimental/i18n-locale.h deps/v8/src/extensions/experimental/i18n-natives.h deps/v8/src/extensions/experimental/i18n-utils.cc deps/v8/src/extensions/experimental/i18n-utils.h deps/v8/src/extensions/experimental/i18n.js deps/v8/src/extensions/experimental/language-matcher.cc deps/v8/src/extensions/experimental/language-matcher.h deps/v8/src/extensions/experimental/number-format.cc deps/v8/src/extensions/experimental/number-format.h deps/v8/src/extensions/externalize-string-extension.cc deps/v8/src/extensions/externalize-string-extension.h deps/v8/src/extensions/gc-extension.cc deps/v8/src/extensions/gc-extension.h deps/v8/src/factory.cc deps/v8/src/factory.h deps/v8/src/fast-dtoa.cc deps/v8/src/fast-dtoa.h deps/v8/src/fixed-dtoa.cc deps/v8/src/fixed-dtoa.h deps/v8/src/flag-definitions.h deps/v8/src/flags.cc deps/v8/src/flags.h deps/v8/src/frames-inl.h deps/v8/src/frames.cc deps/v8/src/frames.h deps/v8/src/full-codegen.cc deps/v8/src/full-codegen.h deps/v8/src/func-name-inferrer.cc deps/v8/src/func-name-inferrer.h deps/v8/src/gdb-jit.cc deps/v8/src/gdb-jit.h deps/v8/src/global-handles.cc deps/v8/src/global-handles.h deps/v8/src/globals.h deps/v8/src/handles-inl.h deps/v8/src/handles.cc deps/v8/src/handles.h deps/v8/src/hashmap.cc deps/v8/src/hashmap.h deps/v8/src/heap-inl.h deps/v8/src/heap-profiler.cc deps/v8/src/heap-profiler.h deps/v8/src/heap.cc deps/v8/src/heap.h deps/v8/src/hydrogen-instructions.cc deps/v8/src/hydrogen-instructions.h deps/v8/src/hydrogen.h deps/v8/src/ia32/builtins-ia32.cc deps/v8/src/ia32/code-stubs-ia32.cc deps/v8/src/ia32/code-stubs-ia32.h deps/v8/src/ia32/codegen-ia32.cc deps/v8/src/ia32/codegen-ia32.h deps/v8/src/ia32/cpu-ia32.cc deps/v8/src/ia32/debug-ia32.cc deps/v8/src/ia32/deoptimizer-ia32.cc deps/v8/src/ia32/disasm-ia32.cc deps/v8/src/ia32/frames-ia32.cc deps/v8/src/ia32/frames-ia32.h deps/v8/src/ia32/full-codegen-ia32.cc deps/v8/src/ia32/ic-ia32.cc deps/v8/src/ia32/lithium-codegen-ia32.cc deps/v8/src/ia32/lithium-codegen-ia32.h deps/v8/src/ia32/lithium-gap-resolver-ia32.cc deps/v8/src/ia32/lithium-gap-resolver-ia32.h deps/v8/src/ia32/lithium-ia32.cc deps/v8/src/ia32/lithium-ia32.h deps/v8/src/ia32/macro-assembler-ia32.cc deps/v8/src/ia32/macro-assembler-ia32.h deps/v8/src/ia32/regexp-macro-assembler-ia32.cc deps/v8/src/ia32/regexp-macro-assembler-ia32.h deps/v8/src/ia32/simulator-ia32.cc deps/v8/src/ia32/simulator-ia32.h deps/v8/src/ia32/stub-cache-ia32.cc deps/v8/src/ic-inl.h deps/v8/src/ic.cc deps/v8/src/ic.h deps/v8/src/inspector.cc deps/v8/src/inspector.h deps/v8/src/interpreter-irregexp.cc deps/v8/src/interpreter-irregexp.h deps/v8/src/isolate-inl.h deps/v8/src/isolate.cc deps/v8/src/isolate.h deps/v8/src/json-parser.h deps/v8/src/json.js deps/v8/src/jsregexp.cc deps/v8/src/jsregexp.h deps/v8/src/list-inl.h deps/v8/src/list.h deps/v8/src/lithium-allocator-inl.h deps/v8/src/lithium-allocator.cc deps/v8/src/lithium-allocator.h deps/v8/src/lithium.cc deps/v8/src/lithium.h deps/v8/src/liveedit-debugger.js deps/v8/src/liveedit.cc deps/v8/src/liveedit.h deps/v8/src/liveobjectlist-inl.h deps/v8/src/liveobjectlist.cc deps/v8/src/liveobjectlist.h deps/v8/src/log-inl.h deps/v8/src/log-utils.cc deps/v8/src/log-utils.h deps/v8/src/log.cc deps/v8/src/log.h deps/v8/src/macro-assembler.h deps/v8/src/macros.py deps/v8/src/mark-compact.cc deps/v8/src/mark-compact.h deps/v8/src/math.js deps/v8/src/messages.cc deps/v8/src/messages.h deps/v8/src/messages.js deps/v8/src/mips/builtins-mips.cc deps/v8/src/mips/code-stubs-mips.cc deps/v8/src/mips/code-stubs-mips.h deps/v8/src/mips/codegen-mips.cc deps/v8/src/mips/codegen-mips.h deps/v8/src/mips/constants-mips.cc deps/v8/src/mips/constants-mips.h deps/v8/src/mips/cpu-mips.cc deps/v8/src/mips/debug-mips.cc deps/v8/src/mips/deoptimizer-mips.cc deps/v8/src/mips/disasm-mips.cc deps/v8/src/mips/frames-mips.cc deps/v8/src/mips/frames-mips.h deps/v8/src/mips/full-codegen-mips.cc deps/v8/src/mips/ic-mips.cc deps/v8/src/mips/lithium-codegen-mips.h deps/v8/src/mips/lithium-mips.h deps/v8/src/mips/macro-assembler-mips.cc deps/v8/src/mips/macro-assembler-mips.h deps/v8/src/mips/regexp-macro-assembler-mips.cc deps/v8/src/mips/regexp-macro-assembler-mips.h deps/v8/src/mips/simulator-mips.cc deps/v8/src/mips/simulator-mips.h deps/v8/src/mips/stub-cache-mips.cc deps/v8/src/mirror-debugger.js deps/v8/src/misc-intrinsics.h deps/v8/src/mksnapshot.cc deps/v8/src/natives.h deps/v8/src/objects-debug.cc deps/v8/src/objects-inl.h deps/v8/src/objects-printer.cc deps/v8/src/objects-visiting.cc deps/v8/src/objects-visiting.h deps/v8/src/objects.cc deps/v8/src/objects.h deps/v8/src/parser.cc deps/v8/src/parser.h deps/v8/src/platform-cygwin.cc deps/v8/src/platform-freebsd.cc deps/v8/src/platform-linux.cc deps/v8/src/platform-macos.cc deps/v8/src/platform-nullos.cc deps/v8/src/platform-openbsd.cc deps/v8/src/platform-posix.cc deps/v8/src/platform-solaris.cc deps/v8/src/platform-tls-mac.h deps/v8/src/platform-tls-win32.h deps/v8/src/platform-tls.h deps/v8/src/platform-win32.cc deps/v8/src/platform.h deps/v8/src/preparse-data-format.h deps/v8/src/preparse-data.cc deps/v8/src/preparse-data.h deps/v8/src/preparser-api.cc deps/v8/src/preparser.cc deps/v8/src/preparser.h deps/v8/src/prettyprinter.cc deps/v8/src/prettyprinter.h deps/v8/src/profile-generator-inl.h deps/v8/src/profile-generator.cc deps/v8/src/profile-generator.h deps/v8/src/property.cc deps/v8/src/property.h deps/v8/src/proxy.js deps/v8/src/regexp-macro-assembler-irregexp-inl.h deps/v8/src/regexp-macro-assembler-irregexp.cc deps/v8/src/regexp-macro-assembler-irregexp.h deps/v8/src/regexp-macro-assembler-tracer.cc deps/v8/src/regexp-macro-assembler-tracer.h deps/v8/src/regexp-macro-assembler.cc deps/v8/src/regexp-macro-assembler.h deps/v8/src/regexp-stack.cc deps/v8/src/regexp-stack.h deps/v8/src/regexp.js deps/v8/src/rewriter.cc deps/v8/src/rewriter.h deps/v8/src/runtime-profiler.cc deps/v8/src/runtime-profiler.h deps/v8/src/runtime.h deps/v8/src/runtime.js deps/v8/src/safepoint-table.cc deps/v8/src/safepoint-table.h deps/v8/src/scanner-character-streams.cc deps/v8/src/scanner-character-streams.h deps/v8/src/scopeinfo.cc deps/v8/src/scopeinfo.h deps/v8/src/scopes.cc deps/v8/src/scopes.h deps/v8/src/serialize.cc deps/v8/src/serialize.h deps/v8/src/simulator.h deps/v8/src/small-pointer-list.h deps/v8/src/smart-array-pointer.h deps/v8/src/snapshot-common.cc deps/v8/src/snapshot-empty.cc deps/v8/src/snapshot.h deps/v8/src/spaces-inl.h deps/v8/src/spaces.cc deps/v8/src/spaces.h deps/v8/src/splay-tree-inl.h deps/v8/src/splay-tree.h deps/v8/src/string-search.cc deps/v8/src/string-search.h deps/v8/src/string-stream.cc deps/v8/src/string-stream.h deps/v8/src/string.js deps/v8/src/strtod.cc deps/v8/src/strtod.h deps/v8/src/stub-cache.cc deps/v8/src/stub-cache.h deps/v8/src/token.cc deps/v8/src/token.h deps/v8/src/type-info.cc deps/v8/src/type-info.h deps/v8/src/unbound-queue-inl.h deps/v8/src/unbound-queue.h deps/v8/src/unicode-inl.h deps/v8/src/unicode.cc deps/v8/src/unicode.h deps/v8/src/uri.js deps/v8/src/utils-inl.h deps/v8/src/utils.cc deps/v8/src/utils.h deps/v8/src/v8-counters.cc deps/v8/src/v8-counters.h deps/v8/src/v8.cc deps/v8/src/v8.h deps/v8/src/v8checks.h deps/v8/src/v8conversions.cc deps/v8/src/v8conversions.h deps/v8/src/v8dll-main.cc deps/v8/src/v8globals.h deps/v8/src/v8memory.h deps/v8/src/v8natives.js deps/v8/src/v8preparserdll-main.cc deps/v8/src/v8threads.cc deps/v8/src/v8threads.h deps/v8/src/v8utils.cc deps/v8/src/v8utils.h deps/v8/src/variables.cc deps/v8/src/variables.h deps/v8/src/version.cc deps/v8/src/version.h deps/v8/src/vm-state-inl.h deps/v8/src/vm-state.h deps/v8/src/weakmap.js deps/v8/src/win32-headers.h deps/v8/src/win32-math.cc deps/v8/src/win32-math.h deps/v8/src/x64/assembler-x64-inl.h deps/v8/src/x64/assembler-x64.cc deps/v8/src/x64/builtins-x64.cc deps/v8/src/x64/code-stubs-x64.cc deps/v8/src/x64/code-stubs-x64.h deps/v8/src/x64/codegen-x64.cc deps/v8/src/x64/codegen-x64.h deps/v8/src/x64/cpu-x64.cc deps/v8/src/x64/debug-x64.cc deps/v8/src/x64/deoptimizer-x64.cc deps/v8/src/x64/disasm-x64.cc deps/v8/src/x64/frames-x64.cc deps/v8/src/x64/frames-x64.h deps/v8/src/x64/full-codegen-x64.cc deps/v8/src/x64/ic-x64.cc deps/v8/src/x64/lithium-codegen-x64.cc deps/v8/src/x64/lithium-codegen-x64.h deps/v8/src/x64/lithium-gap-resolver-x64.cc deps/v8/src/x64/lithium-gap-resolver-x64.h deps/v8/src/x64/lithium-x64.cc deps/v8/src/x64/lithium-x64.h deps/v8/src/x64/macro-assembler-x64.cc deps/v8/src/x64/macro-assembler-x64.h deps/v8/src/x64/regexp-macro-assembler-x64.cc deps/v8/src/x64/regexp-macro-assembler-x64.h deps/v8/src/x64/simulator-x64.cc deps/v8/src/x64/simulator-x64.h deps/v8/src/x64/stub-cache-x64.cc deps/v8/src/zone-inl.h deps/v8/src/zone.cc deps/v8/src/zone.h deps/v8/tools/codemap.js deps/v8/tools/consarray.js deps/v8/tools/csvparser.js deps/v8/tools/disasm.py deps/v8/tools/gc-nvp-trace-processor.py deps/v8/tools/gcmole/Makefile deps/v8/tools/gcmole/gcmole.cc deps/v8/tools/gdb-v8-support.py deps/v8/tools/grokdump.py deps/v8/tools/gyp/v8.gyp deps/v8/tools/jsmin.py deps/v8/tools/ll_prof.py deps/v8/tools/logreader.js deps/v8/tools/oom_dump/SConstruct deps/v8/tools/oom_dump/oom_dump.cc deps/v8/tools/process-heap-prof.py deps/v8/tools/profile.js deps/v8/tools/profile_view.js deps/v8/tools/push-to-trunk.sh deps/v8/tools/run-valgrind.py deps/v8/tools/splaytree.js deps/v8/tools/stats-viewer.py deps/v8/tools/test-wrapper-gypbuild.py deps/v8/tools/tickprocessor-driver.js deps/v8/tools/tickprocessor.js deps/v8/tools/utils.py test/gc/testcfg.py test/internet/testcfg.py test/message/testcfg.py test/pummel/testcfg.py test/simple/testcfg.py tools/js2c.py tools/run-valgrind.py Copyright: 2006-2008, the V8 project authors. 2006-2009, the V8 project authors. 2006-2010, the V8 project authors. 2006-2011, the V8 project authors. 2007-2008, the V8 project authors. 2007-2010, the V8 project authors. 2008, the V8 project authors. 2008-2009, the V8 project authors. 2009, the V8 project authors. 2009-2010, the V8 project authors. 2010, the V8 project authors. 2011, the V8 project authors. 2012, the V8 project authors. HOLDERS AND CONTRIBUTORS License: BSD (3 clause) FIXME Files: AUTHORS BSDmakefile ChangeLog Makefile Makefile-gyp README.md benchmark/arrays/var_int.js benchmark/arrays/zero_float.js benchmark/arrays/zero_int.js benchmark/buffer_creation.js benchmark/fast_buffer2.js benchmark/fast_buffer2_creation.js benchmark/fast_buffer_creation.js benchmark/function_call/bench.js benchmark/function_call/binding.cc benchmark/function_call/wscript benchmark/http_simple.js benchmark/http_simple.rb benchmark/http_simple_auto.js benchmark/http_simple_bench.sh benchmark/http_simple_cluster.js benchmark/idle_clients.js benchmark/idle_server.js benchmark/io.c benchmark/io.js benchmark/next-tick.js benchmark/plot.R benchmark/process_loop.js benchmark/report-startup-memory.js benchmark/run.js benchmark/settimeout.js benchmark/startup.js benchmark/static_http_server.js benchmark/string_creation.js benchmark/throughput-child.js benchmark/throughput.js benchmark/timers.js benchmark/v8_bench.js common.gypi configure configure-gyp debian/NEWS debian/README.source debian/TODO debian/compat debian/control debian/control.in debian/gbp.conf debian/node-waf.1 debian/node-waf.bash-completion debian/nodejs-dev.bash-completion debian/nodejs-dev.dirs debian/nodejs-dev.install debian/nodejs-dev.manpages debian/nodejs-legacy.links debian/nodejs.README.Debian debian/nodejs.dirs debian/nodejs.doc-base debian/nodejs.docs debian/nodejs.install debian/nodejs.manpages debian/nodejs.postinst debian/nodejs.prerm debian/patches/1001_align_fast_buffers_8byte_boundary.patch debian/patches/2001_FHS_paths_for_nodejs.patch debian/patches/2002_build_without_libv8_debug.patch debian/patches/2003_rename_node_to_nodejs.patch debian/patches/2004_relax_failing_test.patch debian/patches/2005_expected_failing_tests.patch debian/patches/2006_use_system_libeio.patch debian/patches/2007_fix_use_shared_zlib.patch debian/patches/2008_fix_use_shared_cares.patch debian/patches/2009_fix_shared_ev.patch debian/patches/2011_enable_mipsel_build.patch debian/patches/2012_fix_v8_3_10.patch debian/patches/2013_waf_linkflags.patch debian/patches/series debian/source/format debian/watch deps/http_parser/.gitignore deps/http_parser/CONTRIBUTIONS deps/http_parser/Makefile deps/http_parser/README.md deps/http_parser/http_parser.gyp deps/uv/.gitignore deps/uv/.travis.yml deps/uv/README.md deps/uv/build/gcc_version.py deps/uv/common.gypi deps/uv/gyp_uv deps/uv/src/unix/eio/Changes deps/uv/src/unix/eio/Makefile.am deps/uv/src/unix/eio/autogen.sh deps/uv/src/unix/eio/config.h.in deps/uv/src/unix/eio/config_cygwin.h deps/uv/src/unix/eio/config_darwin.h deps/uv/src/unix/eio/config_freebsd.h deps/uv/src/unix/eio/config_linux.h deps/uv/src/unix/eio/config_netbsd.h deps/uv/src/unix/eio/config_openbsd.h deps/uv/src/unix/eio/config_sunos.h deps/uv/src/unix/eio/configure.ac deps/uv/src/unix/eio/demo.c deps/uv/src/unix/eio/eio.3 deps/uv/src/unix/eio/eio.pod deps/uv/src/unix/eio/libeio.m4 deps/uv/src/unix/eio/xthread.h deps/uv/src/unix/uv-eio.h deps/uv/uv.gyp deps/uv/vcbuild.bat deps/v8/.gitignore deps/v8/AUTHORS deps/v8/ChangeLog deps/v8/benchmarks/README.txt deps/v8/benchmarks/revisions.html deps/v8/benchmarks/run.html deps/v8/benchmarks/style.css deps/v8/build/README.txt deps/v8/tools/freebsd-tick-processor deps/v8/tools/gcmole/README deps/v8/tools/gyp/v8-node.gyp deps/v8/tools/linux-tick-processor deps/v8/tools/mac-nm deps/v8/tools/mac-tick-processor deps/v8/tools/oom_dump/README deps/v8/tools/visual_studio/README.txt deps/v8/tools/windows-tick-processor.bat doc/api/_toc.markdown doc/api/addons.markdown doc/api/all.markdown doc/api/api/_toc.json doc/api/api/addons.json doc/api/api/appendix_1.json doc/api/api/assert.json doc/api/api/assets/sh.css doc/api/api/assets/style.css doc/api/api/buffer.json doc/api/api/child_process.json doc/api/api/cluster.json doc/api/api/crypto.json doc/api/api/debugger.json doc/api/api/dgram.json doc/api/api/dns.json doc/api/api/documentation.json doc/api/api/events.json doc/api/api/fs.json doc/api/api/globals.json doc/api/api/http.json doc/api/api/https.json doc/api/api/index.json doc/api/api/modules.json doc/api/api/os.json doc/api/api/path.json doc/api/api/process.json doc/api/api/querystring.json doc/api/api/readline.json doc/api/api/repl.json doc/api/api/stdio.json doc/api/api/stream.json doc/api/api/string_decoder.json doc/api/api/synopsis.json doc/api/api/timers.json doc/api/api/tls.json doc/api/api/tty.json doc/api/api/url.json doc/api/api/util.json doc/api/api/vm.json doc/api/api/zlib.json doc/api/appendix_1.markdown doc/api/assert.markdown doc/api/buffer.markdown doc/api/child_process.markdown doc/api/cluster.markdown doc/api/crypto.markdown doc/api/debugger.markdown doc/api/dgram.markdown doc/api/dns.markdown doc/api/documentation.markdown doc/api/events.markdown doc/api/fs.markdown doc/api/globals.markdown doc/api/http.markdown doc/api/https.markdown doc/api/index.markdown doc/api/modules.markdown doc/api/os.markdown doc/api/path.markdown doc/api/process.markdown doc/api/querystring.markdown doc/api/readline.markdown doc/api/repl.markdown doc/api/stdio.markdown doc/api/stream.markdown doc/api/synopsis.markdown doc/api/timers.markdown doc/api/tls.markdown doc/api/tty.markdown doc/api/url.markdown doc/api/util.markdown doc/api/vm.markdown doc/api/zlib.markdown doc/api_assets/sh.css doc/api_assets/style.css doc/changelog-head.html doc/cla.html doc/favicon.ico doc/node.1 doc/pipe.css doc/sh.css doc/sh_javascript.min.js doc/sh_vim-dark.css doc/v0.4_announcement.html node.gyp src/macros.py src/v8constants.h test/CMakeLists.txt test/fixtures/agent.crt test/fixtures/agent.key test/fixtures/alice.crt test/fixtures/breakpoints.js test/fixtures/breakpoints_utf8.js test/fixtures/cert.pem test/fixtures/child-process-spawn-node.js test/fixtures/destroy-stdin.js test/fixtures/elipses.txt test/fixtures/fixture.ini test/fixtures/foafssl.crt test/fixtures/foafssl.key test/fixtures/foo test/fixtures/keys/Makefile test/fixtures/keys/agent1-cert.pem test/fixtures/keys/agent1-csr.pem test/fixtures/keys/agent1-key.pem test/fixtures/keys/agent1.cnf test/fixtures/keys/agent2-cert.pem test/fixtures/keys/agent2-csr.pem test/fixtures/keys/agent2-key.pem test/fixtures/keys/agent2.cnf test/fixtures/keys/agent3-cert.pem test/fixtures/keys/agent3-csr.pem test/fixtures/keys/agent3-key.pem test/fixtures/keys/agent3.cnf test/fixtures/keys/agent4-cert.pem test/fixtures/keys/agent4-csr.pem test/fixtures/keys/agent4-key.pem test/fixtures/keys/agent4.cnf test/fixtures/keys/ca1-cert.pem test/fixtures/keys/ca1-cert.srl test/fixtures/keys/ca1-key.pem test/fixtures/keys/ca1.cnf test/fixtures/keys/ca2-cert.pem test/fixtures/keys/ca2-cert.srl test/fixtures/keys/ca2-crl.pem test/fixtures/keys/ca2-database.txt test/fixtures/keys/ca2-key.pem test/fixtures/keys/ca2-serial test/fixtures/keys/ca2.cnf test/fixtures/module-load-order/file1 test/fixtures/module-load-order/file1.node test/fixtures/module-load-order/file1.reg test/fixtures/module-load-order/file1.reg2 test/fixtures/module-load-order/file2.node test/fixtures/module-load-order/file2.reg test/fixtures/module-load-order/file2.reg2 test/fixtures/module-load-order/file2/index.node test/fixtures/module-load-order/file2/index.reg test/fixtures/module-load-order/file2/index.reg2 test/fixtures/module-load-order/file3.node test/fixtures/module-load-order/file3.reg test/fixtures/module-load-order/file3.reg2 test/fixtures/module-load-order/file3/index.node test/fixtures/module-load-order/file3/index.reg test/fixtures/module-load-order/file3/index.reg2 test/fixtures/module-load-order/file4.reg test/fixtures/module-load-order/file4.reg2 test/fixtures/module-load-order/file4/index.node test/fixtures/module-load-order/file4/index.reg test/fixtures/module-load-order/file4/index.reg2 test/fixtures/module-load-order/file5.reg2 test/fixtures/module-load-order/file5/index.node test/fixtures/module-load-order/file5/index.reg test/fixtures/module-load-order/file5/index.reg2 test/fixtures/module-load-order/file6/index.node test/fixtures/module-load-order/file6/index.reg test/fixtures/module-load-order/file6/index.reg2 test/fixtures/module-load-order/file7/index.node test/fixtures/module-load-order/file7/index.reg test/fixtures/module-load-order/file7/index.reg2 test/fixtures/module-load-order/file8/index.reg test/fixtures/module-load-order/file8/index.reg2 test/fixtures/module-load-order/file9/index.reg2 test/fixtures/module-require/child/index.js test/fixtures/module-require/child/node_modules/target.js test/fixtures/module-require/parent/index.js test/fixtures/module-require/parent/node_modules/target.js test/fixtures/msca.pem test/fixtures/packages/main-index/package.json test/fixtures/packages/main/package.json test/fixtures/pass-cert.pem test/fixtures/pass-csr.pem test/fixtures/pass-key.pem test/fixtures/registerExt.hello.world test/fixtures/registerExt.test test/fixtures/registerExt2.test test/fixtures/test_ca.pem test/fixtures/test_cert.pem test/fixtures/test_cert.pfx test/fixtures/test_dsa_params.pem test/fixtures/test_dsa_privkey.pem test/fixtures/test_dsa_pubkey.pem test/fixtures/test_key.pem test/fixtures/test_rsa_privkey.pem test/fixtures/test_rsa_privkey_2.pem test/fixtures/test_rsa_pubkey.pem test/fixtures/test_rsa_pubkey_2.pem test/fixtures/utf8-bom.js test/fixtures/utf8-bom.json test/fixtures/x.txt test/gc/test-http-client-connaborted.js test/gc/test-http-client-onerror.js test/gc/test-http-client-timeout.js test/gc/test-http-client.js test/gc/test-net-timeout.js test/internet/internet.status test/message/2100bytes.out test/message/hello_world.out test/message/stack_overflow.out test/message/throw_custom_error.out test/message/throw_non_error.out test/message/undefined_reference_in_new_context.out test/pummel/pummel.status test/simple/simple.status test/simple/test-fs-non-number-arguments-throw.js test/simple/test-http-parser-bad-ref.js tools/build-changelog.sh tools/changelog-head.sh tools/doc/README.md tools/doc/node_modules/marked/.npmignore tools/doc/node_modules/marked/Makefile tools/doc/node_modules/marked/index.js tools/doc/node_modules/marked/package.json tools/doc/package.json tools/email-footer.md tools/getnodeversion.py tools/gyp_node tools/license2rtf.js tools/msvs/msi/nodemsi.sln tools/msvs/msi/nodemsi.wixproj tools/msvs/msi/product.wxs tools/msvs/npm/npmrc tools/node-waf tools/osx-pkg-postinstall.sh tools/osx-pkg.pmdoc/01local-contents.xml tools/osx-pkg.pmdoc/01local.xml tools/osx-pkg.pmdoc/02npm-contents.xml tools/osx-pkg.pmdoc/02npm.xml tools/osx-pkg.pmdoc/index.xml tools/updateAuthors.awk tools/wafadmin/Build.py tools/wafadmin/Configure.py tools/wafadmin/Constants.py tools/wafadmin/Environment.py tools/wafadmin/Logs.py tools/wafadmin/Node.py tools/wafadmin/Options.py tools/wafadmin/Runner.py tools/wafadmin/Scripting.py tools/wafadmin/Task.py tools/wafadmin/TaskGen.py tools/wafadmin/Tools/__init__.py tools/wafadmin/Tools/ar.py tools/wafadmin/Tools/cc.py tools/wafadmin/Tools/ccroot.py tools/wafadmin/Tools/compiler_cc.py tools/wafadmin/Tools/compiler_cxx.py tools/wafadmin/Tools/compiler_d.py tools/wafadmin/Tools/config_c.py tools/wafadmin/Tools/cxx.py tools/wafadmin/Tools/d.py tools/wafadmin/Tools/dmd.py tools/wafadmin/Tools/gas.py tools/wafadmin/Tools/gcc.py tools/wafadmin/Tools/gdc.py tools/wafadmin/Tools/gnu_dirs.py tools/wafadmin/Tools/gob2.py tools/wafadmin/Tools/gxx.py tools/wafadmin/Tools/icc.py tools/wafadmin/Tools/icpc.py tools/wafadmin/Tools/intltool.py tools/wafadmin/Tools/libtool.py tools/wafadmin/Tools/misc.py tools/wafadmin/Tools/nasm.py tools/wafadmin/Tools/node_addon.py tools/wafadmin/Tools/osx.py tools/wafadmin/Tools/preproc.py tools/wafadmin/Tools/python.py tools/wafadmin/Tools/suncc.py tools/wafadmin/Tools/suncxx.py tools/wafadmin/Tools/unittestw.py tools/wafadmin/Tools/winres.py tools/wafadmin/Tools/xlc.py tools/wafadmin/Tools/xlcxx.py tools/wafadmin/Utils.py tools/wafadmin/__init__.py tools/wafadmin/ansiterm.py tools/wafadmin/py3kfixes.py vcbuild.bat Copyright: *No copyright* License: UNKNOWN FIXME Files: deps/http_parser/LICENSE-MIT deps/http_parser/http_parser.h deps/http_parser/test.c deps/uv/Makefile deps/uv/config-mingw.mk deps/uv/config-unix.mk deps/uv/include/uv-private/uv-unix.h deps/uv/include/uv-private/uv-win.h deps/uv/include/uv.h deps/uv/src/unix/cares.c deps/uv/src/unix/core.c deps/uv/src/unix/cygwin.c deps/uv/src/unix/darwin.c deps/uv/src/unix/dl.c deps/uv/src/unix/error.c deps/uv/src/unix/freebsd.c deps/uv/src/unix/fs.c deps/uv/src/unix/internal.h deps/uv/src/unix/kqueue.c deps/uv/src/unix/linux.c deps/uv/src/unix/netbsd.c deps/uv/src/unix/openbsd.c deps/uv/src/unix/pipe.c deps/uv/src/unix/process.c deps/uv/src/unix/stream.c deps/uv/src/unix/sunos.c deps/uv/src/unix/tcp.c deps/uv/src/unix/tty.c deps/uv/src/unix/udp.c deps/uv/src/unix/uv-eio.c deps/uv/src/uv-common.c deps/uv/src/uv-common.h deps/uv/src/win/async.c deps/uv/src/win/cares.c deps/uv/src/win/core.c deps/uv/src/win/dl.c deps/uv/src/win/error.c deps/uv/src/win/fs-event.c deps/uv/src/win/fs.c deps/uv/src/win/getaddrinfo.c deps/uv/src/win/handle.c deps/uv/src/win/internal.h deps/uv/src/win/loop-watcher.c deps/uv/src/win/pipe.c deps/uv/src/win/process.c deps/uv/src/win/req.c deps/uv/src/win/stream.c deps/uv/src/win/tcp.c deps/uv/src/win/threadpool.c deps/uv/src/win/threads.c deps/uv/src/win/timer.c deps/uv/src/win/tty.c deps/uv/src/win/udp.c deps/uv/src/win/util.c deps/uv/src/win/winapi.c deps/uv/src/win/winapi.h deps/uv/src/win/winsock.c deps/uv/src/win/winsock.h deps/uv/test/benchmark-ares.c deps/uv/test/benchmark-getaddrinfo.c deps/uv/test/benchmark-list.h deps/uv/test/benchmark-ping-pongs.c deps/uv/test/benchmark-pound.c deps/uv/test/benchmark-pump.c deps/uv/test/benchmark-sizes.c deps/uv/test/benchmark-spawn.c deps/uv/test/benchmark-tcp-write-batch.c deps/uv/test/benchmark-udp-packet-storm.c deps/uv/test/blackhole-server.c deps/uv/test/dns-server.c deps/uv/test/echo-server.c deps/uv/test/run-benchmarks.c deps/uv/test/run-tests.c deps/uv/test/runner-unix.c deps/uv/test/runner-unix.h deps/uv/test/runner-win.c deps/uv/test/runner-win.h deps/uv/test/runner.c deps/uv/test/runner.h deps/uv/test/task.h deps/uv/test/test-async.c deps/uv/test/test-callback-stack.c deps/uv/test/test-connection-fail.c deps/uv/test/test-counters-init.c deps/uv/test/test-cwd-and-chdir.c deps/uv/test/test-delayed-accept.c deps/uv/test/test-error.c deps/uv/test/test-fail-always.c deps/uv/test/test-fs-event.c deps/uv/test/test-fs.c deps/uv/test/test-get-currentexe.c deps/uv/test/test-get-loadavg.c deps/uv/test/test-get-memory.c deps/uv/test/test-getaddrinfo.c deps/uv/test/test-gethostbyname.c deps/uv/test/test-getsockname.c deps/uv/test/test-hrtime.c deps/uv/test/test-idle.c deps/uv/test/test-ipc.c deps/uv/test/test-list.h deps/uv/test/test-loop-handles.c deps/uv/test/test-multiple-listen.c deps/uv/test/test-pass-always.c deps/uv/test/test-ping-pong.c deps/uv/test/test-pipe-bind-error.c deps/uv/test/test-pipe-connect-error.c deps/uv/test/test-ref.c deps/uv/test/test-shutdown-close.c deps/uv/test/test-shutdown-eof.c deps/uv/test/test-spawn.c deps/uv/test/test-stdio-over-pipes.c deps/uv/test/test-tcp-bind-error.c deps/uv/test/test-tcp-bind6-error.c deps/uv/test/test-tcp-close.c deps/uv/test/test-tcp-connect-error.c deps/uv/test/test-tcp-connect6-error.c deps/uv/test/test-tcp-flags.c deps/uv/test/test-tcp-write-error.c deps/uv/test/test-tcp-write-to-half-open-connection.c deps/uv/test/test-tcp-writealot.c deps/uv/test/test-threadpool.c deps/uv/test/test-timer-again.c deps/uv/test/test-timer.c deps/uv/test/test-tty.c deps/uv/test/test-udp-dgram-too-big.c deps/uv/test/test-udp-ipv6.c deps/uv/test/test-udp-multicast-join.c deps/uv/test/test-udp-multicast-ttl.c deps/uv/test/test-udp-options.c deps/uv/test/test-udp-send-and-recv.c tools/doc/LICENSE Copyright: HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER Joyent, Inc. and other Node contributors. License: MIT/X11 (BSD like) FIXME Files: doc/api/api/_toc.html doc/api/api/addons.html doc/api/api/appendix_1.html doc/api/api/assert.html doc/api/api/buffer.html doc/api/api/cluster.html doc/api/api/crypto.html doc/api/api/debugger.html doc/api/api/dgram.html doc/api/api/dns.html doc/api/api/documentation.html doc/api/api/events.html doc/api/api/fs.html doc/api/api/globals.html doc/api/api/http.html doc/api/api/https.html doc/api/api/index.html doc/api/api/modules.html doc/api/api/os.html doc/api/api/path.html doc/api/api/process.html doc/api/api/querystring.html doc/api/api/readline.html doc/api/api/repl.html doc/api/api/stdio.html doc/api/api/stream.html doc/api/api/string_decoder.html doc/api/api/synopsis.html doc/api/api/timers.html doc/api/api/tls.html doc/api/api/tty.html doc/api/api/url.html doc/api/api/util.html doc/api/api/vm.html doc/api/api/zlib.html Copyright: Joyent, Inc, Node.js is a trademark of Joyent, Inc. View license.

License: UNKNOWN FIXME Files: deps/v8/src/assembler.cc deps/v8/src/assembler.h deps/v8/src/ia32/assembler-ia32-inl.h deps/v8/src/ia32/assembler-ia32.h deps/v8/src/mips/assembler-mips-inl.h deps/v8/src/mips/assembler-mips.cc deps/v8/src/mips/assembler-mips.h deps/v8/src/x64/assembler-x64.h Copyright: 1994-2006, Sun Microsystems Inc 2011, Sun Microsystems Inc 2011, the V8 project authors. HOLDERS AND CONTRIBUTORS "AS OWNER OR License: BSD (2 clause) FIXME Files: doc/about/index.html doc/changelog-foot.html doc/community/index.html doc/index.html doc/template.html Copyright: Joyent, Inc, Node.js is a trademark of Joyent, Inc. View license.

License: UNKNOWN FIXME Files: deps/v8/src/arm/assembler-arm-inl.h deps/v8/src/arm/assembler-arm.cc deps/v8/src/arm/assembler-arm.h deps/v8/src/ia32/assembler-ia32.cc Copyright: 1994-2006, Sun Microsystems Inc 2011, the V8 project authors. 2012, the V8 project authors. HOLDERS AND CONTRIBUTORS OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT License: BSD (2 clause) FIXME Files: tools/doc/node_modules/.bin/marked tools/doc/node_modules/marked/bin/marked tools/doc/node_modules/marked/man/marked.1 Copyright: 2011-2012, Christopher Jeffrey (MIT License) License: UNKNOWN FIXME Files: deps/v8/src/extensions/experimental/i18n-js2c.py deps/v8/tools/js2c.py Copyright: 2006-2008, the V8 project authors. 2011, Google Inc. 2011, the V8 project authors. HOLDERS AND CONTRIBUTORS License: BSD (3 clause) FIXME Files: deps/v8/tools/test.py tools/test.py Copyright: 2008, the V8 project authors. / HOLDERS AND CONTRIBUTORS License: BSD (3 clause) FIXME Files: deps/v8/LICENSE.valgrind deps/v8/src/third_party/valgrind/valgrind.h Copyright: 2000-2007, Julian Seward. 2000-2010, Julian Seward. License: BSD (3 clause) FIXME Files: src/v8_typed_array.cc src/v8_typed_array.h Copyright: Dean McNamee , 2011, HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER License: MIT/X11 (BSD like) FIXME Files: test/fixtures/fork2.js test/fixtures/sample.png Copyright: License: UNKNOWN FIXME Files: doc/api/api/all.html doc/api/api/net.html Copyright: Joyent, Inc, Node.js is a trademark of Joyent, Inc. View license.

{ //'connection' listener License: UNKNOWN FIXME Files: deps/uv/.mailmap deps/uv/AUTHORS Copyright: License: UNKNOWN FIXME Files: deps/v8/tools/gcmole/gccause.lua deps/v8/tools/gcmole/gcmole.lua Copyright: 2011, the V8 project authors. HOLDERS AND CONTRIBUTORS License: UNKNOWN FIXME Files: deps/uv/include/uv-private/eio.h deps/uv/src/unix/eio/eio.c Copyright: 2007-2011, Marc Alexander Lehmann License: UNKNOWN FIXME Files: doc/api/api/all.json doc/api/api/net.json Copyright: { //'connection' listener\n console.log('server connected');\n c.on('end', function() {\n console.log('server disconnected');\n });\n c.write('hello\\r\\n');\n c.pipe;\n});\nserver.listen(8124, function() { //'listening' listener\n console.log('server bound');\n});\n

Test this by using telnet:\n\n

\n
telnet localhost 8124
\n

To listen on the socket /tmp/echo.sock the third line from the last would\njust be changed to\n\n

\n
server.listen('/tmp/echo.sock', function() { //'listening' listener
\n

Use nc to connect to a UNIX domain socket server:\n\n

\n
nc -U /tmp/echo.sock
\n" License: UNKNOWN FIXME Files: deps/uv/src/unix/eio/LICENSE Copyright: 2007-2008, Marc Alexander Lehmann HOLDERS AND CONTRIBUTORS License: BSD (2 clause) FIXME Files: deps/v8/LICENSE.strongtalk Copyright: 1994-2006, Sun Microsystems Inc HOLDERS AND CONTRIBUTORS "AS OWNER OR License: BSD (2 clause) FIXME Files: deps/v8/tools/presubmit.py Copyright: License: BSD (3 clause) FIXME Files: deps/v8/src/scanner.cc Copyright: && IsCarriageReturn(c0_)) Advance(); && IsLineFeed(c0_)) Advance(); 2011, the V8 project authors. HOLDERS AND CONTRIBUTORS License: BSD (3 clause) FIXME Files: deps/v8/src/runtime.cc Copyright: * kJsonQuotesCharactersPerEntry; 2011, the V8 project authors. >= kQuoteTableLength) { HOLDERS AND CONTRIBUTORS || c == 0x200b; License: BSD (3 clause) FIXME Files: tools/waf-light Copyright: *No copyright* License: BSD (3 clause) FIXME Files: deps/v8/src/scanner.h Copyright: 2011, the V8 project authors. <= 5) return c + 10; <= 9) return c; HOLDERS AND CONTRIBUTORS License: BSD (3 clause) FIXME Files: lib/buffer_ieee754.js Copyright: 2008, Fair Oaks Labs, Inc HOLDERS AND CONTRIBUTORS "AS IS" OWNER OR CONTRIBUTORS BE License: BSD (3 clause) FIXME Files: src/platform_darwin_proctitle.cc Copyright: 2010, Google Inc HOLDERS AND CONTRIBUTORS License: BSD (3 clause) FIXME Files: tools/cpplint.py Copyright: 2009, Google Inc. HOLDERS AND CONTRIBUTORS [year message found. ' License: BSD (3 clause) FIXME Files: deps/v8/src/hydrogen.cc Copyright: 2011, the V8 project authors. HOLDERS AND CONTRIBUTORS Reachable only normally License: BSD (3 clause) FIXME Files: deps/v8/src/char-predicates-inl.h Copyright: 2006-2008, the V8 project authors. HOLDERS AND CONTRIBUTORS || IsInRange(AsciiAlphaToLower, 'a', 'f'); License: BSD (3 clause) FIXME Files: deps/uv/src/unix/eio/aclocal.m4 Copyright: 1996, 1998, 2000-2005, 2008 1996-1997, 2000-2001, 2003, 2005, 2008 1996-2001, 2003-2005 1996-2004, 1997, 1999-2001, 2003-2005, 2008 1997, 2000-2001, 2003-2006, 2008 1999-2005, 2008 1999-2006, 2009 2001, 2003, 2005, 2008 Free Software Foundation, Inc 2001, 2003, 2005, Free Software Foundation, Inc 2001-2003, 2005, 2008, Free Software Foundation, Inc 2001-2003, 2005, 2009, Free Software Foundation, Inc 2002-2003, 2005-2008, Free Software Foundation, Inc 2003, 2005 Free Software Foundation, Inc 2003-2006, Free Software Foundation, Inc 2004, Free Software Foundation, Inc 2004-2005, 2007 Free Software Foundation, Inc 2004-2005, 2007-2008, Free Software Foundation, Inc 2004-2005, Free Software Foundation, Inc 2006, 2008 Free Software Foundation, Inc 2008, Free Software Foundation, Inc License: GPL-2+ FIXME Files: deps/v8/benchmarks/deltablue.js Copyright: 1996, John Maloney and Mario Wolczko 2008, the V8 project authors. License: GPL-2+ FIXME Files: deps/http_parser/http_parser.c Copyright: & 0x80)) (IS_ALPHANUM || == '.' || == '-') (tokens[(unsigned char)c License: MIT/X11 (BSD like) FIXME Files: src/node_crypto.cc Copyright: ( <= '9' ? ( - '0') : <= 'Z' ? ( - 'A' + 10) \ - 'a' + 10)) HOLDERS BE LIABLE FOR ANY CLAIM Joyent, Inc. and other Node contributors License: MIT/X11 (BSD like) FIXME Files: test/simple/test-punycode.js Copyright: 2011, Ben Noordhuis Chinese (traditional) HOLDERS BE LIABLE FOR ANY CLAIM HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER Joyent, Inc. and other Node contributors License: MIT/X11 (BSD like) FIXME Files: tools/doc/node_modules/marked/LICENSE Copyright: 2011-2012, Christopher Jeffrey (https://github.com/chjj/) HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER License: MIT/X11 (BSD like) FIXME Files: deps/uv/LICENSE Copyright: Daniel Stenberg and others. MIT licensed HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER Igor Sysoev. Two clause BSD license Joyent, Inc. and other Node contributors. Marc Alexander Lehmann, and Niels Provos. Two clause BSD license License: MIT/X11 (BSD like) FIXME Files: tools/msvs/res/node.rc Copyright: HOLDERS BE LIABLE FOR ANY CLAIM Joyent, Inc. and other Node contributors Joyent, Inc. and other Node contributors. MIT license." License: MIT/X11 (BSD like) FIXME Files: test/simple/test-url.js Copyright: 2002-2008, Kris Kowal HOLDERS BE LIABLE FOR ANY CLAIM Joyent, Inc. and other Node contributors License: MIT/X11 (BSD like) FIXME Files: test/simple/test-zlib.js Copyright: HOLDERS BE LIABLE FOR ANY CLAIM Joyent, Inc. and other Node contributors this.write; License: MIT/X11 (BSD like) FIXME Files: test/disabled/test-child-process-uid-gid.js Copyright: HOLDERS BE LIABLE FOR ANY CLAIM Joyent, Inc. and other Node contributors { this.buf += c; } License: MIT/X11 (BSD like) FIXME Files: test/simple/test-http-chunked.js Copyright: HOLDERS BE LIABLE FOR ANY CLAIM Joyent, Inc. and other Node contributors {data += c}); License: MIT/X11 (BSD like) FIXME Files: lib/assert.js Copyright: 2009, Thomas Robinson <280north.com> License: MIT/X11 (BSD like) FIXME Files: deps/v8/benchmarks/crypto.js Copyright: 2003-2005, Tom Wu 2005, Tom Wu License: MIT/X11 (BSD like) FIXME Files: deps/v8/benchmarks/v8-logo.png Copyright: $91u蒳a () 2011, Emanuele Giaquinta License: UNKNOWN FIXME Files: src/v8ustack.d Copyright: (this->buf[this->off++ License: UNKNOWN FIXME Files: debian/patches/1002_upstream_forgot_to_build_doc.patch Copyright: Joyent, Inc, Node.js is a trademark of Joyent, Inc. View license.

Joyent, Inc, Node.js is a trademark of Joyent, Inc. View license.

{ //'connection' listener { //'connection' listener\n console.log('server connected');\n c.on('end', function() {\n console.log('server disconnected');\n });\n c.write('hello\\r\\n');\n c.pipe;\n});\nserver.listen(8124, function() { //'listening' listener\n console.log('server bound');\n});\n

Test this by using telnet:\n\n

\n
telnet localhost 8124
\n

To listen on the socket /tmp/echo.sock the third line from the last would\njust be changed to\n\n

\n
server.listen('/tmp/echo.sock', function() { //'listening' listener
\n

Use nc to connect to a UNIX domain socket server:\n\n

\n
nc -U /tmp/echo.sock
\n" License: UNKNOWN FIXME Files: doc/api/api/child_process.html Copyright: Joyent, Inc, Node.js is a trademark of Joyent, Inc. View license.

License: UNKNOWN FIXME Files: doc/logos/index.html Copyright: Joyent, Inc., Node.js is a trademark of Joyent, Inc., View License

License: UNKNOWN FIXME Files: tools/doc/node_modules/marked/README.md Copyright: 2011-2012, Christopher Jeffrey. (MIT License) License: UNKNOWN FIXME Files: tools/doc/node_modules/marked/lib/marked.js Copyright: 2011-2012, Christopher Jeffrey. (MIT Licensed) License: UNKNOWN FIXME Files: deps/v8/tools/generate-ten-powers.scm Copyright: 2010, the V8 project authors. 2010, the V8 project authors.") HOLDERS AND CONTRIBUTORS License: UNKNOWN FIXME Files: deps/uv/include/uv-private/ngx-queue.h Copyright: Igor Sysoev License: UNKNOWN FIXME Files: lib/punycode.js Copyright: 2011, Mathias Bynens License: UNKNOWN FIXME Files: tools/wafadmin/pproc.py Copyright: 2003-2005, Peter Astrand License: UNKNOWN FIXME Files: deps/v8/benchmarks/raytrace.js Copyright: 2005-2007, Sam Stephenson License: UNKNOWN FIXME Files: doc/sh_main.js Copyright: 2007-2008, gnombat@users.sourceforge.net License: UNKNOWN FIXME Files: debian/rules Copyright: maintenance License: UNKNOWN FIXME Files: deps/v8/build/all.gyp Copyright: 2011, the V8 project authors. License: UNKNOWN FIXME Files: test/fixtures/person.jpg Copyright: uz3@VnyI'D: [ehitI&JH,XyZܠD ܭ0 z5mXRysMcu)FI<*Ze%HfU@Z׷Г License: UNKNOWN FIXME Files: doc/api/net.markdown Copyright: { //'connection' listener License: UNKNOWN FIXME Files: test/fixtures/person.jpg.gz Copyright: h$Hn'hdv«y\\7"?pY0q bN_LgX|%*cmB+hkhR5jzH!*JVNp0nDB.d4˻@0֘6wɃq=HM@\c`=cj$~|_M(UQߑ&۰mӫѹ `\݅bU&NE License: UNKNOWN FIXME Files: LICENSE Copyright: 1995-2010, Jean-loup Gailly and Mark Adler 1998, the Massachusetts Institute of Technology 1998-2011, The OpenSSL Project. 2006-2012, the V8 project authors. 2007, Google Inc 2007-2008, Marc Alexander Lehmann 2007-2009, Marc Alexander Lehmann 2008, Fair Oaks Labs, Inc 2009, Google Inc. 2009-2012, Isaac Z. Schlueter (the "Original Author") 2010, James Halliday 2010, Robert Kieffer 2011, Mathias Bynens 2011, Mikeal Rogers 2011-2012, Christopher Jeffrey (https://github.com/chjj/) HOLDERS AND CONTRIBUTORS HOLDERS AND CONTRIBUTORS "AS IS" HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER Joyent, Inc. and other Node contributors. OWNER OR CONTRIBUTORS BE Thomas Nagy, 2005-2011, License: zlib/libpng BSD (4 clause) MIT/X11 (BSD like) FIXME debian/copyright0000644000000000000000000007254612004014454011131 0ustar Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Upstream-Name: Node Source: http://nodejs.org/ Upstream-Contact: https://github.com/joyent/node/issues Files: * Copyright: Joyent, Inc. and other Node contributors. License: Expat Files: deps/http_parser/* Copyright: Igor Sysoev, Joyent, Inc. and other Node contributors. License: Expat Files: deps/uv/include/uv-private/ngx-queue.h Copyright: Igor Sysoev License: Expat Files: deps/uv/src/unix/eio/* Copyright: 2007-2011, Marc Alexander Lehmann License: BSD-2-clause~author or GPL-2+ Alternatively, the contents of this package may be used under the terms of the GNU General Public License ("GPL") version 2 or any later version, in which case the provisions of the GPL are applicable instead of the above. If you wish to allow the use of your version of this package only under the terms of the GPL and not to allow others to use your version of this file under the BSD license, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the GPL in this and the other files of this package. If you do not delete the provisions above, a recipient may use your version of this file under either the BSD or the GPL. Files: deps/v8/* tools/test.py tools/js2c.py test/simple/testcfg.py test/pummel/testcfg.py test/message/testcfg.py test/internet/testcfg.py test/gc/testcfg.py Copyright: 2006-2011, the V8 Project Authors License: BSD-3-clause~Google Files: deps/v8/benchmarks/crypto.js Copyright: 2003-2005 Tom Wu License: Expat~Wu Files: deps/v8/benchmark/deltablue.js Copyright: 1996 John Maloney and Mario Wolczko 2008 the V8 project authors License: GPL-2+ Files: deps/v8/src/arm/assembler-arm* deps/v8/src/assembler.* deps/v8/src/ia32/assembler-ia32* deps/v8/src/mips/assembler-mips* deps/v8/src/x64/assembler-x64.h Copyright: 1994-2006, Sun Microsystems Inc. 2006-2011, the V8 Project Authors License: BSD-3-clause~Sun Files: deps/v8/src/third-party/dtoa/* Copyright: 1991, 2000, 2001 by David M. Gay at Lucent Technologies License: OpenBSD~Lucent Files: deps/v8/src/third-party/valgrind/valgrind.h Copyright: 2000-2007, Julian Seward License: BSD-4-clause~author Files: doc/sh_main.js doc/sh_javascript.min.js doc/sh.css doc/sh_vim-dark.css Copyright: 2007, 2008 gnombat@users.sourceforge.net License: GPL-3 Files: lib/assert.js Copyright: 2009 Thomas Robinson <280north.com> License: Expat Files: lib/buffer_ieee754.js Copyright: 2008 Fair Oaks Labs, Inc. License: BSD-3-clause~FairOaksLabs Files: lib/punycode.js Copyright: 2011 Mathias Bynens License: Expat Files: tools/doc/node_modules/marked/* Copyright: 2011-2012, Christopher Jeffrey (https://github.com/chjj/) License: Expat Files: tools/waf-light tools/wafadmin/* Copyright: 2003-2005, Peter Astrand 2005-2009, Thomas Nagy 2005, Scott Newton 2006-2007, Carlos Rafael Giani 2006, John O'Meara 2006, Ralf Habacker 2007-2008, Matthias Jahn 2007, Ali Sabil 2007, Anders Waldenborg 2007, Brant Young 2007, Gustavo Carneiro 2007, Tamas Pal 2008-2009, Yinon Ehrlich 2008, Bjoern Michaelsen 2008, Luca Fossati 2008, Ruediger Sonderfeld 2008, Sebastian Schlingmann 2008, Stian Selnes 2009, Nicolas Mercier License: BSD-3-clause~author Files: tools/wafadmin/pproc.py Copyright: (c) 2003-2005 by Peter Astrand License: Python-CNRI Files: src/platform_darwin_proctitle.cc tools/cpplint.py Copyright: 2007,2009-2010, Google Inc. License: BSD-3-clause~Google Files: debian/* Copyright: 2009-2010 Jérémy Lal License: Expat License: Expat Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: . The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. . THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. License: Expat~Wu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: . The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. . THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. . IN NO EVENT SHALL TOM WU BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. . In addition, the following condition applies: . All redistributions must retain an intact copy of this copyright notice and disclaimer. License: BSD-2-clause~author Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: . 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. . 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. . THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. License: BSD-3-clause~Google Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: . * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Google Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. . THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. License: BSD-3-clause~Sun Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: . - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - Redistribution in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. - Neither the name of Sun Microsystems or the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission. . THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. License: BSD-3-clause~author Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: . 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. . 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. . 3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. . THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. License: BSD-3-clause~FairOaksLabs Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: . * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. . * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. . * Neither the name of Fair Oaks Labs, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. . THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. License: BSD-4-clause~author Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: . 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. . 2. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. . 3. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. . 4. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. . THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. License: OpenBSD~Lucent Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software. . THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENT MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. License: GPL-2+ This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. On Debian GNU/Linux systems, the complete text of the GNU General Public License can be found in `/usr/share/common-licenses/GPL-2' License: GPL-3 This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. On Debian GNU/Linux systems, the complete text of the GNU General Public License can be found in `/usr/share/common-licenses/GPL-3' License: Python-CNRI Licensed to PSF under a Contributor Agreement and distributed under the Python License. . A. HISTORY OF THE SOFTWARE ========================== . Python was created in the early 1990s by Guido van Rossum at Stichting Mathematisch Centrum (CWI, see http://www.cwi.nl) in the Netherlands as a successor of a language called ABC. Guido remains Python's principal author, although it includes many contributions from others. . In 1995, Guido continued his work on Python at the Corporation for National Research Initiatives (CNRI, see http://www.cnri.reston.va.us) in Reston, Virginia where he released several versions of the software. . In May 2000, Guido and the Python core development team moved to BeOpen.com to form the BeOpen PythonLabs team. In October of the same year, the PythonLabs team moved to Digital Creations (now Zope Corporation, see http://www.zope.com). In 2001, the Python Software Foundation (PSF, see http://www.python.org/psf/) was formed, a non-profit organization created specifically to own Python-related Intellectual Property. Zope Corporation is a sponsoring member of the PSF. . All Python releases are Open Source (see http://www.opensource.org for the Open Source Definition). Historically, most, but not all, Python releases have also been GPL-compatible; the table below summarizes the various releases. . Release Derived Year Owner GPL- from compatible? (1) . 0.9.0 thru 1.2 1991-1995 CWI yes 1.3 thru 1.5.2 1.2 1995-1999 CNRI yes 1.6 1.5.2 2000 CNRI no 2.0 1.6 2000 BeOpen.com no 1.6.1 1.6 2001 CNRI yes (2) 2.1 2.0+1.6.1 2001 PSF no 2.0.1 2.0+1.6.1 2001 PSF yes 2.1.1 2.1+2.0.1 2001 PSF yes 2.2 2.1.1 2001 PSF yes 2.1.2 2.1.1 2002 PSF yes 2.1.3 2.1.2 2002 PSF yes 2.2.1 2.2 2002 PSF yes 2.2.2 2.2.1 2002 PSF yes 2.2.3 2.2.2 2003 PSF yes 2.3 2.2.2 2002-2003 PSF yes 2.3.1 2.3 2002-2003 PSF yes 2.3.2 2.3.1 2002-2003 PSF yes 2.3.3 2.3.2 2002-2003 PSF yes 2.3.4 2.3.3 2004 PSF yes 2.3.5 2.3.4 2005 PSF yes 2.4 2.3 2004 PSF yes 2.4.1 2.4 2005 PSF yes 2.4.2 2.4.1 2005 PSF yes 2.4.3 2.4.2 2006 PSF yes 2.5 2.4 2006 PSF yes . Footnotes: . (1) GPL-compatible doesn't mean that we're distributing Python under the GPL. All Python licenses, unlike the GPL, let you distribute a modified version without making your changes open source. The GPL-compatible licenses make it possible to combine Python with other software that is released under the GPL; the others don't. . (2) According to Richard Stallman, 1.6.1 is not GPL-compatible, because its license has a choice of law clause. According to CNRI, however, Stallman's lawyer has told CNRI's lawyer that 1.6.1 is "not incompatible" with the GPL. . Thanks to the many outside volunteers who have worked under Guido's direction to make these releases possible. . . B. TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING PYTHON =============================================================== . PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 -------------------------------------------- . 1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and the Individual or Organization ("Licensee") accessing and otherwise using this software ("Python") in source or binary form and its associated documentation. . 2. Subject to the terms and conditions of this License Agreement, PSF hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of copyright, i.e., "Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006 Python Software Foundation; All Rights Reserved" are retained in Python alone or in any derivative version prepared by Licensee. . 3. In the event Licensee prepares a derivative work that is based on or incorporates Python or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python. . 4. PSF is making Python available to Licensee on an "AS IS" basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. . 5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. . 6. This License Agreement will automatically terminate upon a material breach of its terms and conditions. . 7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between PSF and Licensee. This License Agreement does not grant permission to use PSF trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party. . 8. By copying, installing or otherwise using Python, Licensee agrees to be bound by the terms and conditions of this License Agreement. . . BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0 ------------------------------------------- . BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1 . 1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization ("Licensee") accessing and otherwise using this software in source or binary form and its associated documentation ("the Software"). . 2. Subject to the terms and conditions of this BeOpen Python License Agreement, BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use the Software alone or in any derivative version, provided, however, that the BeOpen Python License is retained in the Software, alone or in any derivative version prepared by Licensee. . 3. BeOpen is making the Software available to Licensee on an "AS IS" basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. . 4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. . 5. This License Agreement will automatically terminate upon a material breach of its terms and conditions. . 6. This License Agreement shall be governed by and interpreted in all respects by the law of the State of California, excluding conflict of law provisions. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between BeOpen and Licensee. This License Agreement does not grant permission to use BeOpen trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party. As an exception, the "BeOpen Python" logos available at http://www.pythonlabs.com/logos.html may be used according to the permissions granted on that web page. . 7. By copying, installing or otherwise using the software, Licensee agrees to be bound by the terms and conditions of this License Agreement. . . CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1 --------------------------------------- . 1. This LICENSE AGREEMENT is between the Corporation for National Research Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191 ("CNRI"), and the Individual or Organization ("Licensee") accessing and otherwise using Python 1.6.1 software in source or binary form and its associated documentation. . 2. Subject to the terms and conditions of this License Agreement, CNRI hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python 1.6.1 alone or in any derivative version, provided, however, that CNRI's License Agreement and CNRI's notice of copyright, i.e., "Copyright (c) 1995-2001 Corporation for National Research Initiatives; All Rights Reserved" are retained in Python 1.6.1 alone or in any derivative version prepared by Licensee. Alternately, in lieu of CNRI's License Agreement, Licensee may substitute the following text (omitting the quotes): "Python 1.6.1 is made available subject to the terms and conditions in CNRI's License Agreement. This Agreement together with Python 1.6.1 may be located on the Internet using the following unique, persistent identifier (known as a handle): 1895.22/1013. This Agreement may also be obtained from a proxy server on the Internet using the following URL: http://hdl.handle.net/1895.22/1013". . 3. In the event Licensee prepares a derivative work that is based on or incorporates Python 1.6.1 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to Python 1.6.1. . 4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS" basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. . 5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. . 6. This License Agreement will automatically terminate upon a material breach of its terms and conditions. . 7. This License Agreement shall be governed by the federal intellectual property law of the United States, including without limitation the federal copyright law, and, to the extent such U.S. federal law does not apply, by the law of the Commonwealth of Virginia, excluding Virginia's conflict of law provisions. Notwithstanding the foregoing, with regard to derivative works based on Python 1.6.1 that incorporate non-separable material that was previously distributed under the GNU General Public License (GPL), the law of the Commonwealth of Virginia shall govern this License Agreement only as to issues arising under or with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between CNRI and Licensee. This License Agreement does not grant permission to use CNRI trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party. . 8. By clicking on the "ACCEPT" button where indicated, or by copying, installing or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and conditions of this License Agreement. . ACCEPT . . CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2 -------------------------------------------------- . Copyright (c) 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The Netherlands. All rights reserved. . Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. . STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. debian/nodejs.manpages0000644000000000000000000000004512004014433012153 0ustar debian/tmp/usr/share/man/man1/node.1 debian/gbp.conf0000644000000000000000000000053212004014454010577 0ustar # Configuration file for git-buildpackage and friends [DEFAULT] # master and upstream branches are uploaded to unstable upstream-branch = upstream debian-branch = master # there are separate branches for stable and experimental #upstream-branch = upstream-experimental #debian-branch = master-experimental pristine-tar = True sign-tags = True debian/rules0000755000000000000000000000723412054744060010256 0ustar #!/usr/bin/make -f -include /usr/share/cdbs/1/rules/upstream-tarball.mk include /usr/share/cdbs/1/rules/utils.mk include /usr/share/cdbs/1/rules/debhelper.mk include /usr/share/cdbs/1/class/autotools.mk DEB_UPSTREAM_URL = http://nodejs.org/dist/v$(DEB_UPSTREAM_TARBALL_VERSION)/ DEB_UPSTREAM_TARBALL_BASENAME = node-v$(DEB_UPSTREAM_TARBALL_VERSION) DEB_UPSTREAM_WGET_OPTS += --no-check-certificate # ./deps/npm contains some non-DFSG files, repackaging is needed. # Conveniently, remove unused software to ease debian/copyright maintenance. DEB_UPSTREAM_REPACKAGE_EXCLUDES += \ ./deps/npm/ \ ./deps/openssl/ \ ./deps/zlib/ \ ./deps/uv/src/ares/ \ ./deps/uv/src/unix/ev/ \ ./deps/uv/include/ares*.h \ ./deps/uv/include/uv-private/ev.h \ ./deps/uv/include/uv-private/tree.h \ ./tools/scons/ \ ./tools/gyp/ \ ./tools/closure_linter/ DEB_UPSTREAM_REPACKAGE_TAG = $(shell echo $(DEB_UPSTREAM_VERSION) | egrep -o "dfsg[0-9]+") # Needed by upstream build bdeps = binutils, openssl (>= 1.0.0g), pkg-config, bash-completion bdeps += , curl, procps, zlib1g-dev # Needed by upstream build and binary development package deps = python,\ libv8-dev (>= 3.7),\ libssl-dev (>= 1.0.0g),\ libev-dev (>= 1:4.11),\ libc-ares-dev (>= 1.7.5) CDBS_BUILD_DEPENDS += , $(bdeps), $(deps) CDBS_DEPENDS_nodejs-dev = $(deps) CDBS_BREAKS_nodejs =\ buddycloud-server (<< 0.3.1-2),\ carto (<< 0.4.6+ds1-2~),\ coffeescript (<< 1.3.3-3~),\ node-bones (<< 2.0.1+ds1-3~),\ node-cli (<< 0.4.4~20120516-1~),\ node-express (<< 2.5.9-2~),\ node-get (<< 1.1.5+ds1-2~),\ node-jake (<< 0.2.32-2~),\ node-less (<< 1.3.0~20120310-3~),\ node-mapnik (<< 0.6.7-3~),\ node-mbtiles (<< 0.2.3-2~),\ node-optimist (<< 0.3.1-2~),\ node-semver (<< 1.0.13-2~),\ node-tilelive (<< 4.2.1-4~),\ node-uglify (<< 1.2.6-2~),\ node-vows (<< 0.6.3-2~),\ npm (<< 1.1.4~dfsg-2~) # suppress checking binary files, to not upset dpkg-source DEB_COPYRIGHT_CHECK_IGNORE_REGEX = ^(doc/trademark-policy\.pdf|doc/mac_osx_nodejs_installer_logo\.png|doc/.*-white-stripe\.jpg|favicon\.ico|debian/(changelog|copyright(|_hints|_newhints)))$ DEB_CONFIGURE_NORMAL_ARGS = "" DEB_CONFIGURE_EXTRA_FLAGS = --debug --without-npm --shared-v8 --shared-cares --shared-libev --shared-zlib --no-ssl2 DEB_CONFIGURE_SCRIPT_ENV += PREFIX="/usr" DEB_DESTDIR = $(CURDIR)/debian/tmp DEB_MAKE_CLEAN_TARGET = clean # * relax regression tests when targeted experimental suite exp-relax-check := $(if $(shell dpkg-parsechangelog | grep -x 'Distribution: \(experimental\|UNRELEASED\)'),-i) DEB_MAKE_CHECK_TARGET = $(exp-relax-check) test # properly clean files from build, waf, test, python clean:: rm -f node rm -f node_g rm -f .lock-wscript rm -rf build rm -f test/fixtures/hello.txt rm -rf test/tmp find . -name "*.pyc" -delete rm -rf out binary-post-install/nodejs:: mv debian/nodejs/usr/bin/node debian/nodejs/usr/bin/nodejs mv debian/nodejs/usr/share/man/man1/node.1 debian/nodejs/usr/share/man/man1/nodejs.1 # remove *.json files from documentation, remove google-analytics calls # TODO: when doc will be generated from markdown, remove it from doc/template.html binary-install/nodejs:: find debian/nodejs/usr/share/doc/nodejs -name *.json -delete sed -i -e '/document\.write/d' -e '/pageTracker/d' debian/nodejs/usr/share/doc/nodejs/api/*.html # we have completion for nodejs-waf install/nodejs-dev:: dh_bash-completion # Work around upstream shipping docs in wrong subdir pre-build:: debian/replace-items debian/replace-items: debian/stamp-copyright-check cp -at doc/api doc/api/api/* touch $@ binary-post-install/nodejs:: rm -rf debian/nodejs/usr/share/doc/nodejs/api/api clean:: rm -rf $(patsubst doc/api/api/%,doc/api/%,$(wildcard doc/api/api/*)) rm -f debian/replace-items debian/node-waf.10000644000000000000000000000151512004014433010741 0ustar .TH node-waf 1 "11 July 2010" . .SH NAME . node-waf - WAF helper for building node modules . .SH SYNOPSIS .B node-waf [\fICOMMAND\fR] . .SH DESCRIPTION .PP Helper for the waf build system that is included in nodejs-dev package. .P Typical usage is : \fInode-waf\fP \fBconfigure\fR \fBbuild\fR . .SH ENVIRONMENT VARIABLE .P \fBNODE_PATH\fR sets the path where the module is installed. This environment variable may be set when calling \fBconfigure\fR command. If $HOME is set, it defaults to $HOME/.node_libraries, else to /usr/lib/nodejs. . .SH COMMANDS .TP \fBdistclean\fR Removes all files created by \fInode-waf\fP. This may be useful when using a new node release. .TP \fBclean\fR .TP \fBconfigure\fR .TP \fBbuild\fR .TP \fBinstall\fR Install to NODE_PATH. .TP \fBuninstall\fR Uninstall module from NODE_PATH. . .SH "SEE ALSO" . .BR node(1) debian/nodejs.prerm0000644000000000000000000000016412004014454011512 0ustar #!/bin/sh set -e if [ "$1" = "remove" ]; then update-alternatives --remove js /usr/bin/nodejs fi #DEBHELPER# debian/nodejs.README.Debian0000644000000000000000000000210312004014454012476 0ustar nodejs for Debian ================= packaged modules ---------------- The global search path for modules is /usr/lib/nodejs Future packages of node modules will use that directory, so it should be used wisely. user modules ------------ Node looks for modules in ./node_modules directory first; please read node#modules documentation carefully for more information. Node does not look for modules in /usr/local/lib/node_modules, where npm put them. Please read npm-link(1) of npm package, to understand how to properly use npm-installed modules in a project. Note that require.paths is not supported in future node versions. See also node(1) for more information about NODE_PATH. nodejs command -------------- The upstream name for the Node.js interpreter command is "node". In Debian the interpreter command has been changed to "nodejs". This was done to prevent a namespace collision: other commands use the same name in their upstreams, such as ax25-node from the "node" package. Scripts calling Node.js as a shell command must be changed to instead use the "nodejs" command. debian/control.in0000644000000000000000000000621712054743266011215 0ustar Source: nodejs Section: web Priority: extra Maintainer: Debian Javascript Maintainers Uploaders: Jérémy Lal , Jonas Smedegaard DM-Upload-Allowed: yes Build-Depends: @cdbs@ Standards-Version: 3.9.3 Homepage: http://nodejs.org/ Vcs-Browser: http://git.debian.org/?p=collab-maint/nodejs.git Vcs-Git: git://git.debian.org/git/collab-maint/nodejs.git Package: nodejs-dev Section: devel Architecture: any Depends: ${cdbs:Depends}, ${misc:Depends}, nodejs (= ${binary:Version}) Description: Development files for Node.js Node.js provides an event-based server-side javascript engine. . It is similar in design to and influenced by systems like Ruby's Event Machine or Python's Twisted. . Node.js takes the event model a bit further - it presents the event loop as a language construct instead of as a library. . This package is needed to build plugins. Package: nodejs Architecture: any Depends: ${shlibs:Depends}, ${misc:Depends} Breaks: ${cdbs:Breaks} Description: Node.js event-based server-side javascript engine Node.js is similar in design to and influenced by systems like Ruby's Event Machine or Python's Twisted. . It takes the event model a bit further - it presents the event loop as a language construct instead of as a library. . Node.js is bundled with several useful libraries to handle server tasks : System, Events, Standard I/O, Modules, Timers, Child Processes, POSIX, HTTP, Multipart Parsing, TCP, DNS, Assert, Path, URL, Query Strings. Package: nodejs-dbg Section: debug Architecture: any Depends: ${misc:Depends}, nodejs (= ${binary:Version}) Suggests: libv8-dbg Description: Node.js event-based server-side javascript engine (debug) Node.js is similar in design to and influenced by systems like Ruby's Event Machine or Python's Twisted. . It takes the event model a bit further - it presents the event loop as a language construct instead of as a library. . Node.js is bundled with several useful libraries to handle server tasks : System, Events, Standard I/O, Modules, Timers, Child Processes, POSIX, HTTP, Multipart Parsing, TCP, DNS, Assert, Path, URL, Query Strings. . This package contains the debugging symbols. Package: nodejs-legacy Priority: extra Architecture: all Depends: ${misc:Depends}, nodejs (>= 0.6.19~dfsg1-3~) Conflicts: node Description: Node.js event-based server-side javascript engine (legacy symlink) Node.js is similar in design to and influenced by systems like Ruby's Event Machine or Python's Twisted. . It takes the event model a bit further - it presents the event loop as a language construct instead of as a library. . Node.js is bundled with several useful libraries to handle server tasks : System, Events, Standard I/O, Modules, Timers, Child Processes, POSIX, HTTP, Multipart Parsing, TCP, DNS, Assert, Path, URL, Query Strings. . This package contains a symlink for legacy Node.js code requiring binary to be /usr/bin/node (not /usr/bin/nodejs as provided in Debian). . No other Debian packages should depend on this package. For more information, see debian/nodejs-legacy.links0000644000000000000000000000013012004726564012754 0ustar usr/bin/nodejs usr/bin/node usr/share/man/man1/nodejs.1.gz usr/share/man/man1/node.1.gz debian/nodejs.dirs0000644000000000000000000000001712004014433011320 0ustar usr/lib/nodejs debian/NEWS0000644000000000000000000000156512004014454007666 0ustar nodejs (0.6.19~dfsg1-3) unstable; urgency=low * The nodejs package now provides /usr/bin/nodejs, not /usr/bin/node. For more information, see -- Jonas Smedegaard Wed, 25 Jul 2012 17:54:27 +0200 nodejs (0.4.12-2) unstable; urgency=low Do not search for modules in /usr/local/lib/nodejs. That folder, populated by npm, used to be in the search path : this is a mistake, using those modules in a user project is done with `npm link mymodule`, *not* by changing NODE_PATH nor require.paths. System-wide search path is only /usr/lib/nodejs, where modules installed by debian packages go. npm >= 1.0 (when released) install path for 'global' modules will be /usr/local/lib/node_modules. -- Jérémy Lal Mon, 05 Dec 2011 11:34:21 +0100