87 lines
1.7 KiB
Text
87 lines
1.7 KiB
Text
.TH ERRSTR 2
|
|
.SH NAME
|
|
errstr, rerrstr, werrstr \- description of last system call error
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.PP
|
|
.B
|
|
int errstr(char *err, uint nerr)
|
|
.PP
|
|
.B
|
|
void rerrstr(char *err, uint nerr)
|
|
.PP
|
|
.B
|
|
void werrstr(char *fmt, ...)
|
|
.SH DESCRIPTION
|
|
When a system call fails it returns \-1 and
|
|
records a null terminated string describing the error in a per-process buffer.
|
|
.I Errstr
|
|
swaps the contents of that buffer with the contents of the array
|
|
.IR err .
|
|
.I Errstr
|
|
will write at most
|
|
.I nerr
|
|
bytes into
|
|
.IR err ;
|
|
if the per-process error string does not fit,
|
|
it is silently truncated at a UTF character boundary.
|
|
The returned string is NUL-terminated.
|
|
Usually
|
|
.I errstr
|
|
will be called with an empty string,
|
|
but the exchange property provides a mechanism for
|
|
libraries to set the return value for the next call to
|
|
.IR errstr .
|
|
.PP
|
|
The per-process buffer is
|
|
.B ERRMAX
|
|
bytes long. Any error string provided by the user will
|
|
be truncated at
|
|
.B ERRMAX-1
|
|
bytes.
|
|
.B ERRMAX
|
|
is defined in
|
|
.BR <libc.h> .
|
|
.PP
|
|
If no system call has generated an error since the last call to
|
|
.I errstr
|
|
with an empty string,
|
|
the result is an empty string.
|
|
.PP
|
|
The verb
|
|
.B r
|
|
in
|
|
.IR print (2)
|
|
calls
|
|
.I errstr
|
|
and outputs the error string.
|
|
.PP
|
|
.I Rerrstr
|
|
reads the error string but does not modify the per-process buffer, so
|
|
a subsequent
|
|
.I errstr
|
|
will recover the same string.
|
|
.PP
|
|
.I Werrstr
|
|
takes a
|
|
.I print
|
|
style format as its argument and uses it to format
|
|
a string to pass to
|
|
.IR errstr .
|
|
The string returned from
|
|
.I errstr
|
|
is discarded.
|
|
.SH SOURCE
|
|
.B /sys/src/libc/9syscall
|
|
.br
|
|
.B /sys/src/libc/9sys/rerrstr.c
|
|
.br
|
|
.B /sys/src/libc/9sys/werrstr.c
|
|
.SH DIAGNOSTICS
|
|
.I Errstr
|
|
always returns 0.
|
|
.SH SEE ALSO
|
|
.IR intro (2),
|
|
.IR perror (2)
|