doc/api/buffer.markdown

   1 # Buffer
   2
   3     Stability: 3 - Stable
   4
   5 Pure JavaScript is Unicode friendly but not nice to binary data.  When
   6 dealing with TCP streams or the file system, it's necessary to handle octet
   7 streams. Node has several strategies for manipulating, creating, and
   8 consuming octet streams.
   9
  10 Raw data is stored in instances of the `Buffer` class. A `Buffer` is similar
  11 to an array of integers but corresponds to a raw memory allocation outside
  12 the V8 heap. A `Buffer` cannot be resized.
  13
  14 The `Buffer` class is a global, making it very rare that one would need
  15 to ever `require('buffer')`.
  16
  17 Converting between Buffers and JavaScript string objects requires an explicit
  18 encoding method.  Here are the different string encodings.
  19
  20 * `'ascii'` - for 7 bit ASCII data only.  This encoding method is very fast, and
  21   will strip the high bit if set.
  22
  23 * `'utf8'` - Multibyte encoded Unicode characters. Many web pages and other
  24   document formats use UTF-8.
  25
  26 * `'utf16le'` - 2 or 4 bytes, little endian encoded Unicode characters.
  27   Surrogate pairs (U+10000 to U+10FFFF) are supported.
  28
  29 * `'ucs2'` - Alias of `'utf16le'`.
  30
  31 * `'base64'` - Base64 string encoding.
  32
  33 * `'binary'` - A way of encoding raw binary data into strings by using only
  34   the first 8 bits of each character. This encoding method is deprecated and
  35   should be avoided in favor of `Buffer` objects where possible. This encoding
  36   will be removed in future versions of Node.
  37
  38 * `'hex'` - Encode each byte as two hexadecimal characters.
  39
  40 ## Class: Buffer
  41
  42 The Buffer class is a global type for dealing with binary data directly.
  43 It can be constructed in a variety of ways.
  44
  45 ### new Buffer(size)
  46
  47 * `size` Number
  48
  49 Allocates a new buffer of `size` octets.
  50
  51 ### new Buffer(array)
  52
  53 * `array` Array
  54
  55 Allocates a new buffer using an `array` of octets.
  56
  57 ### new Buffer(str, [encoding])
  58
  59 * `str` String - string to encode.
  60 * `encoding` String - encoding to use, Optional.
  61
  62 Allocates a new buffer containing the given `str`.
  63 `encoding` defaults to `'utf8'`.
  64
  65 ### Class Method: Buffer.isEncoding(encoding)
  66
  67 * `encoding` {String} The encoding string to test
  68
  69 Returns true if the `encoding` is a valid encoding argument, or false
  70 otherwise.
  71
  72 ### Class Method: Buffer.isBuffer(obj)
  73
  74 * `obj` Object
  75 * Return: Boolean
  76
  77 Tests if `obj` is a `Buffer`.
  78
  79 ### Class Method: Buffer.byteLength(string, [encoding])
  80
  81 * `string` String
  82 * `encoding` String, Optional, Default: 'utf8'
  83 * Return: Number
  84
  85 Gives the actual byte length of a string. `encoding` defaults to `'utf8'`.
  86 This is not the same as `String.prototype.length` since that returns the
  87 number of *characters* in a string.
  88
  89 Example:
  90
  91     str = '\u00bd + \u00bc = \u00be';
  92
  93     console.log(str + ": " + str.length + " characters, " +
  94       Buffer.byteLength(str, 'utf8') + " bytes");
  95
  96     // ½ + ¼ = ¾: 9 characters, 12 bytes
  97
  98 ### Class Method: Buffer.concat(list, [totalLength])
  99
 100 * `list` {Array} List of Buffer objects to concat
 101 * `totalLength` {Number} Total length of the buffers when concatenated
 102
 103 Returns a buffer which is the result of concatenating all the buffers in
 104 the list together.
 105
 106 If the list has no items, or if the totalLength is 0, then it returns a
 107 zero-length buffer.
 108
 109 If the list has exactly one item, then the first item of the list is
 110 returned.
 111
 112 If the list has more than one item, then a new Buffer is created.
 113
 114 If totalLength is not provided, it is read from the buffers in the list.
 115 However, this adds an additional loop to the function, so it is faster
 116 to provide the length explicitly.
 117
 118 ### buf.length
 119
 120 * Number
 121
 122 The size of the buffer in bytes.  Note that this is not necessarily the size
 123 of the contents. `length` refers to the amount of memory allocated for the
 124 buffer object.  It does not change when the contents of the buffer are changed.
 125
 126     buf = new Buffer(1234);
 127
 128     console.log(buf.length);
 129     buf.write("some string", 0, "ascii");
 130     console.log(buf.length);
 131
 132     // 1234
 133     // 1234
 134
 135 ### buf.write(string, [offset], [length], [encoding])
 136
 137 * `string` String - data to be written to buffer
 138 * `offset` Number, Optional, Default: 0
 139 * `length` Number, Optional, Default: `buffer.length - offset`
 140 * `encoding` String, Optional, Default: 'utf8'
 141
 142 Writes `string` to the buffer at `offset` using the given encoding.
 143 `offset` defaults to `0`, `encoding` defaults to `'utf8'`. `length` is
 144 the number of bytes to write. Returns number of octets written. If `buffer` did
 145 not contain enough space to fit the entire string, it will write a partial
 146 amount of the string. `length` defaults to `buffer.length - offset`.
 147 The method will not write partial characters.
 148
 149     buf = new Buffer(256);
 150     len = buf.write('\u00bd + \u00bc = \u00be', 0);
 151     console.log(len + " bytes: " + buf.toString('utf8', 0, len));
 152
 153
 154 ### buf.toString([encoding], [start], [end])
 155
 156 * `encoding` String, Optional, Default: 'utf8'
 157 * `start` Number, Optional, Default: 0
 158 * `end` Number, Optional, Default: `buffer.length`
 159
 160 Decodes and returns a string from buffer data encoded with `encoding`
 161 (defaults to `'utf8'`) beginning at `start` (defaults to `0`) and ending at
 162 `end` (defaults to `buffer.length`).
 163
 164 See `buffer.write()` example, above.
 165
 166
 167 ### buf.toJSON()
 168
 169 Returns a JSON-representation of the Buffer instance.  `JSON.stringify`
 170 implicitly calls this function when stringifying a Buffer instance.
 171
 172 Example:
 173
 174     var buf = new Buffer('test');
 175     var json = JSON.stringify(buf);
 176
 177     console.log(json);
 178     // '{"type":"Buffer","data":[116,101,115,116]}'
 179
 180     var copy = JSON.parse(json, function(key, value) {
 181         return value && value.type === 'Buffer'
 182           ? new Buffer(value.data)
 183           : value;
 184       });
 185
 186     console.log(copy);
 187     // <Buffer 74 65 73 74>
 188
 189 ### buf[index]
 190
 191 <!--type=property-->
 192 <!--name=[index]-->
 193
 194 Get and set the octet at `index`. The values refer to individual bytes,
 195 so the legal range is between `0x00` and `0xFF` hex or `0` and `255`.
 196
 197 Example: copy an ASCII string into a buffer, one byte at a time:
 198
 199     str = "node.js";
 200     buf = new Buffer(str.length);
 201
 202     for (var i = 0; i < str.length ; i++) {
 203       buf[i] = str.charCodeAt(i);
 204     }
 205
 206     console.log(buf);
 207
 208     // node.js
 209
 210 ### buf.copy(targetBuffer, [targetStart], [sourceStart], [sourceEnd])
 211
 212 * `targetBuffer` Buffer object - Buffer to copy into
 213 * `targetStart` Number, Optional, Default: 0
 214 * `sourceStart` Number, Optional, Default: 0
 215 * `sourceEnd` Number, Optional, Default: `buffer.length`
 216
 217 Does copy between buffers. The source and target regions can be overlapped.
 218 `targetStart` and `sourceStart` default to `0`.
 219 `sourceEnd` defaults to `buffer.length`.
 220
 221 All values passed that are `undefined`/`NaN` or are out of bounds are set equal
 222 to their respective defaults.
 223
 224 Example: build two Buffers, then copy `buf1` from byte 16 through byte 19
 225 into `buf2`, starting at the 8th byte in `buf2`.
 226
 227     buf1 = new Buffer(26);
 228     buf2 = new Buffer(26);
 229
 230     for (var i = 0 ; i < 26 ; i++) {
 231       buf1[i] = i + 97; // 97 is ASCII a
 232       buf2[i] = 33; // ASCII !
 233     }
 234
 235     buf1.copy(buf2, 8, 16, 20);
 236     console.log(buf2.toString('ascii', 0, 25));
 237
 238     // !!!!!!!!qrst!!!!!!!!!!!!!
 239
 240
 241 ### buf.slice([start], [end])
 242
 243 * `start` Number, Optional, Default: 0
 244 * `end` Number, Optional, Default: `buffer.length`
 245
 246 Returns a new buffer which references the same memory as the old, but offset
 247 and cropped by the `start` (defaults to `0`) and `end` (defaults to
 248 `buffer.length`) indexes.  Negative indexes start from the end of the buffer.
 249
 250 **Modifying the new buffer slice will modify memory in the original buffer!**
 251
 252 Example: build a Buffer with the ASCII alphabet, take a slice, then modify one
 253 byte from the original Buffer.
 254
 255     var buf1 = new Buffer(26);
 256
 257     for (var i = 0 ; i < 26 ; i++) {
 258       buf1[i] = i + 97; // 97 is ASCII a
 259     }
 260
 261     var buf2 = buf1.slice(0, 3);
 262     console.log(buf2.toString('ascii', 0, buf2.length));
 263     buf1[0] = 33;
 264     console.log(buf2.toString('ascii', 0, buf2.length));
 265
 266     // abc
 267     // !bc
 268
 269 ### buf.readUInt8(offset, [noAssert])
 270
 271 * `offset` Number
 272 * `noAssert` Boolean, Optional, Default: false
 273 * Return: Number
 274
 275 Reads an unsigned 8 bit integer from the buffer at the specified offset.
 276
 277 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 278 may be beyond the end of the buffer. Defaults to `false`.
 279
 280 Example:
 281
 282     var buf = new Buffer(4);
 283
 284     buf[0] = 0x3;
 285     buf[1] = 0x4;
 286     buf[2] = 0x23;
 287     buf[3] = 0x42;
 288
 289     for (ii = 0; ii < buf.length; ii++) {
 290       console.log(buf.readUInt8(ii));
 291     }
 292
 293     // 0x3
 294     // 0x4
 295     // 0x23
 296     // 0x42
 297
 298 ### buf.readUInt16LE(offset, [noAssert])
 299 ### buf.readUInt16BE(offset, [noAssert])
 300
 301 * `offset` Number
 302 * `noAssert` Boolean, Optional, Default: false
 303 * Return: Number
 304
 305 Reads an unsigned 16 bit integer from the buffer at the specified offset with
 306 specified endian format.
 307
 308 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 309 may be beyond the end of the buffer. Defaults to `false`.
 310
 311 Example:
 312
 313     var buf = new Buffer(4);
 314
 315     buf[0] = 0x3;
 316     buf[1] = 0x4;
 317     buf[2] = 0x23;
 318     buf[3] = 0x42;
 319
 320     console.log(buf.readUInt16BE(0));
 321     console.log(buf.readUInt16LE(0));
 322     console.log(buf.readUInt16BE(1));
 323     console.log(buf.readUInt16LE(1));
 324     console.log(buf.readUInt16BE(2));
 325     console.log(buf.readUInt16LE(2));
 326
 327     // 0x0304
 328     // 0x0403
 329     // 0x0423
 330     // 0x2304
 331     // 0x2342
 332     // 0x4223
 333
 334 ### buf.readUInt32LE(offset, [noAssert])
 335 ### buf.readUInt32BE(offset, [noAssert])
 336
 337 * `offset` Number
 338 * `noAssert` Boolean, Optional, Default: false
 339 * Return: Number
 340
 341 Reads an unsigned 32 bit integer from the buffer at the specified offset with
 342 specified endian format.
 343
 344 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 345 may be beyond the end of the buffer. Defaults to `false`.
 346
 347 Example:
 348
 349     var buf = new Buffer(4);
 350
 351     buf[0] = 0x3;
 352     buf[1] = 0x4;
 353     buf[2] = 0x23;
 354     buf[3] = 0x42;
 355
 356     console.log(buf.readUInt32BE(0));
 357     console.log(buf.readUInt32LE(0));
 358
 359     // 0x03042342
 360     // 0x42230403
 361
 362 ### buf.readInt8(offset, [noAssert])
 363
 364 * `offset` Number
 365 * `noAssert` Boolean, Optional, Default: false
 366 * Return: Number
 367
 368 Reads a signed 8 bit integer from the buffer at the specified offset.
 369
 370 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 371 may be beyond the end of the buffer. Defaults to `false`.
 372
 373 Works as `buffer.readUInt8`, except buffer contents are treated as two's
 374 complement signed values.
 375
 376 ### buf.readInt16LE(offset, [noAssert])
 377 ### buf.readInt16BE(offset, [noAssert])
 378
 379 * `offset` Number
 380 * `noAssert` Boolean, Optional, Default: false
 381 * Return: Number
 382
 383 Reads a signed 16 bit integer from the buffer at the specified offset with
 384 specified endian format.
 385
 386 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 387 may be beyond the end of the buffer. Defaults to `false`.
 388
 389 Works as `buffer.readUInt16*`, except buffer contents are treated as two's
 390 complement signed values.
 391
 392 ### buf.readInt32LE(offset, [noAssert])
 393 ### buf.readInt32BE(offset, [noAssert])
 394
 395 * `offset` Number
 396 * `noAssert` Boolean, Optional, Default: false
 397 * Return: Number
 398
 399 Reads a signed 32 bit integer from the buffer at the specified offset with
 400 specified endian format.
 401
 402 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 403 may be beyond the end of the buffer. Defaults to `false`.
 404
 405 Works as `buffer.readUInt32*`, except buffer contents are treated as two's
 406 complement signed values.
 407
 408 ### buf.readFloatLE(offset, [noAssert])
 409 ### buf.readFloatBE(offset, [noAssert])
 410
 411 * `offset` Number
 412 * `noAssert` Boolean, Optional, Default: false
 413 * Return: Number
 414
 415 Reads a 32 bit float from the buffer at the specified offset with specified
 416 endian format.
 417
 418 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 419 may be beyond the end of the buffer. Defaults to `false`.
 420
 421 Example:
 422
 423     var buf = new Buffer(4);
 424
 425     buf[0] = 0x00;
 426     buf[1] = 0x00;
 427     buf[2] = 0x80;
 428     buf[3] = 0x3f;
 429
 430     console.log(buf.readFloatLE(0));
 431
 432     // 0x01
 433
 434 ### buf.readDoubleLE(offset, [noAssert])
 435 ### buf.readDoubleBE(offset, [noAssert])
 436
 437 * `offset` Number
 438 * `noAssert` Boolean, Optional, Default: false
 439 * Return: Number
 440
 441 Reads a 64 bit double from the buffer at the specified offset with specified
 442 endian format.
 443
 444 Set `noAssert` to true to skip validation of `offset`. This means that `offset`
 445 may be beyond the end of the buffer. Defaults to `false`.
 446
 447 Example:
 448
 449     var buf = new Buffer(8);
 450
 451     buf[0] = 0x55;
 452     buf[1] = 0x55;
 453     buf[2] = 0x55;
 454     buf[3] = 0x55;
 455     buf[4] = 0x55;
 456     buf[5] = 0x55;
 457     buf[6] = 0xd5;
 458     buf[7] = 0x3f;
 459
 460     console.log(buf.readDoubleLE(0));
 461
 462     // 0.3333333333333333
 463
 464 ### buf.writeUInt8(value, offset, [noAssert])
 465
 466 * `value` Number
 467 * `offset` Number
 468 * `noAssert` Boolean, Optional, Default: false
 469
 470 Writes `value` to the buffer at the specified offset. Note, `value` must be a
 471 valid unsigned 8 bit integer.
 472
 473 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 474 that `value` may be too large for the specific function and `offset` may be
 475 beyond the end of the buffer leading to the values being silently dropped. This
 476 should not be used unless you are certain of correctness. Defaults to `false`.
 477
 478 Example:
 479
 480     var buf = new Buffer(4);
 481     buf.writeUInt8(0x3, 0);
 482     buf.writeUInt8(0x4, 1);
 483     buf.writeUInt8(0x23, 2);
 484     buf.writeUInt8(0x42, 3);
 485
 486     console.log(buf);
 487
 488     // <Buffer 03 04 23 42>
 489
 490 ### buf.writeUInt16LE(value, offset, [noAssert])
 491 ### buf.writeUInt16BE(value, offset, [noAssert])
 492
 493 * `value` Number
 494 * `offset` Number
 495 * `noAssert` Boolean, Optional, Default: false
 496
 497 Writes `value` to the buffer at the specified offset with specified endian
 498 format. Note, `value` must be a valid unsigned 16 bit integer.
 499
 500 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 501 that `value` may be too large for the specific function and `offset` may be
 502 beyond the end of the buffer leading to the values being silently dropped. This
 503 should not be used unless you are certain of correctness. Defaults to `false`.
 504
 505 Example:
 506
 507     var buf = new Buffer(4);
 508     buf.writeUInt16BE(0xdead, 0);
 509     buf.writeUInt16BE(0xbeef, 2);
 510
 511     console.log(buf);
 512
 513     buf.writeUInt16LE(0xdead, 0);
 514     buf.writeUInt16LE(0xbeef, 2);
 515
 516     console.log(buf);
 517
 518     // <Buffer de ad be ef>
 519     // <Buffer ad de ef be>
 520
 521 ### buf.writeUInt32LE(value, offset, [noAssert])
 522 ### buf.writeUInt32BE(value, offset, [noAssert])
 523
 524 * `value` Number
 525 * `offset` Number
 526 * `noAssert` Boolean, Optional, Default: false
 527
 528 Writes `value` to the buffer at the specified offset with specified endian
 529 format. Note, `value` must be a valid unsigned 32 bit integer.
 530
 531 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 532 that `value` may be too large for the specific function and `offset` may be
 533 beyond the end of the buffer leading to the values being silently dropped. This
 534 should not be used unless you are certain of correctness. Defaults to `false`.
 535
 536 Example:
 537
 538     var buf = new Buffer(4);
 539     buf.writeUInt32BE(0xfeedface, 0);
 540
 541     console.log(buf);
 542
 543     buf.writeUInt32LE(0xfeedface, 0);
 544
 545     console.log(buf);
 546
 547     // <Buffer fe ed fa ce>
 548     // <Buffer ce fa ed fe>
 549
 550 ### buf.writeInt8(value, offset, [noAssert])
 551
 552 * `value` Number
 553 * `offset` Number
 554 * `noAssert` Boolean, Optional, Default: false
 555
 556 Writes `value` to the buffer at the specified offset. Note, `value` must be a
 557 valid signed 8 bit integer.
 558
 559 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 560 that `value` may be too large for the specific function and `offset` may be
 561 beyond the end of the buffer leading to the values being silently dropped. This
 562 should not be used unless you are certain of correctness. Defaults to `false`.
 563
 564 Works as `buffer.writeUInt8`, except value is written out as a two's complement
 565 signed integer into `buffer`.
 566
 567 ### buf.writeInt16LE(value, offset, [noAssert])
 568 ### buf.writeInt16BE(value, offset, [noAssert])
 569
 570 * `value` Number
 571 * `offset` Number
 572 * `noAssert` Boolean, Optional, Default: false
 573
 574 Writes `value` to the buffer at the specified offset with specified endian
 575 format. Note, `value` must be a valid signed 16 bit integer.
 576
 577 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 578 that `value` may be too large for the specific function and `offset` may be
 579 beyond the end of the buffer leading to the values being silently dropped. This
 580 should not be used unless you are certain of correctness. Defaults to `false`.
 581
 582 Works as `buffer.writeUInt16*`, except value is written out as a two's
 583 complement signed integer into `buffer`.
 584
 585 ### buf.writeInt32LE(value, offset, [noAssert])
 586 ### buf.writeInt32BE(value, offset, [noAssert])
 587
 588 * `value` Number
 589 * `offset` Number
 590 * `noAssert` Boolean, Optional, Default: false
 591
 592 Writes `value` to the buffer at the specified offset with specified endian
 593 format. Note, `value` must be a valid signed 32 bit integer.
 594
 595 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 596 that `value` may be too large for the specific function and `offset` may be
 597 beyond the end of the buffer leading to the values being silently dropped. This
 598 should not be used unless you are certain of correctness. Defaults to `false`.
 599
 600 Works as `buffer.writeUInt32*`, except value is written out as a two's
 601 complement signed integer into `buffer`.
 602
 603 ### buf.writeFloatLE(value, offset, [noAssert])
 604 ### buf.writeFloatBE(value, offset, [noAssert])
 605
 606 * `value` Number
 607 * `offset` Number
 608 * `noAssert` Boolean, Optional, Default: false
 609
 610 Writes `value` to the buffer at the specified offset with specified endian
 611 format. Note, behavior is unspecified if `value` is not a 32 bit float.
 612
 613 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 614 that `value` may be too large for the specific function and `offset` may be
 615 beyond the end of the buffer leading to the values being silently dropped. This
 616 should not be used unless you are certain of correctness. Defaults to `false`.
 617
 618 Example:
 619
 620     var buf = new Buffer(4);
 621     buf.writeFloatBE(0xcafebabe, 0);
 622
 623     console.log(buf);
 624
 625     buf.writeFloatLE(0xcafebabe, 0);
 626
 627     console.log(buf);
 628
 629     // <Buffer 4f 4a fe bb>
 630     // <Buffer bb fe 4a 4f>
 631
 632 ### buf.writeDoubleLE(value, offset, [noAssert])
 633 ### buf.writeDoubleBE(value, offset, [noAssert])
 634
 635 * `value` Number
 636 * `offset` Number
 637 * `noAssert` Boolean, Optional, Default: false
 638
 639 Writes `value` to the buffer at the specified offset with specified endian
 640 format. Note, `value` must be a valid 64 bit double.
 641
 642 Set `noAssert` to true to skip validation of `value` and `offset`. This means
 643 that `value` may be too large for the specific function and `offset` may be
 644 beyond the end of the buffer leading to the values being silently dropped. This
 645 should not be used unless you are certain of correctness. Defaults to `false`.
 646
 647 Example:
 648
 649     var buf = new Buffer(8);
 650     buf.writeDoubleBE(0xdeadbeefcafebabe, 0);
 651
 652     console.log(buf);
 653
 654     buf.writeDoubleLE(0xdeadbeefcafebabe, 0);
 655
 656     console.log(buf);
 657
 658     // <Buffer 43 eb d5 b7 dd f9 5f d7>
 659     // <Buffer d7 5f f9 dd b7 d5 eb 43>
 660
 661 ### buf.fill(value, [offset], [end])
 662
 663 * `value`
 664 * `offset` Number, Optional
 665 * `end` Number, Optional
 666
 667 Fills the buffer with the specified value. If the `offset` (defaults to `0`)
 668 and `end` (defaults to `buffer.length`) are not given it will fill the entire
 669 buffer.
 670
 671     var b = new Buffer(50);
 672     b.fill("h");
 673
 674 ## buffer.INSPECT_MAX_BYTES
 675
 676 * Number, Default: 50
 677
 678 How many bytes will be returned when `buffer.inspect()` is called. This can
 679 be overridden by user modules.
 680
 681 Note that this is a property on the buffer module returned by
 682 `require('buffer')`, not on the Buffer global, or a buffer instance.
 683
 684 ## Class: SlowBuffer
 685
 686 Returns an un-pooled `Buffer`.
 687
 688 In order to avoid the garbage collection overhead of creating many individually
 689 allocated Buffers, by default allocations under 4KB are sliced from a single
 690 larger allocated object. This approach improves both performance and memory
 691 usage since v8 does not need to track and cleanup as many `Persistent` objects.
 692
 693 In the case where a developer may need to retain a small chunk of memory from a
 694 pool for an indeterminate amount of time it may be appropriate to create an
 695 un-pooled Buffer instance using SlowBuffer and copy out the relevant bits.
 696
 697     // need to keep around a few small chunks of memory
 698     var store = [];
 699
 700     socket.on('readable', function() {
 701       var data = socket.read();
 702       // allocate for retained data
 703       var sb = new SlowBuffer(10);
 704       // copy the data into the new allocation
 705       data.copy(sb, 0, 0, 10);
 706       store.push(sb);
 707     });
 708
 709 Though this should used sparingly and only be a last resort *after* a developer
 710 has actively observed undue memory retention in their applications.