Skip to content

Update gets-s-getws-s.md #198

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 26, 2018
Merged

Update gets-s-getws-s.md #198

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 89 additions & 89 deletions docs/c-runtime-library/reference/gets-s-getws-s.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,92 +19,92 @@ author: "corob-msft"
ms.author: "corob"
manager: "ghogen"
ms.workload: ["cplusplus"]
---
# gets_s, _getws_s
Gets a line from the `stdin` stream. These versions of [gets, _getws](../../c-runtime-library/gets-getws.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md).

## Syntax

```
char *gets_s(
char *buffer,
size_t sizeInCharacters
);
wchar_t *_getws_s(
wchar_t *buffer,
size_t sizeInCharacters
);
template <size_t size>
char *gets_s(
char (&buffer)[size]
); // C++ only
template <size_t size>
wchar_t *_getws_s(
wchar_t (&buffer)[size]
); // C++ only
```

#### Parameters
[out] `buffer`
Storage location for input string.

[in] `sizeInCharacters`
The size of the buffer.

## Return Value
Returns `buffer` if successful. A `NULL` pointer indicates an error or end-of-file condition. Use [ferror](../../c-runtime-library/reference/ferror.md) or [feof](../../c-runtime-library/reference/feof.md) to determine which one has occurred.

## Remarks
The `gets_s` function reads a line from the standard input stream `stdin` and stores it in `buffer`. The line consists of all characters up to and including the first newline character ('\n'). `gets_s` then replaces the newline character with a null character ('\0') before returning the line. In contrast, the `fgets_s` function retains the newline character.

If the first character read is the end-of-file character, a null character is stored at the beginning of `buffer` and `NULL` is returned.

`_getws` is a wide-character version of `gets_s`; its argument and return value are wide-character strings.

If `buffer` is `NULL` or `sizeInCharacters` is less than or equal to zero, or if the buffer is too small to contain the input line and null terminator, these functions invoke an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return `NULL` and set errno to `ERANGE`.

In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md).

### Generic-Text Routine Mappings

|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined|
|---------------------|------------------------------------|--------------------|-----------------------|
|`_getts`|`gets_s`|`gets_s`|`_getws`|

## Requirements

|Routine|Required header|
|-------------|---------------------|
|`gets_s`|\<stdio.h>|
|`_getws`|\<stdio.h> or \<wchar.h>|

The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md).

## Example

```
// crt_gets_s.c
// This program retrieves a string from the stdin and
// prints the same string to the console.

#include <stdio.h>

int main( void )
{
char line[21]; // room for 20 chars + '\0'
gets_s( line, 20 );
printf( "The line entered was: %s\n", line );
}
```

```Output

Hello there!The line entered was: Hello there!
```

## See Also
[Stream I/O](../../c-runtime-library/stream-i-o.md)
[gets, _getws](../../c-runtime-library/gets-getws.md)
[fgets, fgetws](../../c-runtime-library/reference/fgets-fgetws.md)
[fputs, fputws](../../c-runtime-library/reference/fputs-fputws.md)
[puts, _putws](../../c-runtime-library/reference/puts-putws.md)
---
# gets_s, _getws_s
Gets a line from the `stdin` stream. These versions of [gets, _getws](../../c-runtime-library/gets-getws.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md).
## Syntax
```
char *gets_s(
char *buffer,
size_t sizeInCharacters
);
wchar_t *_getws_s(
wchar_t *buffer,
size_t sizeInCharacters
);
template <size_t size>
char *gets_s(
char (&buffer)[size]
); // C++ only
template <size_t size>
wchar_t *_getws_s(
wchar_t (&buffer)[size]
); // C++ only
```
#### Parameters
[out] `buffer`
Storage location for input string.
[in] `sizeInCharacters`
The size of the buffer.
## Return Value
Returns `buffer` if successful. A `NULL` pointer indicates an error or end-of-file condition. Use [ferror](../../c-runtime-library/reference/ferror.md) or [feof](../../c-runtime-library/reference/feof.md) to determine which one has occurred.
## Remarks
The `gets_s` function reads a line from the standard input stream `stdin` and stores it in `buffer`. The line consists of all characters up to and including the first newline character ('\n'). `gets_s` then replaces the newline character with a null character ('\0') before returning the line. In contrast, the `fgets_s` function retains the newline character.
If the first character read is the end-of-file character, a null character is stored at the beginning of `buffer` and `NULL` is returned.
`_getws_s` is a wide-character version of `gets_s`; its argument and return value are wide-character strings.
If `buffer` is `NULL` or `sizeInCharacters` is less than or equal to zero, or if the buffer is too small to contain the input line and null terminator, these functions invoke an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return `NULL` and set errno to `ERANGE`.
In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md).
### Generic-Text Routine Mappings
|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined|
|---------------------|------------------------------------|--------------------|-----------------------|
|`_getts_s`|`gets_s`|`gets_s`|`_getws_s`|
## Requirements
|Routine|Required header|
|-------------|---------------------|
|`gets_s`|\<stdio.h>|
|`_getws_s`|\<stdio.h> or \<wchar.h>|
The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md).
## Example
```
// crt_gets_s.c
// This program retrieves a string from the stdin and
// prints the same string to the console.
#include <stdio.h>
int main( void )
{
char line[21]; // room for 20 chars + '\0'
gets_s( line, 20 );
printf( "The line entered was: %s\n", line );
}
```
```Output
Hello there!The line entered was: Hello there!
```
## See Also
[Stream I/O](../../c-runtime-library/stream-i-o.md)
[gets, _getws](../../c-runtime-library/gets-getws.md)
[fgets, fgetws](../../c-runtime-library/reference/fgets-fgetws.md)
[fputs, fputws](../../c-runtime-library/reference/fputs-fputws.md)
[puts, _putws](../../c-runtime-library/reference/puts-putws.md)