syscall.1

.TH SYSCALL 1
.SH NAME
syscall \- Test a system call
.SH SYNOPSIS
.B syscall
[\fB\-ovlh\fR]
[\fB\-n\fR \fIbytes\fR]
.IR entry
.IR arg ...
.SH DESCRIPTION
.B syscall(1)
is a port of the Plan\ 9 syscall command to Linux.
Rather than going through libc, it invokes system calls directly using the
.BR syscall (2)
library function, which makes it useful for testing kernel behaviour,
understanding how system calls work, and quick scripting without writing C.
.PP
Not every Linux syscall is invocable this way \(em some require kernel
structures that cannot be expressed as plain scalars \(em but the most
common ones work fine.
Up to six arguments can be passed, matching the maximum number of arguments
any Linux syscall takes.
.SH OPTIONS
.TP
.BR \-o
Print the contents of
.B buf
to stdout after the call.
.TP
.BI \-n " bytes"
With
.BR \-o ,
print exactly
.I bytes
bytes from
.B buf
using
.BR fwrite (3)
instead of stopping at the first null byte.
Useful for syscalls that write binary data or structs into the buffer.
.TP
.BR \-v
Print the syscall return value to stderr.
.TP
.BR \-l
List all available syscalls, one per line, and exit.
.TP
.BR \-h
Print a usage message and exit.
.SH SPECIAL ARGUMENTS
The following tokens are recognised by the argument parser and expanded
before being passed to the syscall:
.TP
.B buf
An 8\ KB scratch buffer, passed as a pointer.
Use with
.B \-o
to read its contents after the call.
.TP
.BR stdin ", " stdout ", " stderr
Expand to file descriptors 0, 1, and 2 respectively.
.SH EXAMPLES
Write a string to standard output:
.PP
.RS
syscall write stdout hello 5
.RE
.PP
Read 5 bytes from stdin and print the buffer:
.PP
.RS
echo \-n hello | syscall \-o read stdin buf 5
.RE
.PP
Get the current working directory:
.PP
.RS
syscall \-ov getcwd buf 100
.RE
.PP
Get the PID of the current process:
.PP
.RS
syscall \-v getpid
.RE
.PP
Create a directory:
.PP
.RS
syscall mkdir my\-dir 0755
.RE
.PP
Rename a file:
.PP
.RS
syscall rename old\-name new\-name
.RE
.PP
Test file accessibility (exit code reflects success or failure):
.PP
.RS
syscall access /etc/shadow 0 || echo "no access"
.RE
.PP
Dump all fields of
.B struct utsname
(6 x 65 bytes) by printing the full buffer:
.PP
.RS
syscall \-on 390 uname buf | tr '\0' ' ' | tr \-s ' '
.RE
.PP
Get 16 bytes of random data from the kernel
.PP
.RS
syscall \-ov getrandom buf 16 1
.RE
.PP
Exit with a specific status code:
.PP
.RS
syscall exit 2
.RE
.SH SEE ALSO
.BR syscall (2),
.BR intro (2)