git.saurik.com Git - apple/libc.git/blob

3 .\"

4 .\" Redistribution and use in source and binary forms, with or without

5 .\" modification, are permitted provided that the following conditions

6 .\" are met:

7 .\" 1. Redistributions of source code must retain the above copyright

8 .\" notice, this list of conditions and the following disclaimer.

9 .\" 2. Redistributions in binary form must reproduce the above copyright

10 .\" notice, this list of conditions and the following disclaimer in the

11 .\" documentation and/or other materials provided with the distribution.

12 .\" 4. Neither the name of the University nor the names of its contributors

13 .\" may be used to endorse or promote products derived from this software

14 .\" without specific prior written permission.

15 .\"

16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND

17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE

20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

26 .\" SUCH DAMAGE.

27 .\"

28 .\" @(#)fgetln.3 8.3 (Berkeley) 4/19/94

29 .\" $FreeBSD: src/lib/libc/stdio/fgetln.3,v 1.10 2009/02/28 06:00:58 das Exp $

30 .\"

31 .Dd April 19, 1994

32 .Dt FGETLN 3

33 .Os

34 .Sh NAME

35 .Nm fgetln

36 .Nd get a line from a stream

37 .Sh LIBRARY

38 .Lb libc

39 .Sh SYNOPSIS

40 .In stdio.h

41 .Ft char *

42 .Fn fgetln "FILE *stream" "size_t *len"

43 .Sh DESCRIPTION

44 The

45 .Fn fgetln

46 function

47 returns a pointer to the next line from the stream referenced by

48 .Fa stream .

49 This line is

50 .Em not

51 a C string as it does not end with a terminating

52 .Dv NUL

53 character.

54 The length of the line, including the final newline,

55 is stored in the memory location to which

56 .Fa len

57 points.

58 (Note, however, that if the line is the last

59 in a file that does not end in a newline,

60 the returned text will not contain a newline.)

61 .Sh RETURN VALUES

62 Upon successful completion a pointer is returned;

63 this pointer becomes invalid after the next

64 .Tn I/O

65 operation on

66 .Fa stream

67 (whether successful or not)

68 or as soon as the stream is closed.

69 Otherwise,

70 .Dv NULL

71 is returned.

72 The

73 .Fn fgetln

74 function

75 does not distinguish between end-of-file and error; the routines

76 .Xr feof 3

77 and

78 .Xr ferror 3

79 must be used

80 to determine which occurred.

81 If an error occurs, the global variable

82 .Va errno

83 is set to indicate the error.

84 The end-of-file condition is remembered, even on a terminal, and all

85 subsequent attempts to read will return

86 .Dv NULL

87 until the condition is

88 cleared with

89 .Xr clearerr 3 .

90 .Pp

91 The text to which the returned pointer points may be modified,

92 provided that no changes are made beyond the returned size.

93 These changes are lost as soon as the pointer becomes invalid.

94 .Sh ERRORS

95 .Bl -tag -width Er

96 .It Bq Er EBADF

97 The argument

98 .Fa stream

99 is not a stream open for reading.

100 .It Bq Er ENOMEM

101 The internal line buffer could not be expanded due to lack of available memory,

102 or because it would need to expand beyond INT_MAX in size.

103 .El

104 .Pp

105 The

106 .Fn fgetln

107 function

108 may also fail and set

109 .Va errno

110 for any of the errors specified for the routines

111 .Xr fflush 3 ,

112 .Xr malloc 3 ,

113 .Xr read 2 ,

114 .Xr stat 2 ,

115 or

116 .Xr realloc 3 .

117 .Sh SEE ALSO

118 .Xr ferror 3 ,

119 .Xr fgets 3 ,

120 .Xr fgetwln 3 ,

121 .Xr fopen 3 ,

122 .Xr getline 3 ,

123 .Xr putc 3

124 .Sh HISTORY

125 The

126 .Fn fgetln

127 function first appeared in

128 .Bx 4.4 .