strerror(3)

NOM
strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l - Obtenir le libellé d'un numéro d'erreur

BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)

SYNOPSIS
#include <string.h>

char *strerror(int errnum);
const char *strerrorname_np(int errnum);
const char *strerrordesc_np(int errnum);

int strerror_r(int errnum, char buf[.buflen], size_t buflen);
               /* conforme à XSI */

char *strerror_r(int errnum, char buf[.buflen], size_t buflen);
               /* spécifique à GNU */

char *strerror_l(int errnum, locale_t locale);

    Exigences de macros de test de fonctionnalités pour la glibc (consulter feature_test_macros(7)) :

strerrorname_np(), strerrordesc_np() :
    _GNU_SOURCE

strerror_r() :
    La version conforme à XSI est fournie si :
        (_POSIX_C_SOURCE >= 200112L) && ! _GNU_SOURCE
    Sinon la version spécifique à GNU est fournie.

DESCRIPTION
The strerror() function returns a pointer to a string that describes the error code passed in the argument errnum, possibly using the LC_MESSAGES part of the current locale to select the appropriate language. (For example, if errnum is EINVAL, the returned description will be "Invalid argument".) This string must not be modified by the application, and the returned pointer will be invalidated on a subsequent call to strerror() or strerror_l(), or if the thread that obtained the string exits. No other library function, including perror(3), will modify this string.

Comme strerror(), la fonction strerrordesc_np() renvoie un pointeur vers une chaîne qui décrit le code d’erreur passé dans l’argument errnum, avec comme différence que la chaîne renvoyée n’est pas traduite selon la régionalisation en cours.

The strerrorname_np() function returns a pointer to a string containing the name of the error code passed in the argument errnum. For example, given EPERM as an argument, this function returns a pointer to the string "EPERM". Given 0 as an argument, this function returns a pointer to the string "0".

  strerror_r()
strerror_r() is like strerror(), but might use the supplied buffer buf instead of allocating one internally. This function is available in two versions: an XSI-compliant version specified in POSIX.1-2001 (available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13), and a GNU-specific version (available since glibc 2.0). The XSI-compliant version is provided with the feature test macros settings shown in the SYNOPSIS; otherwise the GNU-specific version is provided. If no feature test macros are explicitly defined, then (since glibc 2.4) _POSIX_C_SOURCE is defined by default with the value 200112L, so that the XSI-compliant version of strerror_r() is provided by default.

La version de strerror_r() conforme XSI est préférée pour les applications portables. Elle renvoie la chaîne d’erreur dans le tampon buf de longueur buflen fourni par l'appelant.

La version de strerror_r() spécifique GNU renvoie un pointeur sur une chaîne contenant le message d'erreur. Cela peut être soit un pointeur vers une chaîne que la fonction stocke dans buf, soit un pointeur vers une chaîne statique (immuable) (auquel cas buf n'est pas utilisé). Si la fonction stocke une chaîne dans buf, au plus buflen octets sont stockés (la chaîne peut être tronquée si buflen est trop petit et qu'errnum est inconnu). La chaîne inclut toujours l'octet NULL final (« \0 »).

  strerror_l()
strerror_l() est semblable à strerror(), mais fait correspondre à errnum un message d'erreur adapté à la localisation précisée par locale. Le comportement de strerror_l() n'est pas défini si la localisation locale est l'objet spécial de localisation LC_GLOBAL_LOCALE ou si elle n'a pas une valeur valable de localisation.

VALEUR RENVOYÉE
Les fonctions strerror(), strerror_l() et la fonction GNU strerror_r() renvoient la description correspondante au code transmis, ou un message « Unknown error nnn » si le numéro d'erreur est inconnu.

En cas de succès, strerrorname_np() et strerrordesc_np() renvoient la description correspondante au code transmis. Si errnum est un numéro d'erreur non valable, elles renvoient NULL.

La fonction strerror_r() conforme XSI renvoie 0 si elle réussit. En cas d'erreur, un numéro (positif) d'erreur est renvoyé (depuis la glibc 2.13), ou -1 est renvoyé et errno est défini pour indiquer l'erreur (avant la glibc 2.13).

POSIX.1-2001 et POSIX.1-2008 exigent qu'un appel réussi de strerror() ou strerror_l() laisse errno non modifié. Remarquez que, puisqu'aucune valeur de retour de fonction n'est réservée pour indiquer une erreur, une application qui désire vérifier les erreurs devrait initialiser errno à zéro avant l'appel, et vérifier errno après l'appel.

ERREURS

EINVAL
    La valeur de errnum n'est pas un code d'erreur valable.

ERANGE
    Le tampon fourni n'est pas assez grand pour la chaîne de description d’erreur.

ATTRIBUTS
Pour une explication des termes utilisés dans cette section, consulter attributes(7).
Interface | Attribut | Valeur
strerror() | Sécurité des threads | MT-Safe
strerrorname_np(), strerrordesc_np() | Sécurité des threads | MT-Safe
strerror_r(), strerror_l() | Sécurité des threads | MT-Safe

Before glibc 2.32, strerror() is not MT-Safe.

STANDARDS

strerror()
    C11, POSIX.1-2008.

strerror_r()
strerror_l()
    POSIX.1-2008.

strerrorname_np()
strerrordesc_np()
    GNU.

POSIX.1-2001 permet à strerror() d'écrire errno si l'appel rencontre une erreur mais ne spécifie pas quelle valeur devrait être renvoyée comme résultat de fonction dans l'éventualité d'une erreur. Sur certains systèmes, strerror() renvoie NULL si le numéro d'erreur est inconnu. Sur d'autres, strerror() renvoie une chaîne du style « Error nnn occurred » et écrit EINVAL dans errno si le numéro d'erreur est inconnu. C99 et POSIX.1-2008 exigent que la valeur renvoyée ne soit pas NULL.

HISTORIQUE

strerror()
    POSIX.1-2001, C89.

strerror_r()
    POSIX.1-2001.

strerror_l()
    glibc 2.6. POSIX.1-2008.

strerrorname_np()
strerrordesc_np()
    glibc 2.32:

NOTES
strerrorname_np() et strerrordesc_np() sont thread-safe et async-signal-safe.

VOIR AUSSI
err(3), errno(3), error(3), perror(3), strsignal(3), locale(7), signal-safety(7)

TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Frédéric Hantrais <fhantrais@gmail.com>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 (https://www.gnu.org/licenses/gpl-3.0.html) concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org.