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

getdelim.3p (6251B)


  1. '\" et
  2. .TH GETDELIM "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. getdelim, getline
  12. \(em read a delimited record from
  13. .IR stream
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <stdio.h>
  18. .P
  19. ssize_t getdelim(char **restrict \fIlineptr\fP, size_t *restrict \fIn\fP,
  20. int \fIdelimiter\fP, FILE *restrict \fIstream\fP);
  21. ssize_t getline(char **restrict \fIlineptr\fP, size_t *restrict \fIn\fP,
  22. FILE *restrict \fIstream\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIgetdelim\fR()
  27. function shall read from
  28. .IR stream
  29. until it encounters a character matching the
  30. .IR delimiter
  31. character. The
  32. .IR delimiter
  33. argument is an
  34. .BR int ,
  35. the value of which the application shall ensure is a character
  36. representable as an
  37. .BR "unsigned char"
  38. of equal value that terminates the read process. If the
  39. .IR delimiter
  40. argument has any other value, the behavior is undefined.
  41. .P
  42. The application shall ensure that
  43. .IR *lineptr
  44. is a valid argument that could be passed to the
  45. \fIfree\fR()
  46. function. If
  47. .IR *n
  48. is non-zero, the application shall ensure that
  49. .IR *lineptr
  50. either points to an object of size at least
  51. .IR *n
  52. bytes, or is a null pointer.
  53. .P
  54. If
  55. .IR *lineptr
  56. is a null pointer or if the object pointed to by
  57. .IR *lineptr
  58. is of insufficient size, an object shall be allocated as if by
  59. \fImalloc\fR()
  60. or the object shall be reallocated as if by
  61. \fIrealloc\fR(),
  62. respectively, such that the object is large enough to hold
  63. the characters to be written to it, including the terminating NUL,
  64. and
  65. .IR *n
  66. shall be set to the new size. If the object was allocated,
  67. or if the reallocation operation moved the object,
  68. .IR *lineptr
  69. shall be updated to point to the new object or new location.
  70. The characters read, including any delimiter, shall be stored
  71. in the object, and a terminating NUL added when the delimiter
  72. or end-of-file is encountered.
  73. .P
  74. The
  75. \fIgetline\fR()
  76. function shall be equivalent to the
  77. \fIgetdelim\fR()
  78. function with the
  79. .IR delimiter
  80. character equal to the
  81. <newline>
  82. character.
  83. .P
  84. The
  85. \fIgetdelim\fR()
  86. and
  87. \fIgetline\fR()
  88. functions may mark the last data access timestamp of the file associated
  89. with
  90. .IR stream
  91. for update. The last data access timestamp shall be marked for update
  92. by the first successful execution of
  93. \fIfgetc\fR(),
  94. \fIfgets\fR(),
  95. \fIfread\fR(),
  96. \fIfscanf\fR(),
  97. \fIgetc\fR(),
  98. \fIgetchar\fR(),
  99. \fIgetdelim\fR(),
  100. \fIgetline\fR(),
  101. \fIgets\fR(),
  102. or
  103. \fIscanf\fR()
  104. using
  105. .IR stream
  106. that returns data not supplied by a prior call to
  107. \fIungetc\fR().
  108. .SH "RETURN VALUE"
  109. Upon successful completion, the
  110. \fIgetline\fR()
  111. and
  112. \fIgetdelim\fR()
  113. functions shall return the number of bytes written into the buffer,
  114. including the delimiter character if one was encountered before EOF,
  115. but excluding the terminating NUL character. If the end-of-file
  116. indicator for the stream is set, or if no characters were read and the
  117. stream is at end-of-file, the end-of-file indicator for the
  118. stream shall be set and the function shall return \-1.
  119. If an error occurs, the error indicator for the stream shall be set,
  120. and the function shall return \-1 and set
  121. .IR errno
  122. to indicate the error.
  123. .SH ERRORS
  124. For the conditions under which the
  125. \fIgetdelim\fR()
  126. and
  127. \fIgetline\fR()
  128. functions shall fail and may fail, refer to
  129. .IR "\fIfgetc\fR\^(\|)".
  130. .P
  131. In addition, these functions shall fail if:
  132. .TP
  133. .BR EINVAL
  134. .IR lineptr
  135. or
  136. .IR n
  137. is a null pointer.
  138. .TP
  139. .BR ENOMEM
  140. Insufficient memory is available.
  141. .br
  142. .P
  143. These functions may fail if:
  144. .TP
  145. .BR EOVERFLOW
  146. The number of bytes to be written into the buffer, including the
  147. delimiter character (if encountered), would exceed
  148. {SSIZE_MAX}.
  149. .LP
  150. .IR "The following sections are informative."
  151. .SH EXAMPLES
  152. .sp
  153. .RS 4
  154. .nf
  155. #include <stdio.h>
  156. #include <stdlib.h>
  157. .P
  158. int main(void)
  159. {
  160. FILE *fp;
  161. char *line = NULL;
  162. size_t len = 0;
  163. ssize_t read;
  164. fp = fopen("/etc/motd", "r");
  165. if (fp == NULL)
  166. exit(1);
  167. while ((read = getline(&line, &len, fp)) != -1) {
  168. printf("Retrieved line of length %zu :\en", read);
  169. printf("%s", line);
  170. }
  171. if (ferror(fp)) {
  172. /* handle error */
  173. }
  174. free(line);
  175. fclose(fp);
  176. return 0;
  177. }
  178. .fi
  179. .P
  180. .RE
  181. .SH "APPLICATION USAGE"
  182. Setting
  183. .IR *lineptr
  184. to a null pointer and
  185. .IR *n
  186. to zero are allowed and a recommended way to start parsing a file.
  187. .P
  188. The
  189. \fIferror\fR()
  190. or
  191. \fIfeof\fR()
  192. functions should be used to distinguish between an error condition and
  193. an end-of-file condition.
  194. .P
  195. Although a NUL terminator is always supplied after the line, note that
  196. .IR strlen (* lineptr )
  197. will be smaller than the return value if the line contains embedded
  198. NUL characters.
  199. .SH RATIONALE
  200. These functions are widely used to solve the problem that the
  201. \fIfgets\fR()
  202. function has with long lines. The functions automatically enlarge the
  203. target buffers if needed. These are especially useful since they reduce
  204. code needed for applications.
  205. .SH "FUTURE DIRECTIONS"
  206. None.
  207. .SH "SEE ALSO"
  208. .IR "Section 2.5" ", " "Standard I/O Streams",
  209. .IR "\fIfgetc\fR\^(\|)",
  210. .IR "\fIfgets\fR\^(\|)",
  211. .IR "\fIfree\fR\^(\|)",
  212. .IR "\fImalloc\fR\^(\|)",
  213. .IR "\fIrealloc\fR\^(\|)"
  214. .P
  215. The Base Definitions volume of POSIX.1\(hy2017,
  216. .IR "\fB<stdio.h>\fP"
  217. .\"
  218. .SH COPYRIGHT
  219. Portions of this text are reprinted and reproduced in electronic form
  220. from IEEE Std 1003.1-2017, Standard for Information Technology
  221. -- Portable Operating System Interface (POSIX), The Open Group Base
  222. Specifications Issue 7, 2018 Edition,
  223. Copyright (C) 2018 by the Institute of
  224. Electrical and Electronics Engineers, Inc and The Open Group.
  225. In the event of any discrepancy between this version and the original IEEE and
  226. The Open Group Standard, the original IEEE and The Open Group Standard
  227. is the referee document. The original Standard can be obtained online at
  228. http://www.opengroup.org/unix/online.html .
  229. .PP
  230. Any typographical or formatting errors that appear
  231. in this page are most likely
  232. to have been introduced during the conversion of the source files to
  233. man page format. To report such errors, see
  234. https://www.kernel.org/doc/man-pages/reporting_bugs.html .