plan9fox/sys/man/1/syscall
kvik aa7c8cac11 syscall: utility overhaul
Following is a list of functional changes:

* The -o flag outputs the entire buffer to the length returned
  by the syscall, or, in case of fd2path(2) and errstr(2), to '\0'.
* The -x flag is removed; the above makes it possible to pipe
  into xd(1) to get the same result.
* The -s flag uses dirfmt(2) to format the stat message, instead
  of trying to imitate ls(1).
* Stderr reports are normalized and made easier to parse.

The code also suffered a number of stylistic changes.
2020-09-20 14:49:12 +02:00

83 lines
1.4 KiB
Plaintext

.TH SYSCALL 1
.SH NAME
syscall \- test a system call
.SH SYNOPSIS
.B syscall
[
.B -os
]
.I entry
[
.I arg ...
]
.SH DESCRIPTION
.I Syscall
invokes the system call
.I entry
with the given arguments.
The return value is printed.
If an error occured, the error string is also printed.
.PP
For convenience,
.IR write (2)
and
.IR read (2)
are included in
.IR entries ,
even though they are not strictly syscalls.
.PP
.I Syscall
arguments are integer constants, strings, or the literal
.BR buf .
The literal
.B buf
refers to a writable 1 megabyte buffer.
Strings and
.B buf
are passed as pointers.
Integers are passed as values.
.PP
The
.B -o
option prints contents of the 1MB buffer.
For
.IR errstr (2)
and
.IR fd2path (2),
the buffer is treated as a 0-terminated string.
For other calls, the number of bytes printed is
determined by the system call's return value.
.PP
The
.B -s
option is similar, but interprets the data as a
.IR stat (5)
message and formats it to standard output.
.SH EXAMPLES
Write a string to standard output:
.IP
.EX
syscall write 1 hello 5
.EE
.PP
Print information about the file connected to standard input:
.IP
.EX
syscall -s fstat 0 buf 1024
.EE
.SH SOURCE
.B /sys/src/cmd/syscall
.SH "SEE ALSO"
Section 2 of this manual.
.SH DIAGNOSTICS
If
.I entry
is not known to
.IR syscall ,
the exit status is
.LR unknown .
If the system call succeeds, the exit status is null;
otherwise the exit status is the string that
.IR errstr (2)
returns.