Doc #61596 [NEW]: Documentation doesn't mention negative return values

From: Operating system: Linux [Debian 6.0.4] PHP version: 5.4Git-2012-04-02 (Git) Package: Documentation problem Bug Type: Documentation Problem Bug description:Documentation doesn't mention negative return values Description: ------------ Originally tested with PHP 5.3.3.7+squeeze8 with Suhosin-Patch (cli) (built: Feb 10 2012 13:05:56) from Debian repository, confirmed with latest from Debian's git repository (announced as 5.4.0). The sscanf() function, when given variables into which to put its results, is documented as returning the number of assigned values: http://php.net/manual/en/function.sscanf.php Usage, however, shows that it can return -1 if the input string does not match the pattern - see test script. I'm not sure if this is a documentation error or an actual function bug (it seems odd that a prefix match should affect the return value), but either way, the disconnect is confusing. The issue seems to arise from ext/standard/scanf.c lines 687-695 (in latest cloned from git), in which different treatment is given to mismatch and underflow, and then line 1200 triggers the -1 return in the case of underflow. My original code (very similar to the test script attached) was using "if (sscanf(....)) do_stuff" - had I known about negative returns, a more correct line of code would say "if (sscanf(...)>0) do_stuff" instead. Test script: --------------- <?php $_POST = array('foobar1'=>5, 'foobar2'=>7, 'foo'=>'Do some Fooage', 'other'=>42); foreach ($_POST as $k=>$v) { $ret=sscanf($k,'foobar%d',$id); echo "key $k -> id $id, value $v - sscanf returned $ret\n"; } Expected result: ---------------- According to the documentation, the foobar1 and foobar2 lines should have a return value of 1, because $id was assigned to; the other two should have a return value of 0. Actual result: -------------- The foo line has a return value of -1, unexpected according to the documentation. -- Edit bug report at https://bugs.php.net/bug.php?id=61596&edit=1 -- Try a snapshot (PHP 5.4): https://bugs.php.net/fix.php?id=61596&r=trysnapshot54 Try a snapshot (PHP 5.3): https://bugs.php.net/fix.php?id=61596&r=trysnapshot53 Try a snapshot (trunk): https://bugs.php.net/fix.php?id=61596&r=trysnapshottrunk Fixed in SVN: https://bugs.php.net/fix.php?id=61596&r=fixed Fixed in SVN and need be documented: https://bugs.php.net/fix.php?id=61596&r=needdocs Fixed in release: https://bugs.php.net/fix.php?id=61596&r=alreadyfixed Need backtrace: https://bugs.php.net/fix.php?id=61596&r=needtrace Need Reproduce Script: https://bugs.php.net/fix.php?id=61596&r=needscript Try newer version: https://bugs.php.net/fix.php?id=61596&r=oldversion Not developer issue: https://bugs.php.net/fix.php?id=61596&r=support Expected behavior: https://bugs.php.net/fix.php?id=61596&r=notwrong Not enough info: https://bugs.php.net/fix.php?id=61596&r=notenoughinfo Submitted twice: https://bugs.php.net/fix.php?id=61596&r=submittedtwice register_globals: https://bugs.php.net/fix.php?id=61596&r=globals PHP 4 support discontinued: https://bugs.php.net/fix.php?id=61596&r=php4 Daylight Savings: https://bugs.php.net/fix.php?id=61596&r=dst IIS Stability: https://bugs.php.net/fix.php?id=61596&r=isapi Install GNU Sed: https://bugs.php.net/fix.php?id=61596&r=gnused Floating point limitations: https://bugs.php.net/fix.php?id=61596&r=float No Zend Extensions: https://bugs.php.net/fix.php?id=61596&r=nozend MySQL Configuration Error: https://bugs.php.net/fix.php?id=61596&r=mysqlcfg