_cgets_s, _cgetws_s

Ottiene una stringa di caratteri dalla console. Queste versioni di e _cgetwsdispongono di miglioramenti per_cgets la sicurezza, come descritto in Funzionalità di sicurezza in CRT.

Importante

Non è possibile usare questa API nelle applicazioni eseguite in Windows Runtime. Per altre informazioni, vedere Funzioni CRT non supportate nelle app della piattaforma UWP (Universal Windows Platform).

Sintassi

errno_t _cgets_s(
   char *buffer,
   size_t numberOfElements,
   size_t *pSizeRead
);
errno_t _cgetws_s(
   wchar_t *buffer
   size_t numberOfElements,
   size_t *pSizeRead
);
template <size_t size>
errno_t _cgets_s(
   char (&buffer)[size],
   size_t *pSizeRead
); // C++ only
template <size_t size>
errno_t _cgetws_s(
   wchar_t (&buffer)[size],
   size_t *pSizeRead
); // C++ only

Parametri

buffer
Percorso di archiviazione per i dati.

numberOfElements
La dimensione del buffer in caratteri a byte singolo o wide, che è anche il numero massimo di caratteri da leggere.

pSizeRead
Numero di caratteri attualmente letti.

Valore restituito

Il valore restituito è zero se ha esito positivo; in caso contrario si verifica un errore.

Condizioni di errore

buffer	numberOfElements	pSizeRead	Restituzione	Contenuto di buffer
NULL	qualsiasi	qualsiasi	EINVAL	n/d
non NULL	zero	qualsiasi	EINVAL	non modificato
non NULL	qualsiasi	NULL	EINVAL	stringa di lunghezza zero

Osservazioni:

_cgets_s e _cgetws_s leggono una stringa dalla console e copiano la stringa (con un carattere di terminazione null) in buffer. _cgetws_s è la versione a caratteri wide della funzione; a parte la dimensione di caratteri, il comportamento di queste due funzioni è identico. La dimensione massima della stringa da leggere viene passata come parametro numberOfElements. Questa dimensione deve includere un carattere aggiuntivo per la terminazione null. Il numero effettivo dei caratteri letti viene inserito in pSizeRead.

Se si verifica un errore durante l'operazione o nella convalida dei parametri, viene richiamato il gestore di parametri non validi, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, errno viene impostata su EINVALe EINVAL viene restituito .

In C++, l'uso di queste funzioni è semplificato dagli overload dei modelli. Gli overload possono dedurre automaticamente la lunghezza del buffer, eliminando la necessità di specificare un argomento size. Possono anche sostituire automaticamente le funzioni meno recenti e meno sicure con le controparti più recenti e più sicure. Per altre informazioni, vedere Proteggere gli overload dei modelli.

Le versioni della libreria di debug di queste funzioni riempiono prima di tutto il buffer con 0xFE. Per disabilitare questo comportamento, usare _CrtSetDebugFillThreshold.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Mapping di routine di testo generico

Routine Tchar.h	_UNICODE e _MBCS non definito	_MBCS definito	_UNICODE definito
_cgetts_s	_cgets_s	_cgets_s	_cgetws_s

Requisiti

Ciclo	Intestazione obbligatoria
_cgets_s	<conio.h>
_cgetws_s	<conio.h> o <wchar.h>

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Vedi anche

I/O della console e della porta
_getch, _getwch