strerror_s, _strerror_s, _wcserror_s, __wcserror_s

Articolo
06/09/2015

Ottenere un messaggio di errore dal sistema (strerror_s, _wcserror_s, o stampa un messaggio di errore fornito dall'utente (_strerror_s, __wcserror_s). Queste sono versioni di strerror, _strerror, _wcserror, __wcserror con i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

errno_t strerror_s(
   char *buffer,
   size_t numberOfElements,
   int errnum 
);
errno_t _strerror_s(
   char *buffer,
   size_t numberOfElements,
   const char *strErrMsg 
);
errno_t _wcserror_s(
   wchar_t *buffer,
   size_t numberOfElements,
   int errnum 
);
errno_t __wcserror_s(
   wchar_t *buffer,
   size_t numberOfElements,
   const wchar_t *strErrMsg 
);
template <size_t size>
errno_t strerror_s(
   char (&buffer)[size],
   int errnum 
); // C++ only
template <size_t size>
errno_t _strerror_s(
   char (&buffer)[size],
   const char *strErrMsg 
); // C++ only
template <size_t size>
errno_t _wcserror_s(
   wchar_t (&buffer)[size],
   int errnum 
); // C++ only
template <size_t size>
errno_t __wcserror_s(
   wchar_t (&buffer)[size],
   const wchar_t *strErrMsg 
); // C++ only

Parametri

buffer
Buffer per contenere la stringa di errore.
numberOfElements
Dimensione del buffer.
errnum
Un codice di errore.
strErrMsg
Messaggi forniti dall'utente

Valore restituito

Zero se ha esito positivo, un codice di errore in caso di errore.

Condizioni di errore

buffer	numberOfElements	strErrMsg	Contenuto di buffer.
NULL	any	any	n/d
any	0	any	non modificato

Note

La funzione strerror_s esegue il mapping di errnum in una stringa contenente il messaggio di errore, restituendo la stringa nel buffer. _strerror_s non accetta il numero dell'errore; utilizza il valore corrente di errno per determinare il messaggio appropriato. Né strerror_s né _strerror_s visualizza effettivamente il messaggio: Per questo, diviene necessario chiamare una funzione di output come fprintf:

if (( _access( "datafile",2 )) == -1 )
{
   _strerror_s(buffer, 80);
   fprintf( stderr, buffer );
}

Se strErrMsg è NULL, _strerror_s restituisce una stringa nel buffer contenente il messaggio di errore del sistema per l'ultima chiamata della libreria che ha generato un errore. La stringa del messaggio di errore termina con il carattere di nuova riga ("\n"). Se strErrMsg non è uguale a NULL, quindi _strerror_s restituisce una stringa nel buffer che contiene (secondo questo ordine) il messaggio della stringa, i due punti, uno spazio, il messaggio di errore del sistema per l'ultima chiamata della libreria che ha generato un errore e il carattere di nuova riga. Il messaggio stringa può essere, al più di 94 caratteri.

Queste funzioni troncano il messaggio di errore se la lunghezza supera numberOfElements -1. La stringa risultante nel buffer termina sempre con null.

Il numero di errore effettivo per _strerror_s viene archiviato nella variabile errno. I messaggi di errore del sistema sono accessibili tramite la variabile _sys_errlist, che è una matrice di messaggi ordinata in base al numero di errore. _strerror_s accede al messaggio di errore appropriato tramite il valore errno come indice della variabile _sys_errlist. Il valore della variabile _sys_nerr è definito come numero massimo di elementi della matrice _sys_errlist. Per fornire risultati accurati, chiamare _strerror_s subito dopo il ritorno di un'errore da parte di una routine della libreria. In caso contrario, le chiamate successive a strerror_s o _strerror_s possono sovrascrivere il valore errno.

_wcserror_se __wcserror_ssono versioni a caratteri estesi rispettivamente di strerror_se _strerror_s.

Queste funzioni convalidano i parametri. Se il buffer è NULL o se il parametro di dimensione è 0, il viene richiamato il gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, la funzione restituisce EINVAL e imposta errno su EINVAL.

_strerror_s, _wcserror_s, e __wcserror_s non fanno parte della definizione ANSI ma sono invece estensioni Microsoft. Non utilizzarli nel caso in cui si desidera avere la portabilità; utilizzare invece, per la compatibilità ANSI strerror_s .

In C++, l'utilizzo di queste funzioni viene semplificato da overload del modello; gli overload possono dedurre la lunghezza del buffer automaticamente, eliminando la necessità di specificare un argomento per la dimensione. Per ulteriori informazioni, vedere Overload di modelli sicuri.

La versione di debug di queste funzioni per prima cosa riempiono il buffer con il valore 0xFD. Per disattivare questo comportamento, utilizzare _CrtSetDebugFillThreshold.

Mapping di routine su testo generico