errstr 1.7 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485
  1. .TH ERRSTR 2
  2. .SH NAME
  3. errstr, rerrstr, werrstr \- description of last system call error
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <libc.h>
  8. .PP
  9. .B
  10. int errstr(char *err, uint nerr)
  11. .PP
  12. .B
  13. void rerrstr(char *err, uint nerr)
  14. .PP
  15. .B
  16. void werrstr(char *fmt, ...)
  17. .SH DESCRIPTION
  18. When a system call fails it returns \-1 and
  19. records a null terminated string describing the error in a per-process buffer.
  20. .I Errstr
  21. swaps the contents of that buffer with the contents of the array
  22. .IR err .
  23. .I Errstr
  24. will write at most
  25. .I nerr
  26. bytes into
  27. .IR err ;
  28. if the per-process error string does not fit,
  29. it is silently truncated at a UTF character boundary.
  30. The returned string is NUL-terminated.
  31. Usually
  32. .I errstr
  33. will be called with an empty string,
  34. but the exchange property provides a mechanism for
  35. libraries to set the return value for the next call to
  36. .IR errstr .
  37. .PP
  38. The per-process buffer is
  39. .B ERRMAX
  40. bytes long. Any error string provided by the user will
  41. be truncated at
  42. .B ERRMAX-1
  43. bytes.
  44. .B ERRMAX
  45. is defined in
  46. .BR <libc.h> .
  47. .PP
  48. If no system call has generated an error since the last call to
  49. .I errstr
  50. with an empty string,
  51. the result is an empty string.
  52. .PP
  53. The verb
  54. .B r
  55. in
  56. .IR print (2)
  57. calls
  58. .I errstr
  59. and outputs the error string.
  60. .PP
  61. .I Rerrstr
  62. reads the error string but does not modify the per-process buffer, so
  63. a subsequent
  64. .I errstr
  65. will recover the same string.
  66. .PP
  67. .I Werrstr
  68. takes a
  69. .I print
  70. style format as its argument and uses it to format
  71. a string to pass to
  72. .IR errstr .
  73. The string returned from
  74. .I errstr
  75. is discarded.
  76. .SH SOURCE
  77. .B /sys/src/libc/9syscall
  78. .br
  79. .B /sys/src/libc/9sys/werrstr.c
  80. .SH DIAGNOSTICS
  81. .I Errstr
  82. always returns 0.
  83. .SH SEE ALSO
  84. .IR intro (2),
  85. .IR perror (2)