binread/binwrite/sockbinread/sockbinwrite/memalloc/memrelease/filesize

Author: braindigitalis

docpages/basic-language-reference/functions/integer/02_INDEX.md

@@ -21,6 +21,7 @@ The following functions operate on or return **integer values** in Retro Rocket
 * \subpage DAY
 * \subpage EOF
 * \subpage EXISTSVARI
+* \subpage FILESIZE
 * \subpage GETNAMECOUNT
 * \subpage GETPROCCOUNT
 * \subpage GETPROCCPUID
@@ -40,6 +41,7 @@ The following functions operate on or return **integer values** in Retro Rocket
 * \subpage LCPUID
 * \subpage LEN
 * \subpage LGETLASTCPUID
+* \subpage MEMALLOC
 * \subpage MEMFREE
 * \subpage MEMORY
 * \subpage MEMPEAK

docpages/basic-language-reference/functions/integer/FILESIZE.md

@@ -0,0 +1,38 @@
+\page FILESIZE FILESIZE Function
+
+```basic
+FILESIZE(string-expression)
+```
+
+Returns the **size of a file** in **bytes**.
+The parameter is a path to a file (absolute or relative to \ref CSD "CSD\$").
+
+---
+
+### Examples
+
+```basic
+PRINT FILESIZE("/system/webserver/index.html")
+```
+
+```basic
+REM Guard against missing files
+path$ = "data.bin"
+IF FILETYPE$(path$) = "file" THEN
+    PRINT "Size = "; FILESIZE(path$); " bytes"
+ELSE
+    PRINT "Not a regular file"
+ENDIF
+```
+
+---
+
+### Notes
+
+* Raises an error if the path does not exist or refers to a directory.
+* Result is a 64-bit integer (bytes).
+
+---
+
+**See also:**
+\ref FILETYPE "FILETYPE$" · \ref OPENIN "OPENIN" · \ref READ "READ$" · \ref BINREAD "BINREAD"

docpages/basic-language-reference/functions/integer/MEMALLOC.md

@@ -0,0 +1,30 @@
+\page MEMALLOC MEMALLOC Function
+
+```basic
+MEMALLOC(integer-expression)
+```
+
+Allocates a block of **heap memory** of the given size (in bytes) and returns a **pointer/integer handle** to it.
+
+---
+
+### Examples
+
+```basic
+size = FILESIZE("/system/webserver/logo.png")
+buf  = MEMALLOC(size)
+REM ... use buf with BINREAD / SOCKBINWRITE ...
+MEMRELEASE buf
+```
+
+---
+
+### Notes
+
+* Contents are unspecified on allocation.
+* Always pair with \ref MEMRELEASE "MEMRELEASE" to avoid leaks.
+* Returned handle is suitable for binary I/O (\ref BINREAD "BINREAD", \ref BINWRITE "BINWRITE", \ref SOCKBINWRITE "SOCKBINWRITE", \ref SOCKBINREAD "SOCKBINREAD").
+
+**See also:**
+\ref MEMRELEASE "MEMRELEASE" · \ref BINREAD "BINREAD" · \ref BINWRITE "BINWRITE"
+

docpages/basic-language-reference/keywords/00_INDEX.md

@@ -41,6 +41,8 @@ The following parameter types are used throughout this documentation:
 
 * \subpage AUTOFLIP
 * \subpage BACKGROUND
+* \subpage BINREAD
+* \subpage BINWRITE
 * \subpage BITAND
 * \subpage BITEOR
 * \subpage BITNAND
@@ -88,6 +90,7 @@ The following parameter types are used throughout this documentation:
 * \subpage LIBRARY
 * \subpage LINE
 * \subpage LOCAL
+* \subpage MEMRELEASE
 * \subpage MKDIR
 * \subpage MOUNT
 * \subpage NEXT
@@ -119,6 +122,8 @@ The following parameter types are used throughout this documentation:
 * \subpage SETVARR
 * \subpage SETVARS
 * \subpage SLEEP
+* \subpage SOCKBINREAD
+* \subpage SOCKBINWRITE
 * \subpage SOCKCLOSE
 * \subpage SOCKFLUSH
 * \subpage SOCKREAD

docpages/basic-language-reference/keywords/BINREAD.md

@@ -0,0 +1,40 @@
+\page BINREAD BINREAD Statement
+
+```basic
+BINREAD(integer-handle, integer-buffer, integer-length)
+```
+
+Reads **binary data** from an **open file** into memory.
+
+* `integer-handle` — file handle from \ref OPENIN "OPENIN" or \ref OPENUP "OPENUP".
+* `integer-buffer` — destination memory handle/pointer (from \ref MEMALLOC "MEMALLOC").
+* `integer-length` — number of bytes to read.
+
+---
+
+### Examples
+
+```basic
+fh  = OPENIN("asset.bin")
+size = FILESIZE("asset.bin")
+buf  = MEMALLOC(size)
+
+BINREAD fh, buf, size
+
+REM ... use buffer ...
+MEMRELEASE buf
+CLOSE fh
+```
+
+---
+
+### Notes
+
+* Use \ref FILESIZE "FILESIZE" to size your buffer appropriately.
+* Binary-safe (no line translation).
+* Reading past end of file yields fewer bytes or an error, depending on context; check with \ref EOF "EOF" as needed.
+
+---
+
+**See also:**
+\ref OPENIN "OPENIN" · \ref OPENUP "OPENUP" · \ref FILESIZE "FILESIZE" · \ref EOF "EOF" · \ref MEMALLOC "MEMALLOC"

