1*61180Sbostic.\" Copyright (c) 1990, 1991, 1993 2*61180Sbostic.\" The Regents of the University of California. All rights reserved. 320343Smckusick.\" 446072Sbostic.\" This code is derived from software contributed to Berkeley by 550294Sbostic.\" Chris Torek and the American National Standards Committee X3, 650294Sbostic.\" on Information Processing Systems. 750294Sbostic.\" 843570Strent.\" %sccs.include.redist.man% 938067Sbostic.\" 10*61180Sbostic.\" @(#)fgets.3 8.1 (Berkeley) 06/04/93 1138067Sbostic.\" 1248352Scael.Dd 1348352Scael.Dt FGETS 3 1448352Scael.Os 1548352Scael.Sh NAME 1648352Scael.Nm fgets , 1748352Scael.Nm gets 1848352Scael.Nd get a line from a stream 1948352Scael.Sh SYNOPSIS 2048352Scael.Fd #include <stdio.h> 2148352Scael.Ft char * 2248352Scael.Fn fgets "char *str" "size_t size" "FILE *stream" 2348352Scael.Ft char * 2448352Scael.Fn gets "char *str" 2548352Scael.Sh DESCRIPTION 2648352ScaelThe 2748352Scael.Fn fgets 2848352Scaelfunction 2946072Sbosticreads at most one less than the number of characters specified by 3048352Scael.Xr size 3146072Sbosticfrom the given 3248352Scael.Fa stream 3348352Scaeland stores them in the string 3448352Scael.Fa str . 3546072SbosticReading stops when a newline character is found, 3646072Sbosticat end-of-file or error. 3746072SbosticThe newline, if any, is retained. 3848352ScaelIn any case a 3948352Scael.Ql \e0 4048352Scaelcharacter is appended to end the string. 4148352Scael.Pp 4248352ScaelThe 4348352Scael.Fn gets 4448352Scaelfunction 4546072Sbosticis equivalent to 4648352Scael.Fn fgets 4746072Sbosticwith an infinite 4848352Scael.Xr size 4946072Sbosticand a 5048352Scael.Fa stream 5146072Sbosticof 5248352Scael.Em stdin , 5346072Sbosticexcept that the newline character (if any) is not stored in the string. 5446072SbosticIt is the caller's responsibility to ensure that the input line, 5546072Sbosticif any, is sufficiently short to fit in the string. 5648352Scael.Sh RETURN VALUES 5748352Scael.Pp 5846072SbosticUpon successful completion, 5948352Scael.Fn fgets 6046072Sbosticand 6148352Scael.Fn gets 6246072Sbosticreturn 6348352Scaela pointer to the string. 6446072SbosticIf end-of-file or an error occurs before any characters are read, 6548352Scaelthey return 6648352Scael.Dv NULL. 6748352ScaelThe 6848352Scael.Fn fgets 6946072Sbosticand 7048352Scaelfunctions 7148352Scael.Fn gets 7247013Sbosticdo not distinguish between end-of-file and error, and callers must use 7348352Scael.Xr feof 3 7447013Sbosticand 7548352Scael.Xr ferror 3 7646072Sbosticto determine which occurred. 7748352Scael.Sh ERRORS 7848352Scael.Bl -tag -width [EBADF] 7948352Scael.It Bq Er EBADF 8048352ScaelThe given 8148352Scael.Fa stream 8246072Sbosticis not a readable stream. 8348352Scael.El 8448352Scael.Pp 8548352ScaelThe function 8648352Scael.Fn fgets 8746072Sbosticmay also fail and set 8848352Scael.Va errno 8946072Sbosticfor any of the errors specified for the routines 9048352Scael.Xr fflush 3 , 9148352Scael.Xr fstat 2 , 9248352Scael.Xr read 2 , 9346072Sbosticor 9448352Scael.Xr malloc 3 . 9548352Scael.Pp 9648352ScaelThe function 9748352Scael.Fn gets 9846072Sbosticmay also fail and set 9948352Scael.Va errno 10046072Sbosticfor any of the errors specified for the routine 10148352Scael.Xr getchar 3 . 10248352Scael.Sh SEE ALSO 10348352Scael.Xr feof 3 , 10448352Scael.Xr ferror 3 , 10548352Scael.Xr fgetline 3 10648352Scael.Sh STANDARDS 10748352ScaelThe functions 10848352Scael.Fn fgets 10947009Sbosticand 11048352Scael.Fn gets 11148352Scaelconform to 11248352Scael.St -ansiC . 11348352Scael.Sh BUGS 11446072SbosticSince it is usually impossible to ensure that the next input line 11546072Sbosticis less than some arbitrary length, and because overflowing the 11646072Sbosticinput buffer is almost invariably a security violation, programs 11746072Sbosticshould 11848352Scael.Em NEVER 11946072Sbosticuse 12048352Scael.Fn gets . 12148352ScaelThe 12248352Scael.Fn gets 12348352Scaelfunction 12448352Scaelexists purely to conform to 12548352Scael.St -ansiC . 126