# HG changeset patch
# User John W. Eaton <jwe@octave.org>
# Date 1317738024 14400
# Node ID fba2cc36b762381fd88e8a54cbd94655cd1ec97b
# Parent  eae58f21710207f896bd8a2ed20e4eee90eaa711
return stream error message in scanf functions and document behavior

* oct-stream.cc (octave_base_stream::oscanf):
Also return stream error message.
* file-io.cc (Ffscanf, Fsscanf, Fscanf): Return stream error message
for both vectorized and "C" style calls.  Update doc string.

diff -r eae58f217102 -r fba2cc36b762 src/file-io.cc
--- a/src/file-io.cc	Tue Oct 04 09:57:29 2011 -0400
+++ b/src/file-io.cc	Tue Oct 04 10:20:24 2011 -0400
@@ -1068,8 +1068,8 @@
 
 DEFUN (fscanf, args, ,
   "-*- texinfo -*-\n\
-@deftypefn  {Built-in Function} {[@var{val}, @var{count}] =} fscanf (@var{fid}, @var{template}, @var{size})\n\
-@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}, @var{count}] =} fscanf (@var{fid}, @var{template}, \"C\")\n\
+@deftypefn  {Built-in Function} {[@var{val}, @var{count}, @var{errmsg}] =} fscanf (@var{fid}, @var{template}, @var{size})\n\
+@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}] =} fscanf (@var{fid}, @var{template}, \"C\")\n\
 In the first form, read from @var{fid} according to @var{template},\n\
 returning the result in the matrix @var{val}.\n\
 \n\
@@ -1102,6 +1102,8 @@
 \n\
 The number of items successfully read is returned in @var{count}.\n\
 \n\
+If an error occurs, @var{errmsg} contains a system-dependent error message.\n\
+\n\
 In the second form, read from @var{fid} according to @var{template},\n\
 with each conversion specifier in @var{template} corresponding to a\n\
 single scalar return value.  This form is more `C-like', and also\n\
@@ -1135,8 +1137,9 @@
     }
   else
     {
-      retval (1) = 0.0;
-      retval (0) = Matrix ();
+      retval(2) = "unknown error";
+      retval(1) = 0.0;
+      retval(0) = Matrix ();
 
       if (nargin == 2 || nargin == 3)
         {
@@ -1158,6 +1161,7 @@
 
                       if (! error_state)
                         {
+                          retval(2) = os.error ();
                           retval(1) = count;
                           retval(0) = tmp;
                         }
@@ -1193,8 +1197,8 @@
 
 DEFUN (sscanf, args, ,
   "-*- texinfo -*-\n\
-@deftypefn  {Built-in Function} {[@var{val}, @var{count}, @var{pos}] =} sscanf (@var{string}, @var{template}, @var{size})\n\
-@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}, @var{count}] =} sscanf (@var{string}, @var{template}, \"C\")\n\
+@deftypefn  {Built-in Function} {[@var{val}, @var{count}, @var{errmsg}, @var{pos}] =} sscanf (@var{string}, @var{template}, @var{size})\n\
+@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}] =} sscanf (@var{string}, @var{template}, \"C\")\n\
 This is like @code{fscanf}, except that the characters are taken from the\n\
 string @var{string} instead of from a stream.  Reaching the end of the\n\
 string is treated as an end-of-file condition.  In addition to the values\n\
@@ -1290,8 +1294,8 @@
 
 DEFUN (scanf, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn  {Built-in Function} {[@var{val}, @var{count}] =} scanf (@var{template}, @var{size})\n\
-@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}, @var{count}]] =} scanf (@var{template}, \"C\")\n\
+@deftypefn  {Built-in Function} {[@var{val}, @var{count}, @var{errmsg}] =} scanf (@var{template}, @var{size})\n\
+@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}, @var{count}, @var{errmsg}]] =} scanf (@var{template}, \"C\")\n\
 This is equivalent to calling @code{fscanf} with @var{fid} = @code{stdin}.\n\
 \n\
 It is currently not useful to call @code{scanf} in interactive\n\
diff -r eae58f217102 -r fba2cc36b762 src/oct-stream.cc
--- a/src/oct-stream.cc	Tue Oct 04 09:57:29 2011 -0400
+++ b/src/oct-stream.cc	Tue Oct 04 10:20:24 2011 -0400
@@ -2115,7 +2115,7 @@
 
           octave_idx_type len = fmt_list.length ();
 
-          retval.resize (nconv+1, Matrix ());
+          retval.resize (nconv+2, Matrix ());
 
           const scanf_format_elt *elt = fmt_list.first ();
 
@@ -2145,6 +2145,9 @@
 
           retval(nconv) = num_values;
 
+          int err_num;
+          retval(nconv+1) = error (false, err_num);
+
           if (! quit)
             {
               // Pick up any trailing stuff.