docpages/basic-language-reference/keywords/BINWRITE.md

@@ -0,0 +1,36 @@
+\page BINWRITE BINWRITE Statement
+
+```basic
+BINWRITE(integer-handle, integer-buffer, integer-length)
+```
+
+Writes **binary data** from memory to an **open file**.
+
+* `integer-handle` — file handle from \ref OPENOUT "OPENOUT" or \ref OPENUP "OPENUP".
+* `integer-buffer` — source memory handle/pointer (from \ref MEMALLOC "MEMALLOC" or other).
+* `integer-length` — number of bytes to write.
+
+---
+
+### Examples
+
+```basic
+fh  = OPENOUT("copy.bin")
+buf = MEMALLOC(1024)
+REM ... fill buf with data ...
+BINWRITE fh, buf, 1024
+CLOSE fh
+MEMRELEASE buf
+```
+
+---
+
+### Notes
+
+* Binary-safe; writes bytes exactly as stored in memory.
+* Ensure the file was opened with appropriate mode (\ref OPENOUT "OPENOUT" to create/overwrite, \ref OPENUP "OPENUP" to update).
+
+---
+
+**See also:**
+\ref OPENOUT "OPENOUT" · \ref OPENUP "OPENUP" · \ref MEMALLOC "MEMALLOC" · \ref MEMRELEASE "MEMRELEASE"

docpages/basic-language-reference/keywords/MEMRELEASE.md

@@ -0,0 +1,29 @@
+\page MEMRELEASE MEMRELEASE Function
+
+```basic
+MEMRELEASE(integer-expression)
+```
+
+Releases (frees) a block of memory previously obtained via \ref MEMALLOC "MEMALLOC".
+
+---
+
+### Examples
+
+```basic
+buf = MEMALLOC(65536)
+REM ... use buf ...
+MEMRELEASE buf
+```
+
+---
+
+### Notes
+
+* Passing an invalid or already-freed handle raises an error.
+* After releasing, set your variable to `0` if you want to avoid accidental reuse.
+
+---
+
+**See also:**
+\ref MEMALLOC "MEMALLOC"

docpages/basic-language-reference/keywords/SOCKBINREAD.md

@@ -0,0 +1,35 @@
+\page SOCKBINREAD SOCKBINREAD Statement
+
+```basic
+SOCKBINREAD(integer-socket, integer-buffer, integer-length)
+```
+
+Reads **binary data** from a **connected socket** into memory.
+
+* `integer-socket` — socket file descriptor.
+* `integer-buffer` — destination memory handle/pointer (from \ref MEMALLOC "MEMALLOC").
+* `integer-length` — maximum number of bytes to read.
+
+---
+
+### Examples
+
+```basic
+buf = MEMALLOC(4096)
+SOCKBINREAD client, buf, 4096
+REM ... process buffer ...
+MEMRELEASE buf
+```
+
+---
+
+### Notes
+
+* Reads up to the specified number of bytes into the buffer.
+* Use \ref SOCKSTATUS "SOCKSTATUS" to detect disconnects.
+* Pair with \ref MEMALLOC "MEMALLOC" / \ref MEMRELEASE "MEMRELEASE" for buffer management.
+
+---
+
+**See also:**
+\ref SOCKREAD "SOCKREAD" · \ref SOCKWRITE "SOCKWRITE" · \ref MEMALLOC "MEMALLOC" · \ref MEMRELEASE "MEMRELEASE"

docpages/basic-language-reference/keywords/SOCKBINWRITE.md

@@ -0,0 +1,40 @@
+\page SOCKBINWRITE SOCKBINWRITE Statement
+
+```basic
+SOCKBINWRITE(integer-socket, integer-buffer, integer-length)
+```
+
+Writes **binary data** from memory to a **connected socket**.
+
+* `integer-socket` — socket file descriptor (e.g. from \ref CONNECT "CONNECT" or \ref SOCKACCEPT "SOCKACCEPT").
+* `integer-buffer` — memory handle/pointer returned by \ref MEMALLOC "MEMALLOC".
+* `integer-length` — number of bytes to write.
+
+---
+
+### Examples
+
+```basic
+size = FILESIZE(file$)
+buf  = MEMALLOC(size)
+BINREAD fh, buf, size
+
+SOCKWRITE client, "Content-Length: "; size; CHR$(13); CHR$(10); CHR$(13); CHR$(10);
+SOCKBINWRITE client, buf, size
+SOCKFLUSH client
+
+MEMRELEASE buf
+```
+
+---
+
+### Notes
+
+* Intended for sending file contents or other raw buffers.
+* Socket must be connected; use \ref SOCKSTATUS "SOCKSTATUS" to check.
+* May write less than requested if the peer closes; handle errors accordingly.
+
+---
+
+**See also:**
+\ref SOCKREAD "SOCKREAD" · \ref SOCKWRITE "SOCKWRITE" · \ref SOCKSTATUS "SOCKSTATUS" · \ref BINREAD "BINREAD" · \ref MEMALLOC "MEMALLOC"

src/basic/sockets.c

@@ -331,7 +331,7 @@ void sockbinwrite_statement(struct basic_ctx* ctx) {
 	accept_or_return(COMMA, ctx);
 	uint64_t buffer_pointer = expr(ctx);
 	accept_or_return(COMMA, ctx);
-	int length = expr(ctx);
+	int64_t length = expr(ctx);
 	if (length && !address_valid_read(buffer_pointer, length)) {
 		tokenizer_error_printf(ctx, "Invalid address: %016lx", buffer_pointer);
 		return;