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

gets.3p (3941B)

    

  1. '\" et
  2. .TH GETS "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. gets
  12. \(em get a string from a
  13. .IR stdin
  14. stream
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <stdio.h>
  19. .P
  20. char *gets(char *\fIs\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The functionality described on this reference page is aligned with the
  24. ISO\ C standard. Any conflict between the requirements described here and the
  25. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  26. .P
  27. The
  28. \fIgets\fR()
  29. function shall read bytes from the standard input stream,
  30. .IR stdin ,
  31. into the array pointed to by
  32. .IR s ,
  33. until a
  34. <newline>
  35. is read or an end-of-file condition is encountered. Any
  36. <newline>
  37. shall be discarded and a null byte shall be placed immediately
  38. after the last byte read into the array.
  39. .P
  40. The
  41. \fIgets\fR()
  42. function may mark the last data access timestamp of
  43. the file associated with
  44. .IR stream
  45. for update. The last data access timestamp shall be
  46. marked for update by the first successful execution of
  47. \fIfgetc\fR(),
  48. \fIfgets\fR(),
  49. \fIfread\fR(),
  50. \fIfscanf\fR(),
  51. \fIgetc\fR(),
  52. \fIgetchar\fR(),
  53. \fIgetdelim\fR(),
  54. \fIgetline\fR(),
  55. \fIgets\fR(),
  56. or
  57. \fIscanf\fR()
  58. using
  59. .IR stream
  60. that returns data not supplied by a prior call to
  61. \fIungetc\fR().
  62. .SH "RETURN VALUE"
  63. Upon successful completion,
  64. \fIgets\fR()
  65. shall return
  66. .IR s .
  67. If the end-of-file indicator for the stream is set, or if the stream
  68. is at end-of-file, the end-of-file indicator for the
  69. stream shall be set and
  70. \fIgets\fR()
  71. shall return a null pointer. If a read error occurs, the error indicator
  72. for the stream shall be set,
  73. \fIgets\fR()
  74. shall return a null pointer,
  75. and set
  76. .IR errno
  77. to indicate the error.
  78. .SH ERRORS
  79. Refer to
  80. .IR "\fIfgetc\fR\^(\|)".
  81. .LP
  82. .IR "The following sections are informative."
  83. .SH EXAMPLES
  84. None.
  85. .SH "APPLICATION USAGE"
  86. Reading a line that overflows the array pointed to by
  87. .IR s
  88. results in undefined behavior. The use of
  89. \fIfgets\fR()
  90. is recommended.
  91. .P
  92. Since the user cannot specify the length of the buffer passed to
  93. \fIgets\fR(),
  94. use of this function is discouraged. The length of the string read is
  95. unlimited. It is possible to overflow this buffer in such a way as to
  96. cause applications to fail, or possible system security violations.
  97. .P
  98. Applications should use the
  99. \fIfgets\fR()
  100. function instead of the obsolescent
  101. \fIgets\fR()
  102. function.
  103. .SH RATIONALE
  104. The standard developers decided to mark the
  105. \fIgets\fR()
  106. function as obsolescent even though it is in the ISO\ C standard due to the
  107. possibility of buffer overflow.
  108. .SH "FUTURE DIRECTIONS"
  109. The
  110. \fIgets\fR()
  111. function may be removed in a future version.
  112. .SH "SEE ALSO"
  113. .IR "Section 2.5" ", " "Standard I/O Streams",
  114. .IR "\fIfeof\fR\^(\|)",
  115. .IR "\fIferror\fR\^(\|)",
  116. .IR "\fIfgets\fR\^(\|)"
  117. .P
  118. The Base Definitions volume of POSIX.1\(hy2017,
  119. .IR "\fB<stdio.h>\fP"
  120. .\"
  121. .SH COPYRIGHT
  122. Portions of this text are reprinted and reproduced in electronic form
  123. from IEEE Std 1003.1-2017, Standard for Information Technology
  124. -- Portable Operating System Interface (POSIX), The Open Group Base
  125. Specifications Issue 7, 2018 Edition,
  126. Copyright (C) 2018 by the Institute of
  127. Electrical and Electronics Engineers, Inc and The Open Group.
  128. In the event of any discrepancy between this version and the original IEEE and
  129. The Open Group Standard, the original IEEE and The Open Group Standard
  130. is the referee document. The original Standard can be obtained online at
  131. http://www.opengroup.org/unix/online.html .
  132. .PP
  133. Any typographical or formatting errors that appear
  134. in this page are most likely
  135. to have been introduced during the conversion of the source files to
  136. man page format. To report such errors, see
  137. https://www.kernel.org/doc/man-pages/reporting_bugs.html .