When browsing through AmigaOS developer documentation and C code, there's always a funny, interesting, sometimes enlightening little find.
It's just nice to see how it all ties together, and the changes made from one operating system (API) release to the next. Learning about the infrastructure of software, esp. over multiple versions, exposes some of the thinking process of the operating system developers.
Sometimes, it also reveals long forgotten secrets. If you're a C coder using AmigaOS, chances are you've been using a datatype known as "APTR" somewhere in your code. It is used extensively throughout AmigaOS 1.3 Native Developer Kit (NDK) C include-files, and even more extensively throughout later NDK releases.
And it turns out it's wrong!
From NDK 1.3 Includes exec/types.h:
typedef STRPTR *APTR; /* absolute memory pointer */
/* sigh. APTR was misdefined, but compatibility rules. Heres what it
* should have been
*/
typedef ULONG CPTR; /* absolute memory pointer */
Yes, even the pros make a little mistake from time to time. Obviously, they kept compatibility, meaning they (and everybody else) kept using APTR, when it should be CPTR.
Interestingly, in NDK 1.3 there is - a little - use of CPTR (in resources/filesysres.h, libraries/romboot_base.h, and libraries/expansion.h), but it has been half-removed (from libraries/romboot_base.h and libraries/expansion.h) and half-reintroduced (in dos/dosextens.h) with later NDK versions.
Chances are you've also been using datatypes SHORT and USHORT in your C code. Guess what: It's wrong, too! Here's another little snippet from NDK 1.3 exec/types.h that may clarify this further, long standing issue:
typedef short WORD; /* signed 16-bit quantity */
typedef unsigned short UWORD; /* unsigned 16-bit quantity */
...
/* For compatability only: (don't use in new code) */
typedef short SHORT; /* signed 16-bit quantity (WORD) */
typedef unsigned short USHORT; /* unsigned 16-bit quantity (UWORD) */
SHORT and USHORT are just backwards-compatable [sic] aliases for WORD and UWORD.
Given the very non-volatile situation of AmigaOS development, both APTR and (U)SHORT won't give you a headache. APTR is used throughout the operating system, and will most likely never be replaced. CPTR is used only in less than a handful of cases - you'll probably never need it (and it has been moved to the "compatibility only" [sic] section of NDK 3.9 exec/types.h). (U)SHORT is deprecated since NDK 1.3, and hasn't been removed in later releases, so it's probably cemented into today's global AmigaOS code base, and will never be removed from the NDK.
So - lessons learned:
- use APTR, it's (not) correct
- (don't) use SHORT and USHORT
;-)
* * *
BONUS:
Here's yet another nice, ancient compatibility [sic] snippet, from NDK 1.3 Includes libraries/dos.h, moved to dos/dos.h in NDK 3.9:
/* Relative position to Seek() */
#define OFFSET_BEGINNING -1 /* relative to Begining Of File */
...
#define OFFSET_BEGINING OFFSET_BEGINNING /* ancient compatibility */
Thank you - one less typing error to worry about. :-)
