Mercurial > hg > nginx-site

comparison xml/en/docs/njs/njs_api.xml @ 2204:001f2d905fd9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>&mdash;open a file for appending.
737 The file is created if it does not exist
738 </listitem>
739
740 <listitem>
741 <literal>ax</literal>&mdash;the same as <literal>a</literal>
742 but fails if the file already exists
743 </listitem>
744
745 <listitem>
746 <literal>a+</literal>&mdash;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>&mdash;the same as <literal>a+</literal>
752 but fails if the file already exists
753 </listitem>
754
755 <listitem>
756 <literal>as</literal>&mdash;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>&mdash;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>&mdash;open a file for reading.
768 An exception occurs if the file does not exist
769 </listitem>
770
771 <listitem>
772 <literal>r+</literal>&mdash;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>&mdash;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>&mdash;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>&mdash;the same as <literal>w</literal>
790 but fails if the file already exists
791 </listitem>
792
793 <listitem>
794 <literal>w+</literal>&mdash;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>&mdash;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>