bgets(3gen) [opensolaris man page]

bgets(3GEN)					     String Pattern-Matching Library Functions					       bgets(3GEN)

NAME

       bgets - read stream up to next delimiter

SYNOPSIS

       cc [ flag ... ] file ... -lgen [ library ... ]
       #include <libgen.h>

       char *bgets(char *buffer, size_t count, FILE  *stream,
	    const char *breakstring);

DESCRIPTION

       The  bgets()  function  reads characters from stream into buffer until either count is exhausted or one of the characters in breakstring is
       encountered in the stream. The read data is terminated with a null byte ('') and a pointer to the trailing null is returned. If a  break-
       string character is encountered, the last non-null is the delimiter character that  terminated the scan.

       Note that, except for the fact that the returned value points to the end of the read string rather than to the beginning, the call

	 bgets(buffer, sizeof buffer, stream, "
");

       is identical to

	 fgets (buffer, sizeof buffer, stream);

       There is always enough room reserved in the buffer for the trailing null character.

       If  breakstring	is  a  null pointer, the value of breakstring from the previous call is used. If breakstring is null at the first call, no
       characters will be used to delimit the string.

RETURN VALUES

       NULL is returned on error or end-of-file.  Reporting the condition is delayed to the next  call if any characters were  read  but  not  yet
       returned.

EXAMPLES

       Example 1 Example of the bgets() function.

       The following example prints the name of the first user encountered in /etc/passswd, including a trailing ":"

	 #include <stdio.h>
	 #include<libgen.h>

	 int main()
	 {
	     char buffer[8];
	     FILE *fp;

	     if ((fp = fopen("/etc/passwd","r")) == NULL) {
		 perror("/etc/passwd");
		 return 1;
	     }
	     if (bgets(buffer, 8, fp, ":") == NULL) {
		 perror("bgets");
		 return 1;
	     }
	     (void) puts(buffer);
	     return 0;
	 }

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       gets(3C), attributes(5)

NOTES

       When  compiling multithread applications, the _REENTRANT flag must be defined on the compile line.  This flag should only be used in multi-
       threaded applications.

SunOS 5.11							    9 May 2001							       bgets(3GEN)

gets(3C)						   Standard C Library Functions 						  gets(3C)

NAME

       gets, fgets - get a string from a stream

SYNOPSIS

       #include <stdio.h>

       char *gets(char *s);

       char *fgets(char *s, int n, FILE *stream);

DESCRIPTION

       The gets() function reads bytes from the standard input stream (see Intro(3)), stdin, into the array pointed to by s, until a newline char-
       acter is read or an end-of-file condition is encountered. The newline character is discarded and the string is terminated with a null byte.

       If the length of an input line exceeds the size of s, indeterminate behavior may result. For this reason, it is strongly  recommended  that
       gets() be avoided in favor of fgets().

       The  fgets()  function reads bytes from the stream into the array pointed to by s, until n-1 bytes are read, or a newline character is read
       and transferred to s, or an end-of-file condition is encountered. The string is then terminated with a null byte.

       The fgets() and gets() functions may mark the st_atime field of the file associated with stream for update.  The  st_atime  field  will	be
       marked  for  update  by	the  first  successful	execution  of fgetc(3C), fgets(), fread(3C), fscanf(3C), getc(3C), getchar(3C), gets(), or
       scanf(3C) using stream that returns data not supplied by a prior call to ungetc(3C) or ungetwc(3C).

RETURN VALUES

       If end-of-file is encountered and no bytes have been read, no bytes are transferred to s and a null pointer is returned. For  standard-con-
       forming	(see  standards(5))  applications,  if	the  end-of-file indicator for the stream is set, no bytes are transferred to s and a null
       pointer is returned whether or not the stream is at end-of-file. If a read error occurs, such as trying to use these functions  on  a  file
       that  has  not been opened for reading, a null pointer is returned and the error indicator for the stream is set. If end-of-file is encoun-
       tered, the EOF indicator for the stream is set.	Otherwise s is returned.

ERRORS

       Refer to fgetc(3C).

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       lseek(2), read(2), ferror(3C), fgetc(3C), fgetwc(3C), fopen(3C), fread(3C), getchar(3C),  scanf(3C),  stdio(3C),  ungetc(3C),  ungetwc(3C),
       attributes(5), standards(5)

SunOS 5.11							    15 Oct 2003 							  gets(3C)