GETPWNAM(3) Manuel du programmeur Linux GETPWNAM(3)

getpwnam, getpwnam_r, getpwuid, getpwuid_r - Lire un enregistrement du fichier des mots de passe

#include <sys/types.h>
#include <pwd.h>
struct passwd *getpwnam(const char *name);
struct passwd *getpwuid(uid_t uid);
int getpwnam_r(const char *restrict name, struct passwd *restrict pwd,
               char *restrict buf, size_t buflen,
               struct passwd **restrict result);
int getpwuid_r(uid_t uid, struct passwd *restrict pwd,
               char *restrict buf, size_t buflen,
               struct passwd **restrict result);
Exigences de macros de test de fonctionnalités pour la glibc (consulter feature_test_macros(7)) :

getpwnam_r(), getpwuid_r() :

_POSIX_C_SOURCE
    || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

La fonction getpwnam() renvoie un pointeur sur une structure contenant les divers champs de l'enregistrement de la base de données des mots de passe (par exemple, la base de données locale /etc/passwd, NIS ou LDAP) correspondant au nom d'utilisateur name.

La fonction getpwuid() renvoie un pointeur sur une structure contenant les divers champs de l'enregistrement de la base de données des mots de passe correspondant à l'ID utilisateur uid.

La structure passwd est définie dans <pwd.h> comme ceci :


struct passwd {
    char   *pw_name;       /* Nom d'utilisateur */
    char   *pw_passwd;     /* Mot de passe de l'utilisateur */
    uid_t   pw_uid;        /* ID de l'utilisateur */
    gid_t   pw_gid;        /* ID du groupe */
    char   *pw_gecos;      /* Information utilisateur */
    char   *pw_dir;        /* Répertoire personnel */
    char   *pw_shell;      /* Interpréteur de commande */
};

Consultez passwd(5) pour plus d'informations sur ces champs.

Les fonctions getpwnam_r() et getpwuid_r() fournissent les mêmes informations que getpwnam() et getpwuid() mais enregistrent la structure passwd trouvée dans l'espace pointé par pwd. Cette structure passwd contient des pointeurs vers des chaînes qui sont enregistrées dans le tampon buf de taille buflen. Un pointeur vers le résultat (en cas de succès) ou NULL (au cas où aucune entrée n'ait été trouvée ou qu'une erreur soit survenue) est enregistré dans *result.

L'appel

sysconf(_SC_GETPW_R_SIZE_MAX)

renvoie soit -1 sans modifier errno, soit une suggestion de taille initiale pour buf (si cette taille est trop petite, l'appel échoue avec ERANGE, auquel cas l'appelant peut réessayer avec un tampon plus grand).

The getpwnam() and getpwuid() functions return a pointer to a passwd structure, or NULL if the matching entry is not found or an error occurs. If an error occurs, errno is set to indicate the error. If one wants to check errno after the call, it should be set to zero before the call.

La valeur de retour peut pointer vers une zone statique et donc être écrasée par des appels successifs à getpwent(3), getpwnam() ou getpwuid(). (Ne pas passer le pointeur renvoyé à free(3).)

En cas de succès, getpwnam_r() et getpwuid_r() renvoient zéro et définissent *result à pwd. Si aucun mot de passe ne correspond, ces fonctions renvoient 0 et définissent *result à NULL. En cas d'erreur, un code d'erreur est renvoyé et *result et définit à NULL.

0 or ENOENT or ESRCH or EBADF or EPERM or ...
Le nom name ou l'identifiant uid n'ont pas été trouvés.
EINTR
Un signal a été intercepté ; consultez signal(7).
EIO
Erreur d'entrée-sortie.
EMFILE
La limite du nombre de descripteurs de fichiers par processus a été atteinte.
ENFILE
La limite du nombre total de fichiers ouverts pour le système entier a été atteinte.
ENOMEM
Pas assez de mémoire pour allouer la structure passwd.
ERANGE
L'espace tampon fourni est insuffisant.

/etc/passwd
Base de données des mots de passe locaux

Pour une explication des termes utilisés dans cette section, consulter attributes(7).
Interface Attribut Valeur
getpwnam() Sécurité des threads MT-Unsafe race:pwnam locale
getpwuid() Sécurité des threads MT-Unsafe race:pwuid locale
getpwnam_r(), getpwuid_r() Sécurité des threads MT-Safe locale

POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. The pw_gecos field is not specified in POSIX, but is present on most implementations.

La description "VALEUR RENVOYÉE" ci-dessus vient de POSIX.1-2001. Elle ne considère pas le cas « non trouvé » comme une erreur, et ne spécifie pas errno dans ce cas. Cela rend la détection d'erreur impossible. On peut dire que, d'après POSIX, errno est inchangée dans le cas où aucune entrée n'est trouvée. Des essais sur de nombreux systèmes UNIX ont fait apparaître différentes valeurs dans ce cas : 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM et probablement d'autres.

Le champ pw_dir contient le nom du répertoire de travail initial de l'utilisateur. Les programmes de connexion (« login ») utilisent ce champ pour initialiser la variable d'environnement HOME pour les interpréteurs de commandes initiaux. Une application qui souhaite déterminer le répertoire personnel des utilisateurs devrait lire la valeur de HOME (au lieu de la valeur de getpwuid(getuid())->pw_dir) puisque que ceci permet à l'utilisateur de modifier « son répertoire personnel » lorsqu'il est connecté. Pour déterminer le répertoire personnel « initial » d'un autre utilisateur, il est nécessaire d'utiliser getpwnam("utilisateur")->pw_dir ou un équivalent.

Le programme suivant est un exemple d'utilisation de getpwnam_r() pour trouver le nom complet et l'identifiant du nom d'utilisateur fourni en paramètre.
#include <pwd.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>
int
main(int argc, char *argv[])
{
    struct passwd pwd;
    struct passwd *result;
    char *buf;
    size_t bufsize;
    int s;
    if (argc != 2) {
        fprintf(stderr, "Usage: %s username\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
    if (bufsize == -1)          /* Value was indeterminate */
        bufsize = 16384;        /* Should be more than enough */
    buf = malloc(bufsize);
    if (buf == NULL) {
        perror("malloc");
        exit(EXIT_FAILURE);
    }
    s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
    if (result == NULL) {
        if (s == 0)
            printf("Not found\n");
        else {
            errno = s;
            perror("getpwnam_r");
        }
        exit(EXIT_FAILURE);
    }
    printf("Name: %s; UID: %jd\n", pwd.pw_gecos,
            (intmax_t) pwd.pw_uid);
    exit(EXIT_SUCCESS);
}

endpwent(3), fgetpwent(3), getgrnam(3), getpw(3), getpwent(3), getspnam(3), putpwent(3), setpwent(3), passwd(5)

Cette page fait partie de la publication 5.11 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page, peuvent être trouvées à l'adresse https://www.kernel.org/doc/man-pages/.

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> et David Prévot <david@tilapin.org>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 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.

22 mars 2021 GNU