@@ -236,9 +236,6 @@ Events are represented by a camel-cased string. Here are some examples:
236
236
Functions can be then be attached to objects, to be executed when an event
237
237
is emitted. These functions are called _listeners_.
238
238
239
- Some asynchronous file operations return an +EventEmitter+ called a
240
- _promise_. A promise emits just a single event when the operation is
241
- complete.
242
239
243
240
=== +events.EventEmitter+
244
241
@@ -586,60 +583,96 @@ will be sent +"SIGTERM"+. See signal(7) for a list of available signals.
586
583
== File System
587
584
588
585
File I/O is provided by simple wrappers around standard POSIX functions. To
589
- use this module do +require("fs")+. All the methods have a similar form.
590
- They return a promise (+events.Promise+). Example of deleting a file:
586
+ use this module do +require("fs")+. All the methods have asynchornous and
587
+ synchronous forms.
591
588
592
- ------------------------------------------------------------------------------
589
+ The asynchronous form always take a completion callback as its last
590
+ argument. The arguments passed to the completion callback depend on the
591
+ method, but the first argument is always reserved for an exception. If the
592
+ operation was completed successfully, then the first argument will be +null+
593
+ or +undefined+.
594
+
595
+ Here is an example of the asynchornous version:
596
+
597
+ -------------------------------------------------------
593
598
var fs = require("fs"),
594
599
sys = require("sys");
595
600
596
- var promise = fs.unlink("/tmp/hello");
597
-
598
- promise.addCallback(function () {
601
+ fs.unlink("/tmp/hello", function (err) {
602
+ if (err) throw err;
599
603
sys.puts("successfully deleted /tmp/hello");
600
604
});
601
- ------------------------------------------------------------------------------
605
+ -------------------------------------------------------
606
+
607
+ Here is the synchronous version:
608
+
609
+ -------------------------------------------------------
610
+ var fs = require("fs"),
611
+ sys = require("sys");
612
+
613
+ fs.unlinkSync("/tmp/hello")
614
+ sys.puts("successfully deleted /tmp/hello");
615
+ -------------------------------------------------------
602
616
603
- This is asynchornous, there is no guaranteed ordering. The following is
604
- prone to error
617
+ With the asynchronous methods there is no guaranteed ordering. So the
618
+ following is prone to error:
605
619
606
- ------------------------------------------------------------------------------
607
- fs.rename("/tmp/hello", "/tmp/world");
608
- fs.stat("/tmp/world").addCallback(function (stats) {
620
+ ------------------------------------------------------
621
+ fs.rename("/tmp/hello", "/tmp/world", function (err) {
622
+ if (err) throw err;
623
+ sys.puts("renamed complete");
624
+ });
625
+ fs.stat("/tmp/world", function (err, stats) {
626
+ if (err) throw err;
609
627
sys.puts("stats: " + JSON.stringify(stats));
610
628
});
611
- ------------------------------------------------------------------------------
629
+ ------------------------------------------------------
612
630
613
631
It could be that +fs.stat+ is executed before +fs.rename+.
614
- The correct way to do this is to chain the promises .
632
+ The correct way to do this is to chain the callbacks .
615
633
616
- ------------------------------------------------------------------------------
617
- fs.rename("/tmp/hello", "/tmp/world").addCallback(function () {
618
- fs.stat("/tmp/world").addCallback(function (stats) {
634
+ ------------------------------------------------------
635
+ fs.rename("/tmp/hello", "/tmp/world", function (err) {
636
+ if (err) throw err;
637
+ fs.stat("/tmp/world", function (err, stats) {
638
+ if (err) throw err;
619
639
sys.puts("stats: " + JSON.stringify(stats));
620
640
});
621
641
});
622
- ------------------------------------------------------------------------------
642
+ ------------------------------------------------------
643
+
644
+ In busy processes, the programmer is _strongly encouraged_ to use the
645
+ asynchronous versions of these calls. The synchronous versions will block
646
+ the entire process until they complete--halting all connections.
623
647
624
648
625
- +fs.rename(path1, path2)+ ::
626
- See rename(2).
627
- - on success: no parameters.
628
- - on error: no parameters.
649
+ +fs.rename(path1, path2, callback)+ ::
650
+ Asynchronous rename(2).
651
+ No arguments other than a possible exception are given to the completion callback.
629
652
630
- +fs.truncate(fd, len)+ ::
631
- See ftruncate(2).
632
- - on success: no parameters.
633
- - on error: no parameters.
653
+ +fs.renameSync(path1, path2)+ ::
654
+ Synchronous rename(2).
655
+
656
+
657
+ +fs.truncate(fd, len, callback)+ ::
658
+ Asynchronous ftruncate(2).
659
+ No arguments other than a possible exception are given to the completion callback.
660
+
661
+ +fs.truncateSync(fd, len)+ ::
662
+ Synchronous ftruncate(2).
663
+
664
+
665
+ +fs.chmod(path, mode, callback)+ ::
666
+ Asynchronous chmod(2).
667
+ No arguments other than a possible exception are given to the completion callback.
668
+
669
+ +fs.chmodSync(path, mode)+ ::
670
+ Synchronous chmod(2).
634
671
635
- +fs.chmod(path, mode)+ ::
636
- See chmod(1)
637
- - on success: no parameters.
638
- - on error: no parameters.
639
672
640
- +fs.stat(path)+ ::
641
- See stat(2).
642
- - on success: Returns +fs.Stats+ object. It looks like this:
673
+ +fs.stat(path, callback )+ ::
674
+ Asynchronous stat(2). The callback gets two arguments +(err, stats)+ where
675
+ +stats+ is a +fs.Stats+ object. It looks like this:
643
676
+
644
677
---------------------------------
645
678
{ dev: 2049
@@ -660,91 +693,116 @@ See stat(2).
660
693
+
661
694
See the +fs.Stats+ section below for more information.
662
695
663
- - on error: no parameters.
696
+ +fs.statSync(path)+ ::
697
+ Synchronous stat(2). Returns an instance of +fs.Stats+.
664
698
665
699
666
- +fs.unlink(path)+ ::
667
- See unlink(2)
668
- - on success: no parameters.
669
- - on error: no parameters.
700
+ +fs.unlink(path, callback)+ ::
701
+ Asynchronous unlink(2).
702
+ No arguments other than a possible exception are given to the completion callback.
670
703
704
+ +fs.unlinkSync(path)+ ::
705
+ Synchronous unlink(2).
671
706
672
- +fs.rmdir(path)+ ::
673
- See rmdir(2)
674
- - on success: no parameters.
675
- - on error: no parameters.
676
707
708
+ +fs.rmdir(path, callback)+ ::
709
+ Asynchronous rmdir(2).
710
+ No arguments other than a possible exception are given to the completion callback.
677
711
678
- +fs.mkdir(path, mode)+ ::
679
- See mkdir(2)
680
- - on success: no parameters.
681
- - on error: no parameters.
712
+ +fs.rmdirSync(path)+ ::
713
+ Synchronous rmdir(2).
682
714
683
715
684
- +fs.readdir(path)+ ::
685
- Reads the contents of a directory.
686
- - on success: One argument, an array containing the names (strings) of the
687
- files in the directory (excluding "." and "..").
688
- - on error: no parameters.
716
+ +fs.mkdir(path, mode, callback)+ ::
717
+ Asynchronous mkdir(2).
718
+ No arguments other than a possible exception are given to the completion callback.
689
719
720
+ +fs.mkdirSync(path, mode)+ ::
721
+ Synchronous mkdir(2).
690
722
691
- +fs.close(fd)+ ::
692
- See close(2)
693
- - on success: no parameters.
694
- - on error: no parameters.
695
723
724
+ +fs.readdir(path, callback)+ ::
725
+ Asynchronous readdir(3). Reads the contents of a directory.
726
+ The callback gets two arguments +(err, files)+ where +files+ is an array of
727
+ the names of the files in the directory excluding +"."+ and +".."+.
696
728
697
- +fs.open(path, flags, mode=0666)+::
698
- See open(2). The constants like +O_CREAT+ are defined at +process.O_CREAT+.
699
- Also you can use the strings "r", "r+", "w", "w+", "a", or "a+" as aliases
700
- to the common flag combinations.
701
- - on success: +fd+ is given as the parameter.
702
- - on error: no parameters.
703
729
730
+ +fs.close(fd, callback)+ ::
731
+ Asynchronous close(2).
732
+ No arguments other than a possible exception are given to the completion callback.
704
733
705
- +fs.write(fd, data, position, encoding)+::
706
- Write data to the file specified by +fd+. +position+ refers to the offset
707
- from the beginning of the file where this data should be written. If
708
- +position+ is +null+, the data will be written at the current position.
709
- See pwrite(2).
710
- - on success: returns an integer +written+ which specifies how many _bytes_ were written.
711
- - on error: no parameters.
734
+ +fs.closeSync(fd)+ ::
735
+ Synchronous close(2).
712
736
713
- +fs.read(fd, length, position, encoding)+::
714
- Read data from the file specified by +fd+.
715
- +
716
- +length+ is an integer specifying the number of
717
- bytes to read.
718
- +
719
- +position+ is an integer specifying where to begin
720
- reading from in the file.
721
- +
722
- - on success: returns +data, bytes_read+, what was read from the file.
723
- - on error: no parameters.
724
737
725
- +fs.readFile(filename, encoding="utf8")+::
726
- Outputs the entire contents of a file. Example:
738
+ +fs.open(path, flags, mode, callback)+::
739
+ Asynchronous file open. See open(2). Flags can be "r", "r+", "w", "w+", "a",
740
+ or "a+". The callback gets two arguments +(err, fd)+.
741
+
742
+ +fs.openSync(path, flags, mode)+::
743
+ Synchronous open(2).
744
+
745
+
746
+ +fs.write(fd, data, position, encoding, callback)+::
747
+ Write data to the file specified by +fd+. +position+ refers to the offset
748
+ from the beginning of the file where this data should be written. If
749
+ +position+ is +null+, the data will be written at the current position.
750
+ See pwrite(2).
751
+ +
752
+ The callback will be given two arguments +(err, written)+ where +written+
753
+ specifies how many _bytes_ were written.
754
+
755
+ +fs.writeSync(fd, data, position, encoding)+::
756
+ Synchronous version of +fs.write()+. Returns the number of bytes written.
757
+
758
+
759
+ +fs.read(fd, length, position, encoding, callback)+::
760
+ Read data from the file specified by +fd+.
761
+ +
762
+ +length+ is an integer specifying the number of
763
+ bytes to read.
764
+ +
765
+ +position+ is an integer specifying where to begin
766
+ reading from in the file.
767
+ +
768
+ The callback is given three arguments, +(err, data, bytesRead)+ where +data+
769
+ is a string--what was read--and +bytesRead+ is the number of bytes read.
770
+
771
+ +fs.readSync(fd, length, position, encoding)+::
772
+ Synchronous version of +fs.read+. Returns an array +[data, bytesRead]+.
773
+
774
+ +fs.readFile(filename, encoding="utf8", callback)+::
775
+ Asynchronously reads the entire contents of a file. Example:
727
776
+
728
777
--------------------------------
729
- fs.readFile("/etc/passwd").addCallback(function (content) {
778
+ fs.readFile("/etc/passwd", function (err, data) {
779
+ if (err) throw err;
730
780
sys.puts(content);
731
781
});
732
782
--------------------------------
733
783
+
734
- - on success: returns +data+, what was read from the file.
735
- - on error: no parameters.
784
+ The callback is passed two arguments +(err, data)+, where +data+ is the
785
+ contents of the file.
786
+
787
+ +fs.readFileSync(filename, encoding="utf8")+::
788
+ Synchronous version of +fs.readFile+. Returns the contents of the
789
+ +filename+.
790
+
736
791
737
- +fs.writeFile(filename, data, encoding="utf8")+::
738
- Writes data to a file. Example:
792
+ +fs.writeFile(filename, data, encoding="utf8", callback )+::
793
+ Asynchronously writes data to a file. Example:
739
794
+
740
795
--------------------------------
741
- fs.writeFile("message.txt", "Hello Node").addCallback(function () {
796
+ fs.writeFile("message.txt", "Hello Node", function (err) {
797
+ if (err) throw err;
742
798
sys.puts("It's saved!");
743
799
});
744
800
--------------------------------
745
- +
746
- - on success: no parameters.
747
- - on error: no parameters.
801
+
802
+ +fs.writeFileSync(filename, data, encoding="utf8")+::
803
+ The synchronous version of +fs.writeFile+.
804
+
805
+
748
806
749
807
=== +fs.Stats+
750
808
0 commit comments