Utilities: Make syscall(1) explain what it's doing

AK/Debug.h.in

@@ -350,6 +350,10 @@
 #cmakedefine01 SYNTAX_HIGHLIGHTING_DEBUG
 #endif
 
+#ifndef SYSCALL_1_DEBUG
+#cmakedefine01 SYSCALL_1_DEBUG
+#endif
+
 #ifndef SYSTEM_MENU_DEBUG
 #cmakedefine01 SYSTEM_MENU_DEBUG
 #endif

Meta/CMake/all_the_debug_macros.cmake

@@ -166,6 +166,7 @@ set(DEBUG_SPAM ON)
 set(DEBUG_CPP_LANGUAGE_SERVER ON)
 set(DEBUG_AUTOCOMPLETE ON)
 set(FILE_WATCHER_DEBUG ON)
+set(SYSCALL_1_DEBUG ON)
 
 # False positive: DEBUG is a flag but it works differently.
 # set(DEBUG ON)

Userland/Utilities/syscall.cpp

@@ -24,7 +24,9 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+#include <AK/Debug.h>
 #include <AK/Iterator.h>
+#include <AK/LogStream.h>
 #include <AK/Vector.h>
 #include <LibCore/ArgsParser.h>
 #include <mman.h>
@@ -50,9 +52,20 @@ int main(int argc, char** argv)
     Vector<const char*> arguments;
 
     Core::ArgsParser args_parser;
+    args_parser.set_general_help(
+        "Enables you to do a direct syscall, even those that use a 'SC_*_params' buffer.\n"
+        "Arguments can be literal strings, numbers, the output buffer, or parameter buffers:\n"
+        " - Arguments that begin with a comma are stripped of the comma and treated as string arguments, for example ',0x0' or ',['.\n"
+        " - 'buf' is replaced by a pointer to the output buffer.\n"
+        " - Numbers can be written like 1234 or 0xDEADC0DE.\n"
+        " - Parameter buffer (e.g. SC_realpath_params) can be passed by wrapping them in '[' and ']'. Note that '[' and ']' must be separate arguments to syscall(1). Buffers can be used recursively.\n"
+        " - The first argument may also be any syscall function name. Run 'syscall -l' to see the list.\n"
+        " - Arguments that cannot be interpreted are treated as string arguments, for example 'Hello, friends!'.\n"
+        "\n"
+        "Full example: syscall -o realpath [ /usr/share/man/man2/getgid.md 1024 buf 1024 ]");
     args_parser.add_option(output_buffer, "Output the contents of the buffer (beware of stray zero bytes!)", "output-buffer", 'o');
     args_parser.add_option(list_syscalls, "List all existing syscalls", "list-syscalls", 'l');
-    args_parser.add_positional_argument(arguments, "Syscall arguments; can be a string, 'buf' for the output buffer, or numbers like 1234 or 0xffffffff, or a buffer that must begin with '[' and end with ']'. If the first character is ',' (comma), the argument is interpreted as a string, no matter what. This is useful if the string is '[' or '0x0'.", "syscall-arguments");
+    args_parser.add_positional_argument(arguments, "Syscall arguments; see general help.", "syscall-arguments");
     args_parser.parse(argc, argv);
 
     ArgIter iter = arguments.begin();
@@ -60,7 +73,7 @@ int main(int argc, char** argv)
         arg[i] = parse_from(iter);
     }
     if (!iter.is_end()) {
-        fprintf(stderr, "Too many arguments (did you want to use '[ parameter buffers ]'?)\n");
+        warnln("Too many arguments (did you want to use '[ parameter buffers ]'?)");
         return -1;
     }
 
@@ -72,18 +85,19 @@ int main(int argc, char** argv)
             }
         }
         if (arg[0] > Syscall::Function::__Count) {
-            fprintf(stderr, "Invalid syscall entry %s\n", (char*)arg[0]);
+            warnln("Invalid syscall entry {}", (char*)arg[0]);
             return -1;
         }
     }
 
+    dbgln_if(SYSCALL_1_DEBUG, "Calling {} {:p} {:p} {:p}\n", arg[0], arg[1], arg[2], arg[3]);
     int rc = syscall(arg[0], arg[1], arg[2], arg[3]);
     if (rc == -1)
         perror("syscall");
     if (output_buffer)
         fwrite(outbuf, 1, sizeof(outbuf), stdout);
 
-    fprintf(stderr, "Syscall return: %d\n", rc);
+    warnln("Syscall return: {}", rc);
     return 0;
 }
 
@@ -99,6 +113,17 @@ static FlatPtr as_buf(Vector<FlatPtr> params_vec)
     // It's probably good to ensure zero-initialization.
     memset(buf, 0, buf_size);
     memcpy(buf, params_vec.data(), params_size);
+
+    if constexpr (SYSCALL_1_DEBUG) {
+        StringBuilder builder;
+        builder.append("Prepared [");
+        for (size_t i = 0; i < params_vec.size(); ++i) {
+            builder.appendff(" {:p}", params_vec[i]);
+        }
+        builder.appendff(" ] at {:p}", (FlatPtr)buf);
+        dbgln(builder.to_string());
+    }
+
     // Leak the buffer here. We need to keep it until the special syscall happens,
     // and we terminate immediately afterwards anyway.
     return (FlatPtr)buf;
@@ -127,8 +152,11 @@ static FlatPtr parse_from(ArgIter& iter)
     ++iter;
 
     // Is it a forced literal?
-    if (this_arg[0] == ',')
+    if (this_arg[0] == ',') {
-        return (FlatPtr)(this_arg + 1);
+        this_arg += 1;
+        dbgln_if(SYSCALL_1_DEBUG, "Using (forced) string >>{}<< at {:p}", this_arg, (FlatPtr)this_arg);
+        return (FlatPtr)this_arg;
+    }
 
     // Is it the output buffer?
     if (strcmp(this_arg, "buf") == 0)
@@ -149,5 +177,7 @@ static FlatPtr parse_from(ArgIter& iter)
     if (strcmp(this_arg, "]") == 0)
         fprintf(stderr, "Warning: Treating unmatched ']' as literal string\n");
 
+    dbgln_if(SYSCALL_1_DEBUG, "Using (detected) string >>{}<< at {:p}", this_arg, (FlatPtr)this_arg);
+
     return (FlatPtr)this_arg;
 }