A2osX/.Docs/KERNEL.md
2018-12-21 15:32:45 +01:00

1283 lines
21 KiB
Markdown

*** Auto generated by docgen.cmd ***
# Args2ArgV
Expand String and convert to ArgV List
## C
short int args2argv(char* args, char* argv[])
## ASM
`>PUSHW argv`
`>LDYA args`
`>SYSCALL Args2ArgV
## RETURN VALUE
A = Arg count
# ArgV
## ASM
**In:**
A = argument index.
## RETURN VALUE
CC : success
Y,A = PTR To Arg[A]
CS : Out Of Bound
# LoadDrv
## ASM
**In:**
Y,A = PTR to "NAME.DRV [PARAM]" C-String
## RETURN VALUE
none
# InsDrv
## C
`void * insdrv (void * src, void * crvcsstart, void * drvcsend, void * drvend);`
## ASM
**In:**
`>PUSHW DRV.END`
`>PUSHW DRV.CS.END`
`>PUSHW DRV.CS.START`
`>LDYA L.SRC`
`SYSCALL insdrv`
## RETURN VALUE
Y,A = Ptr to installed driver
# GetDevByName
Y,A = Ptr to device name (C-String)
## RETURN VALUE
CC = OK, CS = ERROR
Y,A = FD
X = DevID
# GetDevStatus
## C
`int getdevstatus(short int hFD, S.DIB* dstat);`
## ASM
`>PUSHWI S.DIB`
`lda DevID`
`>SYSCALL GetDevStatus`
## RETURN VALUE
# MKDev
Create a hDEV
## C
`hDEV mkdev (S.FD * fd, const char *devname)`
## ASM
`>PUSHW devname`
`>LDYA fd`
`>SYSCALL mkdev
## RETURN VALUE
A = hDEV
# OpenDir
## C
`int hDIR opendir (const char * dirpath);`
## ASM
`>LDYA dirpath`
`>SYSCALL opendir`
## RETURN VALUE
CC : success
A = hDIR
CS : error
A = EC
# ReadDir
## C
`int readdir (int hDIR, S.DIRENT * dirent);`
## ASM
`>PUSHW dirent`
`lda hDIR`
`>SYSCALL readdir`
## RETURN VALUE
CC : success
X = hDIRENT
Y,A = PTR to S.DIRENT
CS : error
A = EC
note : A = 0 means no more entry
# CloseDir
## C
`void closedir(hDIR);`
## ASM
`lda hDIR`
`>SYSCALL closedir`
## RETURN VALUE
none, always succeed.
# ExpandStr
**In:**
Y,A = PTR to String to Expand (C-String)
## RETURN VALUE
X = hMem to Expanded String (C-String)
Y,A = PTR to Expanded String
# FileSearch
Search a file in the provided PATH list
And return, if found, the full path to it.
## C
`int filesearch ( char * filename, char * searchpath, char * fullpath, stat * filestat);`
## ASM
**In:**
`>PUSHWI filestat`
`>PUSHWI fullpath`
`>PUSHWI searchpath`
`>LDYAI filename`
## RETURN VALUE
CC : success
DstBuf = FilePath
DstStat = S.STAT
CS : not found
# PutEnv
Change or add an environment variable, string is 'NAME=VALUE'
## C
`int putenv(char *string);`
## ASM
**In:**
`>LDYA string`
`>SYSCALL putenv`
## RETURN VALUE
# SetEnv
Change or add an environment variable
## C
`int setenv(const char *name, const char *value);`
## ASM
**In:**
`>PUSHW value`
`>LDYA name`
`>SYSCALL setenv`
## RETURN VALUE
# GetEnv
searches the environment list to find the environment variable name,
and returns a pointer to the corresponding value string.
## C
`char *getenv(const char *name);`
## ASM
**In:**
`>LDYA name`
`>SYSCALL getenv`
## RETURN VALUE
CC : Y,A = PTR to VALUE (C-String)
CS : not found
# UnsetEnv
Remove an environment variable
## C
`int unsetenv(const char *name);`
## ASM
**In:**
`>LDYA name`
`>SYSCALL unsetenv`
## RETURN VALUE
# LoadTxtFile
Load TXT a file in memory (with ending 0)
## C
`int loadtxtfile ( const char * filename, short int flags, short int ftype, int auxtype );`
## ASM
**In:**
`>PUSHW auxtype`
`>PUSHB ftype`
`>PUSHB flags`
`>LDYA filename`
`>SYSCALL loadtxtfile`
## RETURN VALUE
Y,A = File Length (without ending 0)
X = hMem of Loaded File
# LoadFile
Load a file in memory
## C
`int loadfile ( const char * filename, short int flags, short int ftype, int auxtype );`
## ASM
**In:**
`>PUSHW auxtype`
`>PUSHB ftype`
`>PUSHB flags`
`>LDYA filename`
`>SYSCALL loadfile`
## RETURN VALUE
Y,A = File Length
X = hMem of Loaded File
# ChTyp
Change The type of a ProDOS File
## C
`int chtyp(const char *filepath, const char filetype);`
## ASM
**In:**
`>PUSHBI filetype`
`>LDYA filepath`
`>SYSCALL chtyp`
## RETURN VALUE
# ChMod
**In:**
PUSHW = UID
PUSHW = PATH
# ChOwn
**In:**
PUSHW = mod
PUSHW = PATH
# ChGrp
**In:**
PUSHW = GID
PUSHW = PATH
# open
## C
`hFD open(const char *pathname, short int flags);`
## ASM
**In:**
`>PUSHB flags`
`>LDYA pathname`
`>SYSCALL open`
## RETURN VALUE
A = hFD
REG File created on ProDOS : T=TXT,X=$0000
# close
## C
`int close(hFD fd);`
## ASM
**In:**
`lda fd`
`>SYSCALL close`
# read
## C
`int read(hFD fd, void *buf, int count);`
## ASM
**In:**
`>PUSHWI count`
`>PUSHW buf`
`lda fd`
`>SYSCALL read`
## RETURN VALUE
CC: Y,A = bytes read
CS: A = EC
# write
## C
`int write(hFD fd, const void *buf, int count);`
## ASM
**In:**
`>PUSHWI count`
`>PUSHW buf`
`lda fd`
`>SYSCALL write`
## RETURN VALUE
CC: Y,A = bytes written
CS: A = EC
# IOCTL
## C
`int ioctl(short int hFD, int request, void * param );`
## ASM
`PUSHWI param`
`PUSHBI request`
`lda hFD`
`>SYSCALL IOCTL`
## RETURN VALUE
Y,A = ...
# pipe
## C
`int pipe(int pipefd[2]);`
## ASM
# FAdd,FSub,FMult,FDiv,FPwr
Return X+Y, X-Y, X*Y, X/Y, X^Y
## ASM
**In:**
`>PUSHF X (float)`
`>PUSHF Y (float)`
`>SYSCALL fadd`
`>SYSCALL fsub`
`>SYSCALL fmult`
`>SYSCALL fdiv`
`>SYSCALL fpwr`
## RETURN VALUE
On stack (float)
# Log,Sqr,Exp,Cos,Sin,Tan,ATan
Return Log(x), Sqr(x), E^X, Cos(x), Sin(X), Tan(x), ATan(x)
## C
`float log ( float x);`
`float sqr ( float x);`
`float exp ( float x);`
`float cos ( float x);`
`float sin ( float x);`
`float tan ( float x);`
`float atan ( float x);`
## ASM
**In:**
`>PUSHF x (Float)`
`>SYSCALL log`
## RETURN VALUE
On stack (Float)
# float
Return 'floated' long
## C
`float f = (float)12345678;
## ASM
**In:**
`>PUSHL X` (long)
## RETURN VALUE
On stack (float)
# lrintf
Return float rounded into a long
## C
`long int lrintf (float x);`
## ASM
**In:**
`>PUSHF x`
`>SYSCALL lrintf`
## RETURN VALUE
On stack (long)
# GetMem0
Y,A = Size Requested
## RETURN VALUE
CC : success
YA = PTR to Mem (ZERO Initialised)
* X = hMem
CS :
A = EC
# GetMem
Y,A = Size Requested
## RETURN VALUE
CC : success
YA = PTR to Mem (Uninitialised)
* X = hMem
CS :
A = EC
# FreeMem
A = hMem To Free
## RETURN VALUE
none.
(X unmodified)
# GetMemPtr
A = hMem
## RETURN VALUE
Y,A = PTR to MemBlock
(X unmodified)
# GetMemByID
A = hMem
## RETURN VALUE
Y,A = ZPMemMgrSPtr = PTR to S.MEM
(X unmodified)
# GetMemStat
**In:**
Y,A = Ptr to 24 bytes buffer
## RETURN VALUE
Buffer filled with memory stats
# SListGetByID
PUSHB = hSList
PUSHW = KeyID
PUSHW = Data Ptr
PUSHW = Key Ptr
## RETURN VALUE
X,Y = Next KeyID
# SListUpdateByID
PUSHB = hSList
PUSHW = KeyID
PUSHW = Data Ptr
## RETURN VALUE
A = Key Length
X,Y = KeyID
# SListAdd
PUSHB = hSList
PUSHW = Key Ptr
PUSHW = Data Ptr
## RETURN VALUE
A = Key Length
X,Y = KeyID
# SListLookup
PUSHB = hSList
PUSHW = Key Ptr
PUSHW = Data Ptr
## RETURN VALUE
A = Key Length
X,Y = KeyID
# SListNew
## RETURN VALUE
A=hSList
# SListFree
A=hSList
## RETURN VALUE
# GetStkObjProp
A = hObject (AUX Memory)
Y = Property Index
## RETURN VALUE
Y,A = Property Value
# NewStkObj
Y,A = Size Requested
## RETURN VALUE
CC : success
YA = PTR to Mem (Uninitialised)
* X = hMem
CS :
A = EC
# FreeStkObj
A = hMem To Free (AUX Memory)
## RETURN VALUE
none.
(X,Y unmodified)
# LoadStkObj
Load a file in AUX memory (Stock Objects)
PUSHW = AUXTYPE (Handled by....
PUSHB = TYPE ...
PUSHB = MODE ...
PUSHW = PATH ...FOpen)
## RETURN VALUE
Y,A = File Length
X = hMem of Loaded Object in AUX mem
# ExecL
## C
`int execl(const char* cmdline, short int flags);`
## ASM
`>PUSHB flags`
`>LDYA cmdline`
`>SYSCALL execl`
## RETURN VALUE
A = Child PSID
# ExecV
## C
`int exec(const char* argv[], short int flags);`
## ASM
`>PUSHB flags`
`>LDYA argv`
`>SYSCALL execv`
## RETURN VALUE
A = Child PSID
# ExecL
## C
`int kill(short int pid, short int sig);`
## ASM
`>PUSHB sig`
`lda pid`
`>SYSCALL kill`
## RETURN VALUE
A = Child PSID
# Stat
Return information about a file
## C
`int stat(const char *pathname, struct stat *statbuf);`
## ASM
**In:**
`>PUSHW statbuf`
`>LDYA pathname`
`>SYSCALL stat`
## RETURN VALUE
# MKDir
create a directory
## C
`int mkdir(const char *pathname, int mode);`
## ASM
**In:**
`>PUSHW mode`
`>LDYA pathname`
`>SYSCALL mkdir`
## RETURN VALUE
CC : success
CS : error
A = EC
# MkNod
Create a special or ordinary file.
(CDEV, BDEV, DSOCKS, SSOCK, PIPE)
## C
`hFILE mknod(const char *pathname, int mode, hFD fd);`
## ASM
**In:**
`>PUSHB fd`
`>PUSHW mode`
`>LDYA pathname`
`>SYSCALL mknod`
## RETURN VALUE
CC = OK, CS = ERROR
A = hFILE
# MKFIFO
return a hFILE to a new FIFO
## C
`hFILE mkfifo(const char *pathname, int mode);`
## ASM
**In:**
`>PUSHW mode`
`>LDYA pathname`
`>SYSCALL mkfifo`
## RETURN VALUE
CC = OK, CS = ERROR
A = hFILE
# PutChar
Print A (char) to StdOut
## C
`int putchar ( int character );`
## ASM
**In:**
`lda caracter`
`>SYSCALL putchar`
## RETURN VALUE
CC = success
# FPutC
Print A (char) to hFILE
## C
`int fputc ( hFILE stream , int character );`
## ASM
**In:**
`>PUSHB character`
`lda stream`
`>SYSCALL fputc`
## RETURN VALUE
CC = success
# PutS
Write Str to StdOut, appends '\r\n'
## C
`int puts ( const char * str );`
**In:**
## ASM
`>LDYAI str`
`>SYSCALL puts`
## RETURN VALUE
CC = success
# FPutS
Write Str to FILE
## C
`int fputs (hFILE stream, const char * str );`
## ASM
**In:**
`>PUSHW str`
`lda stream`
`>SYSCALL fputs`
## RETURN VALUE
CC = success
# PrintF/SPrintF/FPrintF
Prints C-Style String
## C
`int printf ( const char * format, ... );`
`int fprintf ( hFILE stream, const char * format, ... );`
`int sprintf ( char * str, const char * format, ... );`
## ASM
**In:**
PrintF : (example is for printing Y,A as integer : format="%I", 2 bytes)
`>PUSHYA`
`...`
`>PUSHBI bytecount`
`>LDYAI format`
`>SYSCALL printf`
SPrintF :
`>PUSHYA`
`...`
`>PUSHBI bytecount`
`>PUSHWI format`
`>LDYAI str`
`>SYSCALL sprintf`
FPrintF :
`>PUSHYA`
`...`
`>PUSHBI bytecount`
`>PUSHWI format`
`lda hFILE`
`>SYSCALL fprintf`
## RETURN VALUE
CC : success, Y,A = bytes sent
CS : error, A = code from Output
Specifiers :
+ %b : pull 1 byte to Print BIN
+ %B : pull 2 bytes to Print BIN
+ %d : pull 1 byte unsigned DEC 0..255
+ %D : pull 2 bytes unsigned DEC 0..65535
+ %u : pull 4 bytes long unsigned DEC 0..4294967295
+ %e : pull 5 Bytes float (-)1.23456789e+12
+ %f : pull 5 Bytes float (-)3.1415
+ %h : pull 1 byte to Print HEX
+ %H : pull 2 bytes to Print HEX
+ %i : pull 1 byte to Print signed DEC -128..127
+ %I : pull 2 bytes to Print signed DEC -32768..32767
+ %L : pull 4 bytes signed DEC -2147483648..2147483647
+ %n : pull 1 byte to Print low Nibble HEX
+ %N : pull 1 byte to Print high Nibble HEX
+ %s : pull 2 bytes ptr to C-Style String
+ %S : pull 2 bytes ptr to P-Style String
+ \b : Print 'BS' (08)
+ \e : Print 'ESC' ($1B,27)
+ \f : Print 'FF' ($0C,12)
+ \n : Print 'LF' ($0A,10)
+ \r : Print 'CR' ($0D,13)
+ \\\\ : Print \
+ \\% : Print %
Modifiers for len and padding :
+ %d : '9' '12'
+ %2d : ' 9' '12'
+ %02d : '09' '12'
+ %11s : 'ABCDEFGH '
+ %011s : 'ABCDEFGH000'
+ %2f : '3.14'
# FGetS
read bytes from stream into the array
pointed to by s, until n-1 bytes are read, or a <newline> is read and
transferred to s, or an end-of-file condition is encountered. The
string is then terminated with a null byte.
## C
`char *fgets(hFILE stream, char * s, int n);`
## ASM
**In:**
`>PUSHW n`
`>PUSHW s`
`lda hFILE`
`>SYSCALL fgets`
## RETURN VALUE
Y,A: s
CC = success
# GetChar
Get char from StdIn
## C
`int getchar ();`
## ASM
**In:**
`>SYSCALL getchar`
## RETURN VALUE
CC = success
A = char
# GetC
Get char from Node
## C
`int getc ( hFILE stream );`
## ASM
**In:**
`lda stream`
`>SYSCALL getc`
## RETURN VALUE
CC = success
A = char
# SScanF
Read formatted data from string
## C
`int sscanf ( const char * s, const char * format, ... );`
## ASM
**In:**
`>PUSHW ptr`
`...`
`>PUSHBI bytecount`
`>PUSHWI format`
+ %i : short int
+ %d : byte
+ %I : int
+ %D : word
+ %L : long int
+ %U : dword
+ %h : HEX byte
+ %H : HEX word
+ %s : string
TODO : %10s
`>LDYA s`
`>SYSCALL sscanf`
## RETURN VALUE
A = Number of arguments filled.
# FOpen
Open a file
## C
`hFILE fopen ( const char * filename, short int flags, short int ftype, int auxtype );`
**In:**
## ASM
`>PUSHWI auxtype`
`>PUSHBI ftype`
`>PUSHBI flags`
+ O.RDONLY : if R and exists -> ERROR
+ O.WRONLY : if W and exists -> CREATE
+ O.TRUNC : Reset Size To 0
+ O.APPEND : Append
+ O.TEXT : Open/Append in Text mode
+ O.CREATE : Create if not exists
TODO: replace flags/ftype/auxtype with mode="w+,t=TYP,x=AUXTYPE"
+ r = O_RDONLY
+ r+ = O_RDWR
+ w = O_WRONLY | O_CREAT | O_TRUNC
+ w+ = O_RDWR | O_CREAT | O_TRUNC
+ a = O_WRONLY | O_CREAT | O_APPEND
+ a+ = O_RDWR | O_CREAT | O_APPEND
+ ,t=123 or t=$ff or t=TXT
+ ,x=12345 or x=$ffff
`>LDYAI filename`
## RETURN VALUE
CC : A = hFILE
CS : A = EC
# FClose
Close a file
## C
int fclose ( hFILE stream );
## ASM
**In:**
`lda stream`
`>SYSCALL fclose`
## RETURN VALUE
# FRead
Read bytes from file
## C
int fread (hFILE stream, void * ptr, int count );
## ASM
**In:**
`>PUSHWI count`
`>PUSHW ptr`
`lda stream`
`>SYSCALL fread`
## RETURN VALUE
Y,A = Bytes Read
# FWrite
Write bytes to file
## C
`int fwrite (hFILE stream, const void * ptr, int count );`
## ASM
**In:**
`>PUSHWI count`
`>PUSHW ptr`
`lda stream`
`>SYSCALL fwrite`
## RETURN VALUE
Y,A = Bytes Written
# FFlush
## C
int fflush(hFILE stream);
## ASM
**In:**
`lda stream`
`>SYSCALL fflush`
# FSeek
Set the file-position indicator for hFILE
## C
`int fseek(hFILE stream, long offset, short int whence);`
## ASM
**In:**
`>PUSHBI whence`
`>PUSHL offset`
`lda stream`
`>SYSCALL fseek`
# FEOF
Test the end-of-file indicator for hFILE
## C
`int feof(hFILE stream);`
## ASM
**In:**
`lda stream`
`>SYSCALL feof`
## RETURN VALUE
CC :
A=0 EOF
A =0 NOT EOF
CS :
# FTell
Return the current value of the file-position indicator
## C
`long ftell(hFILE stream);`
## ASM
**In:**
`lda stream`
`>SYSCALL ftell`
## RETURN VALUE
On stack (long)
# Remove
Remove a file or directory
## C
int remove(const char *pathname);
## ASM
**In:**
`>LDYA pathname`
`>SYSCALL remove`
## RETURN VALUE
# Rename
Rename a file
## C
`int rename(const char *oldpath, const char *newpath);`
## ASM
**In:**
`>PUSHW newpath`
`>LDYA oldpath`
`>SYSCALL rename`
## RETURN VALUE
# strtof
Convert String to 40 bits Float
## C
`float strtof (const char* str, char** endptr);`
## ASM
**In:**
`>PUSHWI EndPtr`
`>LDYA str`
`>SYSCALL strtof`
## RETURN VALUE
On stack (float)
# AToF
Convert String to 40 bits Float
## C
`float atof (const char* str);`
## ASM
**In:**
`>LDYA str`
`>SYSCALL atof`
## RETURN VALUE
On stack (float)
# StrToL/StrToUL
Convert String to 32 bits (unsigned) int
## C
`long strtol (const char* str, char** endptr, int base);`
`unsigned long strtoul (const char* str, char** endptr, int base);`
## ASM
**In:**
`>PUSHB Base`
`>PUSHWI EndPtr`
`>LDYAI str`
`>SYSCALL strtol`
## RETURN VALUE
On stack (long)
# atol
Convert String to 32 bits long
## C
`long atol ( const char * str );`
## ASM
**In:**
`>LDYA str`
`>SYSCALL atol`
## RETURN VALUE
On stack (long)
# atoi
Convert String to 16 bits int
## C
`int atoi ( const char * str );`
## ASM
**In:**
`>LDYAI str`
`>SYSCALL atoi`
## RETURN VALUE
Y,A = int
# RealPath
Return the canonicalized absolute pathname
## C
`unsigned short int realpath (const char* str);`
## ASM
**In:**
`>LDYA str`
`>SYSCALL realpath`
## RETURN VALUE
CC : success
Y,A = Ptr to Full Path (C-String)
X = hMem of Full Path
CS : A = Error Code
# StrLen
Returns Length of C-String
## C
`int strlen ( char * str);`
## ASM
`>LDYAI str`
`>SYSCALL strlen`
## RETURN VALUE
Y,A = String length
# StrCat
Concatenate strings
## C
`char * strcat ( char * destination, const char * source );`
## ASM
**In:**
`>PUSHWI source`
`>LDYAI destination`
`>SYSCALL strcat`
## RETURN VALUE
Y,A = destination
# StrCpy
Copy string
## C
`char * strcpy ( char * destination, const char * source );`
## ASM
**In:**
`>PUSHWI source`
`>LDYAI destination`
`>SYSCALL strcpy`
## RETURN VALUE
Y,A = destination
# StrDup
Create a new copy of this C-String
Y,A = Ptr to source C-String
## RETURN VALUE
CC : success
Y,A = PTR to String
X = hMem (PSTR)
CS : error
A = SYS error code
# StrUpr/StrLwr
Convert string to UPPERCASE/lowercase
## C
`int strupr ( char * str);`
`int strlwr ( char * str);`
## ASM
**In:**
`>LDYAI str`
`>SYSCALL strupr`
`>SYSCALL strlwr`
## RETURN VALUE
Uppercased/lowercased String in Buffer
Y,A = str
# StrCmp
Compare 2 strings
## C
`int strcmp(const char *s1, const char *s2);`
## ASM
**In:**
`>PUSHWI s2`
`>LDYAI s1`
`>SYSCALL strcmp`
## RETURN VALUE
CC : match
CS : no match
CC, Y,A=0
CS, Y,A > 0 or < 0
# StrCaseCmp
Compare 2 strings, ignoring case
## C
`int strcasecmp(const char *s1, const char *s2);`
## ASM
**In:**
`>PUSHWI s2`
`>LDYAI s1`
`>SYSCALL strcasecmp`
## RETURN VALUE
CC : match
CS : no match
CC, Y,A=0
CS, Y,A > 0 or < 0
# Time
Get System Time in Buffer
## C
`time_t time (S.TIME* timer);`
## ASM
`>LDYA timer`
`>SYSCALL time`
## RETURN VALUE
S.TIME filled with System date/time
# PTime2Time
Convert ProDOS Time To S.TIME
## C
`int PTime2Time (long* ptime, S.TIME* timer);`
## ASM
`>PUSHW timer`
`>LDYA ptime`
`>SYSCALL PTime2Time`
## RETURN VALUE
# CTime2Time
Convert CTime Time To S.TIME
## C
`int CTime2Time (long* ctime, S.TIME* timer);`
## ASM
`>PUSHW timer`
`>LDYA ctime`
`>SYSCALL CTime2Time`
## RETURN VALUE
# StrFTime
## C
Convert S.TIME struct to CSTR
`size_t strftime (char* ptr, const char* format, const struct S.TIME* timeptr );`
## ASM
`PUSHW timeptr`
`PUSHW format`
+ %a : Abbreviated weekday name : Thu
+ %A : Full weekday name : Thursday
+ %b : Abbreviated month name : Aug
+ %B : Full month name : August
+ %d : Day of the month, zero-padded (01-31)
+ %H : Hour in 24h format (00-23) 14
+ %I : Hour in 12h format (01-12) 02
+ %m : Month as a decimal number (01-12) 08
+ %M : Minute (00-59) 55
+ %p : AM or PM designation PM
+ %S : Second (00-61) 02
+ %w : Weekday as a decimal number with Sunday as 0 (0-6)
+ %y : Year, last two digits (00-99)
+ %Y : Year four digits 2001
`>LDYA ptr`
`>SYSCALL strftime`
## RETURN VALUE
none. always succeed.