Full prototype:
char* fgets(char* restrict, int, FILE* restrict);
Purpose and Notes:
Reads and stores a line of text until a newline, EOF character, or one less then the value of the second argument into the character array pointed to by the first argument's char*.
Puts a '\0' at the end of the string at the index associated with the second argument - 1 (remember zero is starting index).
If you want to store a string like "Clay" remember that you need to set aside 5 characters then you can use fgets like:
fgets(buffer_var, 5, stream);
// where stream holds the value "Clay" without the quotes.
// and buffer_var is a character array of at least 5 characters in size.
Also keep in mind that using this alongside scanf is NOT recommended without taking some things into consideration. In fact I recommend usings fgets() followed by sscanf() INSTEAD of ever using scanf() personally. The reason for this is that scanf() leaves the newline on the stream unless you explicitly capture it, which is not common in examples online in my experience. This is because if you read something with scanf() it will read up until the newline, then leave it in the stream. Then if you immediately call fgets() it will read that newline character that was left and stop reading any further. Thus you have to call it twice for most situations to read the string you are intending to.
Returns:
char*- If successful it returns the string pointed to by the first paramater passed in. If EOF is previously set or reached by the function the contents of the first paramater are unchanged and a null pointer is returned. If any error's occur it is undefined what the value of the first paramater's string will be and a null pointer is returned by the function.
Argument 1:
char* restrict-A pointer to a buffer (character array) to store the contents read in from the stream pointed to by the third argument's FILE*.
Argument 2:
int-The number of characters to read in plus one to read from the stream associated with the FILE* passed in as the third argument. If no newline character is read before reaching the number then a '\0' character is appended.
Argument 3:
FILE* restrict-A stream or file pointer to read from.