3c10edcb76b2b89b12897a118caaaa7f3cb8cd4c
[scilab.git] / scilab / modules / fileio / help / en_US / mfprintf.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * ...
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="mfprintf" xml:lang="en">
18     <refnamediv>
19         <refname>mfprintf</refname>
20         <refpurpose>converts, formats, and writes data to a file</refpurpose>
21     </refnamediv>
22     <refsynopsisdiv>
23         <title>Syntax</title>
24         <synopsis>mfprintf(fd, format, a1, ..., an);</synopsis>
25     </refsynopsisdiv>
26     <refsection>
27         <title>Arguments</title>
28         <variablelist>
29             <varlistentry>
30                 <term>fd</term>
31                 <listitem>
32                     <para>
33                         a scalar, file descriptor given by <function>mopen</function>
34                         (it's a positive integer).
35                     </para>
36                     <para>
37                         If <varname>fd</varname> equals 0 redirection in stderr.
38                     </para>
39                     <para>
40                         If <varname>fd</varname> equals 6 redirection in stdout.
41                     </para>
42                     <para>
43                         OBSOLETE: The value <literal>-1</literal> refers to the
44                         default file (i.e the last opened file).
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>format</term>
50                 <listitem>
51                     <para>
52                         a Scilab string describing the format to use to write the
53                         remaining operands. The
54                         <varname>
55                             format
56                         </varname>
57                         operand follows,
58                         as close as possible, the C
59                         <function>
60                             printf
61                         </function>
62                         format
63                         operand syntax.
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>str</term>
69                 <listitem>
70                     <para>a character string: a string to be scanned.</para>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>a1, ..., an</term>
75                 <listitem>
76                     <para>
77                         the data to be converted and printed according to
78                         the format parameter.
79                     </para>
80                 </listitem>
81             </varlistentry>
82         </variablelist>
83     </refsection>
84     <refsection>
85         <title>Description</title>
86         <para>
87             The <function>mfprintf</function> function is a interface for C-coded
88             version of <function>fprintf</function> function.
89         </para>
90         <para>
91             The <function>mfprintf</function> function writes formatted operands
92             to the file specified by the file descriptor <varname>fd</varname>. The
93             argument operands are formatted under control of the
94             <varname>format</varname> operand.
95         </para>
96         <para>
97             This function may be used to output column vectors of numbers
98             and string vectors without an explicit loop on the elements. In that
99             case this function iterates on the rows. The shortest vector gives the
100             number of time the format has to be iterated.
101         </para>
102         <para>
103             An homogeneous sequence of identical type parameters can be replaced
104             by a matrix.
105         </para>
106     </refsection>
107     <refsection>
108         <title>Examples</title>
109         <programlisting role="example"><![CDATA[
110
111 fd = mopen(TMPDIR+'/text.txt','wt');
112 mfprintf(fd,'hello %s %d.\n','world',1);
113 mfprintf(fd,'hello %s %d.\n','scilab',2);
114 mfprintf(fd,'This line is built with a column vector (26:28) %d.\n',[26:28].');
115 mfprintf(fd,'This line is built with a row vector (26:28) %d.\n',[26:28]);
116 A = rand(3,6);
117 mfprintf(fd,'This line is built with a matrix %.3f.\n',A);
118 mclose(fd);
119 if (isdef('editor') | (funptr('editor')<>0)) then
120   editor(TMPDIR+'/text.txt')
121 end
122 mfprintf(0,'stderr output.\n');
123 mfprintf(6,'stdout output.\n');
124  ]]></programlisting>
125     </refsection>
126     <refsection role="see also">
127         <title>See also</title>
128         <simplelist type="inline">
129             <member>
130                 <link linkend="mclose">mclose</link>
131             </member>
132             <member>
133                 <link linkend="meof">meof</link>
134             </member>
135             <member>
136                 <link linkend="fprintfMat">fprintfMat</link>
137             </member>
138             <member>
139                 <link linkend="mfscanf">mfscanf</link>
140             </member>
141             <member>
142                 <link linkend="fscanfMat">fscanfMat</link>
143             </member>
144             <member>
145                 <link linkend="mget">mget</link>
146             </member>
147             <member>
148                 <link linkend="mgetstr">mgetstr</link>
149             </member>
150             <member>
151                 <link linkend="mopen">mopen</link>
152             </member>
153             <member>
154                 <link linkend="mprintf">mprintf</link>
155             </member>
156             <member>
157                 <link linkend="mput">mput</link>
158             </member>
159             <member>
160                 <link linkend="mputstr">mputstr</link>
161             </member>
162             <member>
163                 <link linkend="mseek">mseek</link>
164             </member>
165             <member>
166                 <link linkend="mtell">mtell</link>
167             </member>
168             <member>
169                 <link linkend="mdelete">mdelete</link>
170             </member>
171             <member>
172                 <link linkend="printf_conversion">printf_conversion</link>
173             </member>
174         </simplelist>
175     </refsection>
176 </refentry>