1*48352Scael.\" Copyright (c) 1990, 1991 The Regents of the University of California. 238067Sbostic.\" All rights reserved. 320343Smckusick.\" 446072Sbostic.\" This code is derived from software contributed to Berkeley by 546072Sbostic.\" Chris Torek. 643570Strent.\" %sccs.include.redist.man% 738067Sbostic.\" 8*48352Scael.\" @(#)fgets.3 6.8 (Berkeley) 04/19/91 938067Sbostic.\" 10*48352Scael.Dd 11*48352Scael.Dt FGETS 3 12*48352Scael.Os 13*48352Scael.Sh NAME 14*48352Scael.Nm fgets , 15*48352Scael.Nm gets 16*48352Scael.Nd get a line from a stream 17*48352Scael.Sh SYNOPSIS 18*48352Scael.Fd #include <stdio.h> 19*48352Scael.Ft char * 20*48352Scael.Fn fgets "char *str" "size_t size" "FILE *stream" 21*48352Scael.Ft char * 22*48352Scael.Fn gets "char *str" 23*48352Scael.Sh DESCRIPTION 24*48352ScaelThe 25*48352Scael.Fn fgets 26*48352Scaelfunction 2746072Sbosticreads at most one less than the number of characters specified by 28*48352Scael.Xr size 2946072Sbosticfrom the given 30*48352Scael.Fa stream 31*48352Scaeland stores them in the string 32*48352Scael.Fa str . 3346072SbosticReading stops when a newline character is found, 3446072Sbosticat end-of-file or error. 3546072SbosticThe newline, if any, is retained. 36*48352ScaelIn any case a 37*48352Scael.Ql \e0 38*48352Scaelcharacter is appended to end the string. 39*48352Scael.Pp 40*48352ScaelThe 41*48352Scael.Fn gets 42*48352Scaelfunction 4346072Sbosticis equivalent to 44*48352Scael.Fn fgets 4546072Sbosticwith an infinite 46*48352Scael.Xr size 4746072Sbosticand a 48*48352Scael.Fa stream 4946072Sbosticof 50*48352Scael.Em stdin , 5146072Sbosticexcept that the newline character (if any) is not stored in the string. 5246072SbosticIt is the caller's responsibility to ensure that the input line, 5346072Sbosticif any, is sufficiently short to fit in the string. 54*48352Scael.Sh RETURN VALUES 55*48352Scael.Pp 5646072SbosticUpon successful completion, 57*48352Scael.Fn fgets 5846072Sbosticand 59*48352Scael.Fn gets 6046072Sbosticreturn 61*48352Scaela pointer to the string. 6246072SbosticIf end-of-file or an error occurs before any characters are read, 63*48352Scaelthey return 64*48352Scael.Dv NULL. 65*48352ScaelThe 66*48352Scael.Fn fgets 6746072Sbosticand 68*48352Scaelfunctions 69*48352Scael.Fn gets 7047013Sbosticdo not distinguish between end-of-file and error, and callers must use 71*48352Scael.Xr feof 3 7247013Sbosticand 73*48352Scael.Xr ferror 3 7446072Sbosticto determine which occurred. 75*48352Scael.Sh ERRORS 76*48352Scael.Bl -tag -width [EBADF] 77*48352Scael.It Bq Er EBADF 78*48352ScaelThe given 79*48352Scael.Fa stream 8046072Sbosticis not a readable stream. 81*48352Scael.El 82*48352Scael.Pp 83*48352ScaelThe function 84*48352Scael.Fn fgets 8546072Sbosticmay also fail and set 86*48352Scael.Va errno 8746072Sbosticfor any of the errors specified for the routines 88*48352Scael.Xr fflush 3 , 89*48352Scael.Xr fstat 2 , 90*48352Scael.Xr read 2 , 9146072Sbosticor 92*48352Scael.Xr malloc 3 . 93*48352Scael.Pp 94*48352ScaelThe function 95*48352Scael.Fn gets 9646072Sbosticmay also fail and set 97*48352Scael.Va errno 9846072Sbosticfor any of the errors specified for the routine 99*48352Scael.Xr getchar 3 . 100*48352Scael.Sh SEE ALSO 101*48352Scael.Xr feof 3 , 102*48352Scael.Xr ferror 3 , 103*48352Scael.Xr fgetline 3 104*48352Scael.Sh STANDARDS 105*48352ScaelThe functions 106*48352Scael.Fn fgets 10747009Sbosticand 108*48352Scael.Fn gets 109*48352Scaelconform to 110*48352Scael.St -ansiC . 111*48352Scael.Sh BUGS 11246072SbosticSince it is usually impossible to ensure that the next input line 11346072Sbosticis less than some arbitrary length, and because overflowing the 11446072Sbosticinput buffer is almost invariably a security violation, programs 11546072Sbosticshould 116*48352Scael.Em NEVER 11746072Sbosticuse 118*48352Scael.Fn gets . 119*48352ScaelThe 120*48352Scael.Fn gets 121*48352Scaelfunction 122*48352Scaelexists purely to conform to 123*48352Scael.St -ansiC . 124