Removed the - now unused - empty builtin configuration (was used for the ace

[cc65] / doc / funcref.sgml

diff --git a/doc/funcref.sgml b/doc/funcref.sgml
index 57a5ce94817d00e26d277664c7c8a95ae5053aba..c7f3e2f174ec0a09e749140580297651353e05a4 100644 (file)
--- a/doc/funcref.sgml
+++ b/doc/funcref.sgml
@@ -67,6 +67,7 @@ function.
 <itemize>
 <item>_dos_type
 <item><ref id="get_ostype" name="get_ostype">
+<item>rebootafterexit
 </itemize>
 
 
@@ -74,9 +75,11 @@ function.
 
 <itemize>
 <item>_dos_type
-<item>_textframe
-<item>_textframexy
 <item><ref id="get_ostype" name="get_ostype">
+<item>rebootafterexit
+<item>textframe
+<item>textframexy
+<item><ref id="videomode" name="videomode">
 </itemize>
 
 
@@ -106,8 +109,9 @@ function.
 <itemize>
 <item><ref id="c64mode" name="c64mode">
 <item><ref id="fast" name="fast">
-<item><ref id="toggle_videomode" name="toggle_videomode">
 <item><ref id="slow" name="slow">
+<item><ref id="toggle_videomode" name="toggle_videomode">
+<item><ref id="videomode" name="videomode">
 </itemize>
 
 
@@ -388,7 +392,6 @@ It does not declare any functions.
 <!-- <item><ref id="fgetpos" name="fgetpos"> -->
 <!-- <item><ref id="fgets" name="fgets"> -->
 <item><ref id="fileno" name="fileno">
-<!-- <item><ref id="flushall" name="flushall"> -->
 <!-- <item><ref id="fopen" name="fopen"> -->
 <!-- <item><ref id="fprintf" name="fprintf"> -->
 <!-- <item><ref id="fputc" name="fputc"> -->
@@ -407,7 +410,8 @@ It does not declare any functions.
 <!-- <item><ref id="putc" name="putc"> -->
 <!-- <item><ref id="putchar" name="putchar"> -->
 <!-- <item><ref id="puts" name="puts"> -->
-<!-- <item><ref id="rename" name="rename"> -->
+<item><ref id="rename" name="rename">
+<item><ref id="remove" name="remove">
 <!-- <item><ref id="rewind" name="rewind"> -->
 <!-- <item><ref id="scanf" name="scanf"> -->
 <!-- <item><ref id="sprintf" name="sprintf"> -->
@@ -452,7 +456,6 @@ It does not declare any functions.
 <item><ref id="qsort" name="qsort">
 <item><ref id="rand" name="rand">
 <item><ref id="realloc" name="realloc">
-<item><ref id="remove" name="remove">
 <item><ref id="srand" name="srand">
 <item><ref id="ultoa" name="ultoa">
 <item><ref id="utoa" name="utoa">
@@ -488,7 +491,7 @@ It does not declare any functions.
 <item><ref id="strspn" name="strspn">
 <item><ref id="strstr" name="strstr">
 <item><ref id="strtok" name="strtok">
-<!-- <item><ref id="strxfrm" name="strxfrm"> -->
+<item><ref id="strxfrm" name="strxfrm">
 <item><ref id="strupper" name="strupper">
 <item><ref id="strupr" name="strupr">
 </itemize>
@@ -812,7 +815,7 @@ is present.
 <tag/Declaration/<tt/void CLI (void);/
 <tag/Description/The function will insert a 6502 CLI instruction into the code,
 so interrupts are enabled. Enabling interrupts has no effects if they are
-already enabled (the default). 
+already enabled (the default).
 <tag/Limits/<itemize>
 <item>The function is actually a macro.
 <item>Disabling interrupts may lead to unexpected results.
@@ -1844,7 +1847,7 @@ extended memory that should be supported. There is no autodetect capability.
 memory and returns a pointer to the page frame. Depending on the hardware
 and driver, the data is either mapped into the address space or transfered
 into a buffer. If you don't need the actual contents of the page (for example
-because you're going to overwrite it completely, it is better to call
+because you're going to overwrite it completely), it is better to call
 <tt/<ref id="em_use" name="em_use">/ instead. <tt/em_use/ will not transfer the
 data if it is possible to avoid that.
 <tag/Limits/<itemize>
@@ -2009,7 +2012,8 @@ will nearly double the speed compared to slow mode.
 <tag/Availability/C128
 <tag/See also/
 <ref id="slow" name="slow">,
-<ref id="toggle_videomode" name="toggle_videomode">
+<ref id="toggle_videomode" name="toggle_videomode">,
+<ref id="videomode" name="videomode">
 <tag/Example/None.
 </descrip>
 </quote>
@@ -3903,8 +3907,10 @@ be used in presence of a prototype.
 </itemize>
 <tag/Availability/ISO 9899
 <tag/See also/
+<ref id="rename" name="rename">,
 <ref id="unlink" name="unlink">
 <tag/Example/
+<verb>
 #include &lt;stdio.h&gt;
 
 #define FILENAME "helloworld"
@@ -3914,6 +3920,44 @@ if (remove (FILENAME) == 0) {
 } else {
     printf ("There was a problem deleting %s\n", FILENAME);
 }
+</verb>
+</descrip>
+</quote>
+
+
+<sect1>rename<label id="rename"><p>
+
+<quote>
+<descrip>
+<tag/Function/Rename a file.
+<tag/Header/<tt/<ref id="stdio.h" name="stdio.h">/
+<tag/Declaration/<tt/int __fastcall__ rename (const char* oldname, const char* newname);/
+<tag/Description/<tt/rename/ renames a file (gives it a new name). On success,
+zero is returned. On error, -1 is returned and <tt/errno/ is set to an error
+code describing the reason for the failure.
+<tag/Limits/
+<itemize>
+<item>This function is not available on all cc65 targets (depends on the
+capabilities of the storage devices).
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+</itemize>
+<tag/Availability/ISO 9899
+<tag/See also/
+<ref id="remove" name="remove">
+<tag/Example/
+<verb>
+#include &lt;stdio.h&gt;
+
+#define OLDNAME "textfile.txt"
+#define NEWNAME "textfile.bak"
+
+if (rename (OLDNAME, NEWNAME) == 0) {
+    printf ("Renamed %s to %s\n", OLDNAME, NEWNAME);
+} else {
+    printf ("Error renaming %s to %s\n", OLDNAME, NEWNAME);
+}
+</verb>
 </descrip>
 </quote>
 
@@ -4068,6 +4112,7 @@ different locale has no effect.
 <tag/See also/
 <ref id="localeconv" name="localeconv">,
 <ref id="strcoll" name="strcoll">
+<ref id="strxfrm" name="strxfrm">
 <tag/Example/None.
 </descrip>
 </quote>
@@ -4132,7 +4177,8 @@ will halve the speed compared to fast mode.
 <tag/Availability/C128
 <tag/See also/
 <ref id="fast" name="fast">,
-<ref id="toggle_videomode" name="toggle_videomode">
+<ref id="toggle_videomode" name="toggle_videomode">,
+<ref id="videomode" name="videomode">
 <tag/Example/None.
 </descrip>
 </quote>
@@ -4183,6 +4229,7 @@ be used in presence of a prototype.
 <ref id="strcoll" name="strcoll">,
 <ref id="stricmp" name="stricmp">,
 <ref id="strncmp" name="strncmp">
+<ref id="strxfrm" name="strxfrm">
 <tag/Example/None.
 </descrip>
 </quote>
@@ -4260,6 +4307,7 @@ be used in presence of a prototype.
 <ref id="strcoll" name="strcoll">,
 <ref id="stricmp" name="stricmp">,
 <ref id="strncmp" name="strncmp">
+<ref id="strxfrm" name="strxfrm">
 <tag/Example/None.
 </descrip>
 </quote>
@@ -4288,6 +4336,7 @@ be used in presence of a prototype.
 <ref id="strcmp" name="strcmp">,
 <ref id="stricmp" name="stricmp">,
 <ref id="strncmp" name="strncmp">
+<ref id="strxfrm" name="strxfrm">
 <tag/Example/None.
 </descrip>
 </quote>
@@ -4422,6 +4471,7 @@ be used in presence of a prototype.
 <ref id="strcmp" name="strcmp">,
 <ref id="strcoll" name="strcoll">,
 <ref id="strncmp" name="strncmp">
+<ref id="strxfrm" name="strxfrm">
 <tag/Example/None.
 </descrip>
 </quote>
@@ -4530,6 +4580,7 @@ be used in presence of a prototype.
 <ref id="strcmp" name="strcmp">,
 <ref id="strcoll" name="strcoll">,
 <ref id="stricmp" name="stricmp">
+<ref id="strxfrm" name="strxfrm">
 <tag/Example/None.
 </descrip>
 </quote>
@@ -4668,6 +4719,39 @@ be used in presence of a prototype.
 </quote>
 
 
+<sect1>strxfrm<label id="strxfrm"><p>
+
+<quote>
+<descrip>
+<tag/Function/Transform a string.
+<tag/Header/<tt/<ref id="string.h" name="string.h">/
+<tag/Declaration/<tt/size_t __fastcall__ strxfrm (char* s1, const char* s2, size_t n);/
+<tag/Description/The <tt/strxfrm/ function transforms the string pointed to by
+s2 and places the resulting string into the string pointed to by s1. The
+transformation is such that if the <tt/strcmp/ function is applied to two
+transformed strings, it returns a value greater than, equal to, or less than
+zero, corresponding to the result of the <tt/strcoll/ function applied to the
+same two original strings. No more than n characters are placed into the
+resulting array pointed to by s1, including the terminating null character.
+<tag/Limits/<itemize>
+<item><tt/s1/ and <tt/s2/ must not point to the same memory area, otherwise
+the behaviour is undefined.
+<item>If <tt/n/ is zero, <tt/s1/ may be a NULL pointer.
+<item>The function is only available as fastcall function, so it may only
+be used in presence of a prototype.
+<item>Since cc65 doesn't support different charcter sets, <tt/strxfrm/ will
+just copy s2 to s1 using <tt><ref id="strncpy" name="strncpy"></tt>.
+</itemize>
+<tag/Availability/ISO 9899
+<tag/See also/
+<ref id="strcmp" name="strcmp">,
+<ref id="strcoll" name="strcoll">,
+<ref id="strncpy" name="strncpy">,
+<tag/Example/None.
+</descrip>
+</quote>
+
+
 <sect1>strupper<label id="strupper"><p>
 
 <quote>
@@ -4759,11 +4843,14 @@ old mode (cursor position, color and so on) are saved and restored together
 with the mode.
 <tag/Limits/<itemize>
 <item>The function is specific to the C128.
+<item>This function is deprecated. Please use <ref id="videomode"
+name="videomode"> instead!
 </itemize>
 <tag/Availability/C128
 <tag/See also/
 <ref id="fast" name="fast">,
-<ref id="slow" name="slow">
+<ref id="slow" name="slow">,
+<ref id="videomode" name="videomode">
 <tag/Example/None.
 </descrip>
 </quote>
@@ -4869,6 +4956,7 @@ to the ISO C standard.
 <tag/See also/
 <ref id="remove" name="remove">
 <tag/Example/
+<verb>
 #include &lt;stdio.h&gt;
 #include &lt;unistd.h&gt;
 
@@ -4879,6 +4967,7 @@ if (unlink (FILENAME) == 0) {
 } else {
     printf ("There was a problem deleting %s\n", FILENAME);
 }
+</verb>
 </descrip>
 </quote>
 
@@ -4940,6 +5029,34 @@ used in presence of a prototype.
 </quote>
 
 
+<sect1>videomode<label id="videomode"><p>
+
+<quote>
+<descrip>
+<tag/Function/Switch to either 40 or 80 column mode.
+<tag/Header/<tt/<ref id="apple2enh.h" name="apple2enh.h">,
+<ref id="c128.h" name="c128.h">/
+<tag/Declaration/<tt/unsigned __fastcall__ videomode (unsigned Mode);/
+<tag/Description/Switch to 40 or 80 column mode depending on the argument. If
+the requested mode is already active, nothing happens. The old mode is returned
+from the call.
+<tag/Limits/<itemize>
+<item>The function is specific to the C128 and enhanced Apple //e.
+<item>This function replaces <ref id="toggle_videomode"
+name="toggle_videomode">.
+<item>The function is only available as fastcall function, so it may only be
+used in presence of a prototype.
+</itemize>
+<tag/Availability/C128 and enhanced Apple //e
+<tag/See also/
+<ref id="fast" name="fast">,
+<ref id="slow" name="slow">,
+<ref id="toggle_videomode" name="toggle_videomode">
+<tag/Example/None.
+</descrip>
+</quote>
+
+
 <sect1>wherex<label id="wherex"><p>
 
 <quote>