From a227089ba1b71edf2fc46080faea3fc8fa0e3a2d Mon Sep 17 00:00:00 2001 From: Stefan Date: Wed, 7 Feb 2018 00:11:55 +0100 Subject: [PATCH 1/4] Added missing documentation of header --- doc/funcref.sgml | 185 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 177 insertions(+), 8 deletions(-) diff --git a/doc/funcref.sgml b/doc/funcref.sgml index 15830b2a2..7a7bdb1ee 100644 --- a/doc/funcref.sgml +++ b/doc/funcref.sgml @@ -4,7 +4,7 @@ cc65 function reference <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline> <url url="mailto:greg.king5@verizon.net" name="Greg King"> -<date>2017-12-09 +<date>2018-02-06 <abstract> cc65 is a C compiler for 6502 based systems. This function reference describes @@ -293,6 +293,16 @@ function. (incomplete) +<sect1><tt/device.h/<label id="device.h"><p> + +<itemize> +<item><ref id="getcurrentdevice" name="getcurrentdevice"> +<item><ref id="getdevicedir" name="getdevicedir"> +<item><ref id="getfirstdevice" name="getfirstdevice"> +<item><ref id="getnextdevice" name="getnextdevice"> +</itemize> + + <sect1><tt/dio.h/<label id="dio.h"><p> <url url="dio.html" name="Low-level disk I/O API">. @@ -313,8 +323,6 @@ function. <item><ref id="telldir" name="telldir"> </itemize> -(incomplete) - <sect1><tt/em.h/<label id="em.h"><p> @@ -661,9 +669,11 @@ communication. <item><ref id="strlen" name="strlen"> <item><ref id="strlower" name="strlower"> <item><ref id="strlwr" name="strlwr"> +<item><ref id="strncasecmp" name="strncasecmp"> <item><ref id="strncat" name="strncat"> <item><ref id="strncmp" name="strncmp"> <item><ref id="strncpy" name="strncpy"> +<item><ref id="strnicmp" name="strnicmp"> <item><ref id="strqtok" name="strqtok"> <item><ref id="strrchr" name="strrchr"> <item><ref id="strspn" name="strspn"> @@ -674,8 +684,6 @@ communication. <item><ref id="strupr" name="strupr"> </itemize> -(incomplete) - <sect1><tt/telestrat.h/<label id="telestrat.h"><p> @@ -2930,9 +2938,9 @@ exits. <tag/Availability/cc65 <tag/Example/<verb> /* Hello World */ -#include <stdio.h> -#include <unistd.h> -#include <cc65.h> +#include <stdio.h> +#include <unistd.h> +#include <cc65.h> int main(void) { printf("Hello World\n"); @@ -3450,6 +3458,111 @@ returns one of the constants<itemize> </quote> +<sect1>getcurrentdevice<label id="getcurrentdevice"><p> + +<quote> +<descrip> +<tag/Function/Get current device. +<tag/Header/<tt/<ref id="device.h" name="device.h">/ +<tag/Declaration/<tt/unsigned char getcurrentdevice (void);/ +<tag/Description/The function returns the current device. +<tag/Notes/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="getdevicedir" name="getdevicedir">, +<ref id="getfirstdevice" name="getfirstdevice">, +<ref id="getnextdevice" name="getnextdevice"> +<tag/Example/<verb> +puts (getdevicedir (getcurrentdevice (), buf, sizeof buf)); +</verb> +</descrip> +</quote> + + +<sect1>getdevicedir<label id="getdevicedir"><p> + +<quote> +<descrip> +<tag/Function/Get device directory. +<tag/Header/<tt/<ref id="device.h" name="device.h">/ +<tag/Declaration/<tt/char* __fastcall__ getdevicedir (unsigned char device, char* buf, size_t size);/ +<tag/Description/The function returns the current directory of <tt/device/. +<tag/Notes/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="getcwd" name="getcwd">, +<ref id="getcurrentdevice" name="getcurrentdevice">, +<ref id="getfirstdevice" name="getfirstdevice">, +<ref id="getnextdevice" name="getnextdevice"> +<tag/Example/<verb> +puts (getdevicedir (getcurrentdevice (), buf, sizeof buf)); +</verb> +</descrip> +</quote> + + +<sect1>getfirstdevice<label id="getfirstdevice"><p> + +<quote> +<descrip> +<tag/Function/Get first device. +<tag/Header/<tt/<ref id="device.h" name="device.h">/ +<tag/Declaration/<tt/unsigned char getfirstdevice (void);/ +<tag/Description/The function returns the first device. +The value 255 indicates no device. +<tag/Notes/<itemize> +<item> +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="getcurrentdevice" name="getcurrentdevice">, +<ref id="getdevicedir" name="getdevicedir">, +<ref id="getnextdevice" name="getnextdevice"> +<tag/Example/<verb> +unsigned char dev = getfirstdevice (); +while (dev != 255) { + printf ("%d\n", dev); + dev = getnextdevice (dev); + } +</verb> +</descrip> +</quote> + + +<sect1>getnextdevice<label id="getnextdevice"><p> + +<quote> +<descrip> +<tag/Function/Get next device. +<tag/Header/<tt/<ref id="device.h" name="device.h">/ +<tag/Declaration/<tt/unsigned char __fastcall__ getnextdevice (unsigned char device);/ +<tag/Description/The function returns the next device after <tt/device/. +The value 255 indicates no further device. +<tag/Notes/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="getcurrentdevice" name="getcurrentdevice">, +<ref id="getdevicedir" name="getdevicedir">, +<ref id="getfirstdevice" name="getfirstdevice"> +<tag/Example/<verb> +unsigned char dev = getfirstdevice (); +while (dev != 255) { + printf ("%d\n", dev); + dev = getnextdevice (dev); + } +</verb> +</descrip> +</quote> + + <sect1>getenv<label id="getenv"><p> <quote> @@ -6284,6 +6397,34 @@ See <tt/strlower/. </quote> +<sect1>strncasecmp<label id="strncasecmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings case insensitive. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ strncasecmp (const char* s1, const char* s2, size_t count);/ +<tag/Description/The <tt/strncasecmp/ function compares the two strings passed +as parameters without case sensitivity. It returns a value that is less than +zero if <tt/s1/ is less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, +and a value greater than zero if <tt/s1/ is greater than <tt/s2/. +<tag/Notes/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function is not available in strict ANSI mode. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strcmp" name="strcmp">, +<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> + + <sect1>strncat<label id="strncat"><p> <quote> @@ -6377,6 +6518,34 @@ strncpy (hello, "Hello world!\n", sizeof hello - 1)[5] = '\0'; </quote> +<sect1>strnicmp<label id="strnicmp"><p> + +<quote> +<descrip> +<tag/Function/Compare two strings case insensitive. +<tag/Header/<tt/<ref id="string.h" name="string.h">/ +<tag/Declaration/<tt/int __fastcall__ strnicmp (const char* s1, const char* s2, size_t count);/ +<tag/Description/The <tt/strnicmp/ function compares the two strings passed as +parameters without case sensitivity. It returns a value that is less than zero +if <tt/s1/ is less than <tt/s2/, zero if <tt/s1/ is the same as <tt/s2/, and a +value greater than zero if <tt/s1/ is greater than <tt/s2/. +<tag/Notes/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +<item>The function is not available in strict ANSI mode. +</itemize> +<tag/Availability/cc65 +<tag/See also/ +<ref id="strcasecmp" name="strcasecmp">, +<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> + + <sect1>strqtok<label id="strqtok"><p> <quote> From a48f998162aa6d2c3134821de00c2c1c72dc5e11 Mon Sep 17 00:00:00 2001 From: Stefan <stefan.haubenthal@gmail.com> Date: Wed, 7 Feb 2018 01:55:56 +0100 Subject: [PATCH 2/4] Added missing function --- doc/funcref.sgml | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/doc/funcref.sgml b/doc/funcref.sgml index 7a7bdb1ee..a442f5e08 100644 --- a/doc/funcref.sgml +++ b/doc/funcref.sgml @@ -4,7 +4,7 @@ <title>cc65 function reference <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline> <url url="mailto:greg.king5@verizon.net" name="Greg King"> -<date>2018-02-06 +<date>2018-02-07 <abstract> cc65 is a C compiler for 6502 based systems. This function reference describes @@ -726,7 +726,7 @@ communication. <itemize> <!-- <item><ref id="chdir" name="chdir"> --> <item><ref id="exec" name="exec"> -<!-- <item><ref id="getcwd" name="getcwd"> --> +<item><ref id="getcwd" name="getcwd"> <item><ref id="getopt" name="getopt"> <!-- <item><ref id="lseek" name="lseek"> --> <!-- <item><ref id="mkdir" name="mkdir"> --> @@ -3481,6 +3481,24 @@ puts (getdevicedir (getcurrentdevice (), buf, sizeof buf)); </quote> +<sect1>getcwd<label id="getcwd"><p> + +<quote> +<descrip> +<tag/Function/Get current working directory. +<tag/Header/<tt/<ref id="unistd.h" name="unistd.h">/ +<tag/Declaration/<tt/char* __fastcall__ getcwd (char* buf, size_t size);/ +<tag/Description/The function will return the current working directory. +<tag/Notes/<itemize> +<item>The function is only available as fastcall function, so it may only +be used in presence of a prototype. +</itemize> +<tag/Availability/POSIX 1003.1 +<tag/Example/None. +</descrip> +</quote> + + <sect1>getdevicedir<label id="getdevicedir"><p> <quote> From b69ee802fde17ea8126144dbab9f5cc51dca42a4 Mon Sep 17 00:00:00 2001 From: Stefan <stefan.haubenthal@gmail.com> Date: Wed, 7 Feb 2018 03:07:30 +0100 Subject: [PATCH 3/4] Sorted --- doc/funcref.sgml | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/doc/funcref.sgml b/doc/funcref.sgml index a442f5e08..83fc36a6b 100644 --- a/doc/funcref.sgml +++ b/doc/funcref.sgml @@ -3524,6 +3524,29 @@ puts (getdevicedir (getcurrentdevice (), buf, sizeof buf)); </quote> +<sect1>getenv<label id="getenv"><p> + +<quote> +<descrip> +<tag/Function/Return a value from the environment. +<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ +<tag/Declaration/<tt/char* __fastcall__ getenv (const char* name);/ +<tag/Description/The function searches the environment for an entry that +matches <tt/name/ and returns its value. The environment consists of a list +of strings in the form <tt/name=value/. If there is no match, <tt/getenv/ +returns <tt/NULL/. +<tag/Notes/<itemize> +<item>What exactly is stored in the environment depends on the machine the +program is running on. +<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/Example/None. +</descrip> +</quote> + + <sect1>getfirstdevice<label id="getfirstdevice"><p> <quote> @@ -3581,29 +3604,6 @@ while (dev != 255) { </quote> -<sect1>getenv<label id="getenv"><p> - -<quote> -<descrip> -<tag/Function/Return a value from the environment. -<tag/Header/<tt/<ref id="stdlib.h" name="stdlib.h">/ -<tag/Declaration/<tt/char* __fastcall__ getenv (const char* name);/ -<tag/Description/The function searches the environment for an entry that -matches <tt/name/ and returns its value. The environment consists of a list -of strings in the form <tt/name=value/. If there is no match, <tt/getenv/ -returns <tt/NULL/. -<tag/Notes/<itemize> -<item>What exactly is stored in the environment depends on the machine the -program is running on. -<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/Example/None. -</descrip> -</quote> - - <sect1>getopt<label id="getopt"><p> <quote> From 4d7098f2f223934ab50787c2e7923e16d160c4b8 Mon Sep 17 00:00:00 2001 From: Stefan <stefan.haubenthal@gmail.com> Date: Wed, 7 Feb 2018 16:23:49 +0100 Subject: [PATCH 4/4] Requested changes --- doc/funcref.sgml | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/funcref.sgml b/doc/funcref.sgml index 83fc36a6b..c083f467e 100644 --- a/doc/funcref.sgml +++ b/doc/funcref.sgml @@ -3466,6 +3466,9 @@ returns one of the constants<itemize> <tag/Header/<tt/<ref id="device.h" name="device.h">/ <tag/Declaration/<tt/unsigned char getcurrentdevice (void);/ <tag/Description/The function returns the current device. +It allows to access the current device with the <ref id="dio.h" +name="Low-level disk I/O API"> or <ref id="cbm.h" name="cbm_* I/O +functions"> requiring a 'device' parameter. <tag/Notes/<itemize> <item> </itemize> @@ -3475,7 +3478,7 @@ returns one of the constants<itemize> <ref id="getfirstdevice" name="getfirstdevice">, <ref id="getnextdevice" name="getnextdevice"> <tag/Example/<verb> -puts (getdevicedir (getcurrentdevice (), buf, sizeof buf)); +dio_open (getcurrentdevice ()); </verb> </descrip> </quote> @@ -3506,7 +3509,9 @@ be used in presence of a prototype. <tag/Function/Get device directory. <tag/Header/<tt/<ref id="device.h" name="device.h">/ <tag/Declaration/<tt/char* __fastcall__ getdevicedir (unsigned char device, char* buf, size_t size);/ -<tag/Description/The function returns the current directory of <tt/device/. +<tag/Description/The function returns the directory representing <tt/device/. +It allows to access the device on filesystem level by calling chdir() with +the directory returned. <tag/Notes/<itemize> <item>The function is only available as fastcall function, so it may only be used in presence of a prototype. @@ -3518,7 +3523,7 @@ be used in presence of a prototype. <ref id="getfirstdevice" name="getfirstdevice">, <ref id="getnextdevice" name="getnextdevice"> <tag/Example/<verb> -puts (getdevicedir (getcurrentdevice (), buf, sizeof buf)); +chdir (getdevicedir (device, buf, sizeof buf)); </verb> </descrip> </quote> @@ -3555,7 +3560,7 @@ be used in presence of a prototype. <tag/Header/<tt/<ref id="device.h" name="device.h">/ <tag/Declaration/<tt/unsigned char getfirstdevice (void);/ <tag/Description/The function returns the first device. -The value 255 indicates no device. +The constant <tt/INVALID_DEVICE/ indicates no device. <tag/Notes/<itemize> <item> </itemize> @@ -3566,7 +3571,7 @@ The value 255 indicates no device. <ref id="getnextdevice" name="getnextdevice"> <tag/Example/<verb> unsigned char dev = getfirstdevice (); -while (dev != 255) { +while (dev != INVALID_DEVICE) { printf ("%d\n", dev); dev = getnextdevice (dev); } @@ -3583,7 +3588,7 @@ while (dev != 255) { <tag/Header/<tt/<ref id="device.h" name="device.h">/ <tag/Declaration/<tt/unsigned char __fastcall__ getnextdevice (unsigned char device);/ <tag/Description/The function returns the next device after <tt/device/. -The value 255 indicates no further device. +The constant <tt/INVALID_DEVICE/ indicates no further device. <tag/Notes/<itemize> <item>The function is only available as fastcall function, so it may only be used in presence of a prototype. @@ -3595,7 +3600,7 @@ be used in presence of a prototype. <ref id="getfirstdevice" name="getfirstdevice"> <tag/Example/<verb> unsigned char dev = getfirstdevice (); -while (dev != 255) { +while (dev != INVALID_DEVICE) { printf ("%d\n", dev); dev = getnextdevice (dev); }