logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

perror.3p (4016B)

    

  1. '\" et
  2. .TH PERROR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. perror
  12. \(em write error messages to standard error
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdio.h>
  17. .P
  18. void perror(const char *\fIs\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The functionality described on this reference page is aligned with the
  22. ISO\ C standard. Any conflict between the requirements described here and the
  23. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  24. .P
  25. The
  26. \fIperror\fR()
  27. function shall map the error number accessed through the symbol
  28. .IR errno
  29. to a language-dependent error message, which shall be written to the
  30. standard error stream as follows:
  31. .IP " *" 4
  32. First (if
  33. .IR s
  34. is not a null pointer and the character pointed to by
  35. .IR s
  36. is not the null byte), the string pointed to by
  37. .IR s
  38. followed by a
  39. <colon>
  40. and a
  41. <space>.
  42. .IP " *" 4
  43. Then an error message string followed by a
  44. <newline>.
  45. .P
  46. The contents of the error message strings shall be the same as those
  47. returned by
  48. \fIstrerror\fR()
  49. with argument
  50. .IR errno .
  51. .P
  52. The
  53. \fIperror\fR()
  54. function shall mark for update the last data modification and last file
  55. status change timestamps of the file associated with the standard error
  56. stream at some time between its successful completion and
  57. \fIexit\fR(),
  58. \fIabort\fR(),
  59. or the completion of
  60. \fIfflush\fR()
  61. or
  62. \fIfclose\fR()
  63. on
  64. .IR stderr .
  65. .P
  66. The
  67. \fIperror\fR()
  68. function shall not change the orientation of the standard error stream.
  69. .P
  70. On error,
  71. \fIperror\fR()
  72. shall set the error indicator for the stream to which
  73. .IR stderr
  74. points, and shall set
  75. .IR errno
  76. to indicate the error.
  77. .P
  78. Since no value is returned, an application wishing to check for error
  79. situations should call
  80. .IR clearerr ( stderr )
  81. before calling
  82. \fIperror\fR(),
  83. then if
  84. .IR ferror ( stderr )
  85. returns non-zero, the value of
  86. .IR errno
  87. indicates which error occurred.
  88. .SH "RETURN VALUE"
  89. The
  90. \fIperror\fR()
  91. function shall not return a value.
  92. .SH ERRORS
  93. Refer to
  94. .IR "\fIfputc\fR\^(\|)".
  95. .LP
  96. .IR "The following sections are informative."
  97. .SH EXAMPLES
  98. .SS "Printing an Error Message for a Function"
  99. .P
  100. The following example replaces
  101. .IR bufptr
  102. with a buffer that is the necessary size. If an error occurs, the
  103. \fIperror\fR()
  104. function prints a message and the program exits.
  105. .sp
  106. .RS 4
  107. .nf
  109. #include <stdio.h>
  110. #include <stdlib.h>
  111. \&...
  112. char *bufptr;
  113. size_t szbuf;
  114. \&...
  115. if ((bufptr = malloc(szbuf)) == NULL) {
  116.     perror("malloc"); exit(2);
  117. }
  118. \&...
  119. .fi
  120. .P
  121. .RE
  122. .SH "APPLICATION USAGE"
  123. Application writers may prefer to use alternative interfaces instead of
  124. \fIperror\fR(),
  125. such as
  126. \fIstrerror_r\fR()
  127. in combination with
  128. \fIfprintf\fR().
  129. .SH RATIONALE
  130. None.
  131. .SH "FUTURE DIRECTIONS"
  132. None.
  133. .SH "SEE ALSO"
  134. .IR "\fIfprintf\fR\^(\|)",
  135. .IR "\fIfputc\fR\^(\|)",
  136. .IR "\fIpsiginfo\fR\^(\|)",
  137. .IR "\fIstrerror\fR\^(\|)"
  138. .P
  139. The Base Definitions volume of POSIX.1\(hy2017,
  140. .IR "\fB<stdio.h>\fP"
  141. .\"
  142. .SH COPYRIGHT
  143. Portions of this text are reprinted and reproduced in electronic form
  144. from IEEE Std 1003.1-2017, Standard for Information Technology
  145. -- Portable Operating System Interface (POSIX), The Open Group Base
  146. Specifications Issue 7, 2018 Edition,
  147. Copyright (C) 2018 by the Institute of
  148. Electrical and Electronics Engineers, Inc and The Open Group.
  149. In the event of any discrepancy between this version and the original IEEE and
  150. The Open Group Standard, the original IEEE and The Open Group Standard
  151. is the referee document. The original Standard can be obtained online at
  152. http://www.opengroup.org/unix/online.html .
  153. .PP
  154. Any typographical or formatting errors that appear
  155. in this page are most likely
  156. to have been introduced during the conversion of the source files to
  157. man page format. To report such errors, see
  158. https://www.kernel.org/doc/man-pages/reporting_bugs.html .