scilab/modules/fileio/help/en_US/fprintf.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  * This file must be used under the terms of the CeCILL.
   8  * This source file is licensed as described in the file COPYING, which
   9  * you should have received as part of this distribution.  The terms
  10  * are also available at
  11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
  12  *
  13  -->
  14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="fprintf">
  15     <refnamediv>
  16         <refname>fprintf</refname>
  17         <refpurpose>
  18             Emulator of C language fprintf function. <emphasis role="bold">This function is obsolete.</emphasis>
  19         </refpurpose>
  20     </refnamediv>
  21     <refsynopsisdiv>
  22         <title>Calling Sequence</title>
  23         <synopsis>fprintf(file, format, value_1, ..., value_n)</synopsis>
  24     </refsynopsisdiv>
  25     <refsection>
  26         <title>Arguments</title>
  27         <variablelist>
  28             <varlistentry>
  29                 <term>format</term>
  30                 <listitem>
  31                     <para>a Scilab string. It specifies a character string combining literal characters with conversion specifications.</para>
  32                 </listitem>
  33             </varlistentry>
  34             <varlistentry>
  35                 <term>value_i</term>
  36                 <listitem>
  37                     <para>
  38                         specifies the data to be converted according to the <varname>format</varname> parameter.
  39                     </para>
  40                 </listitem>
  41             </varlistentry>
  42             <varlistentry>
  43                 <term>file</term>
  44                 <listitem>
  45                     <para>
  46                         a Scilab string specifying a file name or a logical unit number (see <link linkend="file">file</link>)
  47                     </para>
  48                     <para>
  49                         Note that if <varname>file</varname>=0, the message will be display on standard error stream (stderr).
  50                     </para>
  51                 </listitem>
  52             </varlistentry>
  53         </variablelist>
  54     </refsection>
  55     <refsection>
  56         <title>Description</title>
  57         <para>
  58             <caution>
  59                 This function is obsolete and will be removed in Scilab 5.5.0, use preferabily the <link
  60         linkend="mfprintf">mfprintf</link> function which is much more
  61                 compatible with the C <function>fprintf</function> functionalities.
  62             </caution>
  63         </para>
  64         <para>
  65             The <function>fprintf</function> function converts, formats, and writes
  66             its <varname>value</varname> parameters, under control of the <varname>format</varname>
  67             parameter, to the file specified by its <varname>file</varname> parameter.
  68         </para>
  69         <para>
  70             The <varname>format</varname> parameter is a character string that contains two
  71             types of objects:
  72         </para>
  73         <variablelist>
  74             <varlistentry>
  75                 <term>Literal characters</term>
  76                 <listitem>
  77                     <para>which are copied to the output stream.</para>
  78                 </listitem>
  79             </varlistentry>
  80             <varlistentry>
  81                 <term>Conversion specifications</term>
  82                 <listitem>
  83                     <para>
  84                         each of which causes zero or more items to be fetched from the <varname>value</varname> parameter list. See <link linkend="printf_conversion">printf_conversion</link> for details.
  85                     </para>
  86                 </listitem>
  87             </varlistentry>
  88         </variablelist>
  89         <para>
  90             If any <varname>value</varname>s remain after the entire <varname>format</varname> has been
  91             processed, they are ignored.
  92         </para>
  93     </refsection>
  94     <refsection>
  95         <title>Examples</title>
  96         <programlisting role="example"><![CDATA[
  97 u=file('open',fullfile(TMPDIR,'results'),'unknown') //open the result file
  98 t=0:0.1:2*%pi;
  99 for tk=t
 100   fprintf(u,'time = %6.3f value = %6.3f',tk,sin(tk)) // write a line
 101 end
 102 file('close',u) //close the result file
 103
 104 fprintf(0,'My error which is going to be displayed on the stderr')
 105  ]]></programlisting>
 106     </refsection>
 107     <refsection>
 108         <title>History</title>
 109         <revhistory>
 110             <revision>
 111                 <revnumber>5.4.1</revnumber>
 112                 <revremark>Function tagged as obsolete. Will be removed in 5.5.0.</revremark>
 113             </revision>
 114         </revhistory>
 115     </refsection>
 116     <refsection role="see also">
 117         <title>See Also</title>
 118         <simplelist type="inline">
 119             <member>
 120                 <link linkend="mfprintf">mfprintf</link>
 121             </member>
 122             <member>
 123                 <link linkend="string">string</link>
 124             </member>
 125             <member>
 126                 <link linkend="print">print</link>
 127             </member>
 128             <member>
 129                 <link linkend="write">write</link>
 130             </member>
 131             <member>
 132                 <link linkend="format">format</link>
 133             </member>
 134             <member>
 135                 <link linkend="disp">disp</link>
 136             </member>
 137             <member>
 138                 <link linkend="file">file</link>
 139             </member>
 140             <member>
 141                 <link linkend="mprintf">mprintf</link>
 142             </member>
 143             <member>
 144                 <link linkend="msprintf">msprintf</link>
 145             </member>
 146             <member>
 147                 <link linkend="printf_conversion">printf_conversion</link>
 148             </member>
 149         </simplelist>
 150     </refsection>
 151 </refentry>