Mercurial > hg > nginx-site
comparison xml/en/docs/njs/njs_api.xml @ 2204:001f2d905fd9
Documented fileSystem methods in njs.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 26 Jun 2018 16:13:07 +0300 |
parents | 56a8cfb422ae |
children | 6f9fd9677d1b |
comparison
equal
deleted
inserted
replaced
2203:56a8cfb422ae | 2204:001f2d905fd9 |
---|---|
620 </list> | 620 </list> |
621 </para> | 621 </para> |
622 | 622 |
623 </section> | 623 </section> |
624 | 624 |
625 | |
626 <section id="njs_api_fs" name="File System"> | |
627 | |
628 <para> | |
629 The File System module provides operations with files. | |
630 The module object is returned by <literal>require('fs')</literal>. | |
631 <list type="tag"> | |
632 | |
633 <tag-name id="appendfilesync"><literal>appendFileSync(<value>filename</value>, | |
634 <value>data</value>[, <value>options</value>])</literal></tag-name> | |
635 <tag-desc> | |
636 Synchronously appends specified <literal>data</literal> | |
637 to a file with provided <literal>filename</literal>. | |
638 If the file does not exist, it will be created. | |
639 The <literal>options</literal> parameter is expected to be | |
640 an object with the following keys: | |
641 <list type="tag"> | |
642 | |
643 <tag-name><literal>mode</literal></tag-name> | |
644 <tag-desc> | |
645 mode option, by default is <literal>0o666</literal> | |
646 </tag-desc> | |
647 | |
648 <tag-name><literal>flag</literal></tag-name> | |
649 <tag-desc> | |
650 file system <link id="njs_api_fs_flags">flag</link>, | |
651 by default is <literal>a</literal> | |
652 </tag-desc> | |
653 | |
654 </list> | |
655 </tag-desc> | |
656 | |
657 <tag-name id="readfilesync"><literal>readFileSync(<value>filename</value>[, | |
658 <value>options</value>])</literal></tag-name> | |
659 <tag-desc> | |
660 Synchronously returns the contents of the file | |
661 with provided <literal>filename</literal>. | |
662 The <literal>options</literal> parameter holds | |
663 <literal>string</literal> that specifies encoding. | |
664 If not specified, a <link id="string_tobytes">byte string</link> is returned. | |
665 If <literal>utf8</literal> encoding is specified, a Unicode string is returned. | |
666 Otherwise, <literal>options</literal> is expected to be | |
667 an object with the following keys: | |
668 <list type="tag"> | |
669 | |
670 <tag-name><literal>encoding</literal></tag-name> | |
671 <tag-desc> | |
672 encoding, by default is not specified. | |
673 The encoding can be <literal>utf8</literal> | |
674 </tag-desc> | |
675 | |
676 <tag-name><literal>flag</literal></tag-name> | |
677 <tag-desc> | |
678 file system <link id="njs_api_fs_flags">flag</link>, | |
679 by default is <literal>r</literal> | |
680 </tag-desc> | |
681 | |
682 </list> | |
683 <example> | |
684 >> var fs = require('fs') | |
685 undefined | |
686 >> var file = fs.readFileSync('/file/path.tar.gz') | |
687 undefined | |
688 >> var gzipped = /^\x1f\x8b/.test(file); gzipped | |
689 true | |
690 </example> | |
691 </tag-desc> | |
692 | |
693 <tag-name id="writefilesync"><literal>writeFileSync(<value>filename</value>, | |
694 <value>data</value>[, | |
695 <value>options</value>])</literal></tag-name> | |
696 <tag-desc> | |
697 Synchronously writes <literal>data</literal> to a file | |
698 with provided <literal>filename</literal>. | |
699 If the file does not exist, it will be created, | |
700 if the file exists, it will be replaced. | |
701 The <literal>options</literal> parameter is expected to be | |
702 an object with the following keys: | |
703 <list type="tag"> | |
704 <tag-name><literal>mode</literal></tag-name> | |
705 <tag-desc> | |
706 mode option, by default is <literal>0o666</literal> | |
707 </tag-desc> | |
708 | |
709 <tag-name><literal>flag</literal></tag-name> | |
710 <tag-desc> | |
711 file system <link id="njs_api_fs_flags">flag</link>, | |
712 by default is <literal>w</literal> | |
713 </tag-desc> | |
714 | |
715 </list> | |
716 <example> | |
717 >> var fs = require('fs') | |
718 undefined | |
719 >> var file = fs.writeFileSync('hello.txt', 'Hello world') | |
720 undefined | |
721 </example> | |
722 </tag-desc> | |
723 | |
724 </list> | |
725 </para> | |
726 | |
727 | |
728 <section id="njs_api_fs_flags" name="File System Flags"> | |
729 | |
730 <para> | |
731 The <literal>flag</literal> option can accept the following values: | |
732 | |
733 <list type= "bullet" compact="no"> | |
734 | |
735 <listitem> | |
736 <literal>a</literal>—open a file for appending. | |
737 The file is created if it does not exist | |
738 </listitem> | |
739 | |
740 <listitem> | |
741 <literal>ax</literal>—the same as <literal>a</literal> | |
742 but fails if the file already exists | |
743 </listitem> | |
744 | |
745 <listitem> | |
746 <literal>a+</literal>—open a file for reading and appending. | |
747 If the file does not exist, it will be created | |
748 </listitem> | |
749 | |
750 <listitem> | |
751 <literal>ax+</literal>—the same as <literal>a+</literal> | |
752 but fails if the file already exists | |
753 </listitem> | |
754 | |
755 <listitem> | |
756 <literal>as</literal>—open a file for appending in synchronous mode. | |
757 If the file does not exist, it will be created | |
758 </listitem> | |
759 | |
760 <listitem> | |
761 <literal>as+</literal>—open a file for reading and appending | |
762 in synchronous mode. | |
763 If the file does not exist, it will be created | |
764 </listitem> | |
765 | |
766 <listitem> | |
767 <literal>r</literal>—open a file for reading. | |
768 An exception occurs if the file does not exist | |
769 </listitem> | |
770 | |
771 <listitem> | |
772 <literal>r+</literal>—open a file for reading and writing. | |
773 An exception occurs if the file does not exist | |
774 </listitem> | |
775 | |
776 <listitem> | |
777 <literal>rs+</literal>—open a file for reading and writing | |
778 in synchronous mode. | |
779 Instructs the operating system to bypass the local file system cache | |
780 </listitem> | |
781 | |
782 <listitem> | |
783 <literal>w</literal>—open a file for writing. | |
784 If the file does not exist, it will be created. | |
785 If the file exists, it will be replaced | |
786 </listitem> | |
787 | |
788 <listitem> | |
789 <literal>wx</literal>—the same as <literal>w</literal> | |
790 but fails if the file already exists | |
791 </listitem> | |
792 | |
793 <listitem> | |
794 <literal>w+</literal>—open a file for reading and writing. | |
795 If the file does not exist, it will be created. | |
796 If the file exists, it will be replaced | |
797 </listitem> | |
798 | |
799 <listitem> | |
800 <literal>wx+</literal>—the same as <literal>w+</literal> | |
801 but fails if the file already exists | |
802 </listitem> | |
803 | |
804 </list> | |
805 </para> | |
806 | |
807 </section> | |
808 | |
809 </section> | |
810 | |
625 </section> | 811 </section> |
626 | 812 |
627 | 813 |
628 <section id="http" name="HTTP Request"> | 814 <section id="http" name="HTTP Request"> |
629 | 815 |
768 <para> | 954 <para> |
769 If <literal>options</literal> is a string, then it | 955 If <literal>options</literal> is a string, then it |
770 holds the subrequest arguments string. | 956 holds the subrequest arguments string. |
771 Otherwise, <literal>options</literal> is expected to be | 957 Otherwise, <literal>options</literal> is expected to be |
772 an object with the following keys: | 958 an object with the following keys: |
773 | |
774 <list type="tag"> | 959 <list type="tag"> |
775 <tag-name><literal>args</literal></tag-name> | 960 <tag-name><literal>args</literal></tag-name> |
776 <tag-desc> | 961 <tag-desc> |
777 arguments string | 962 arguments string |
778 </tag-desc> | 963 </tag-desc> |