.\" -*- coding: UTF-8 -*-
.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl)
.\" and Copyright 2008, 2015 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" Written 11 June 1995 by Andries Brouwer <aeb@cwi.nl>
.\" Modified 22 July 1995 by Michael Chastain <mec@duracef.shout.net>:
.\"   Derived from 'readdir.2'.
.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH getdents 2 "3 maja 2023 r." "Linux man\-pages 6.05.01" 
.SH NAZWA
getdents, getdents64 \- pobiera wpisy z katalogu
.SH BIBLIOTEKA
Standardowa biblioteka C (\fIlibc\fP, \fI\-lc\fP)
.SH SKŁADNIA
.nf
\fB#include <sys/syscall.h>           \fP/* Definicja stałych \fBSYS_*\fP */
\fB#include <unistd.h>\fP
.PP
\fBlong syscall(SYS_getdents, unsigned int \fP\fIfd\fP\fB, struct linux_dirent *\fP\fIdirp\fP\fB,\fP
\fB             unsigned int \fP\fIcount\fP\fB);\fP
.PP
\fB#define _GNU_SOURCE\fP           /* Zob. feature_test_macros(7) */
\fB#include <dirent.h>\fP
.PP
\fBssize_t getdents64(int \fP\fIfd\fP\fB, void \fP\fIdirp\fP\fB[.\fP\fIcount\fP\fB], size_t \fP\fIcount\fP\fB);\fP
.fi
.PP
\fIUwaga\fP: glibc nie udostępnia opakowania dla \fBgetdents\fP(), co wymusza
użycie \fBsyscall\fP(2).
.PP
\fINote\fP: W glibc brak definicji \fIstruct linux_dirent\fP; zob. UWAGI.
.SH OPIS
Nie są to interfejsy, które cię interesują. Opis implementacji interfejsu
zgodnego z POSIX w bibliotece C znajduje się w \fBreaddir\fP(3). Niniejsza
strona opisuje nagi interfejs wywołania systemowego.
.SS getdents()
Wywołanie systemowe  \fBgetdents\fP() odczytuje kolejne struktury
\fIlinux_dirent\fP z katalogu wskazywanego przez przez deskryptor otwartego
pliku \fIfd\fP do bufora wskazywanego przez \fIdirp\fP. Argument \fIcount\fP określa
rozmiar tego bufora.
.PP
Struktura \fIlinux_dirent\fP jest zadeklarowana następująco:
.PP
.in +4n
.EX
struct linux_dirent {
    unsigned long  d_ino;     /* Numer i\-węzła */
    unsigned long  d_off;     /* Przesun. do nast. \fIlinux_dirent\fP */
    unsigned short d_reclen;  /* Długość tego \fIlinux_dirent\fP */
    char           d_name[];  /* Nazwa pliku (zakończ. znakiem null) */
                      /* długość to faktycznie (d_reclen \- 2 \-
                         offsetof(struct linux_dirent, d_name)) */
    /*
    char           pad;       // Zerowy bajt wyrównania
    char           d_type;    // Typ pliku (tylko od  Linuksa
                              // 2.6.4); przesunięciem jest (d_reclen \- 1)
    */
}
.EE
.in
.PP
\fId_ino\fP jest numerem i\-węzła. \fId_off\fP jest odległością od początku
katalogu do początku następnej struktury \fIlinux_dirent\fP. \fId_reclen\fP jest
wielkością tej całej struktury \fIlinux_dirent\fP. \fId_name\fP jest nazwą pliku
zakończoną znakiem NUL.
.PP
\fId_type\fP jest bajtem na końcu struktury wskazującym typ pliku. Zawiera
jedną z następujących wartości (zdefiniowanym w \fI<dirent.h>\fP):
.TP  12
\fBDT_BLK\fP
Jest to urządzenie blokowe
.TP 
\fBDT_CHR\fP
Jest to urządzenie znakowe.
.TP 
\fBDT_DIR\fP
Jest to katalog.
.TP 
\fBDT_FIFO\fP
Jest to potok nazwany (FIFO).
.TP 
\fBDT_LNK\fP
Jest to dowiązanie symboliczne.
.TP 
\fBDT_REG\fP
Jest to zwykły plik.
.TP 
\fBDT_SOCK\fP
Jest to gniazdo dziedziny Uniksa.
.TP 
\fBDT_UNKNOWN\fP
Typ pliku jest nieznany.
.PP
Pole \fId_type\fP zaimplementowano od Linuksa 2.6.4. Zajmuje miejsce, które
wcześniej zajmował zerowy bajt wypełnienia w strukturze \fIlinux_dirent\fP. Z
tego względu jądra do Linuksa 2.6.3, próbujące uzyskać dostęp do tego pola
zawsze zwracają wartość 0 (\fBDT_UNKNOWN\fP).
.PP
.\" kernel 2.6.27
.\" The same sentence is in readdir.2
Obecnie jedynie niektóre systemy plików (m.in Btrfs, ext2, ext3 i ext4)
obsługują w pełni zwracanie typu pliku w \fId_type\fP. Wszystkie programy muszą
poprawnie obsługiwać zwrócenie wartości \fBDT_UNKNOWN\fP.
.SS getdents64()
Pierwotne, linuksowe wywołanie \fBgetdents\fP() nie obsługiwało dużych systemów
plików i dużych przesunięć pliku. Z tego powodu, Linux 2.4 dodał
\fBgetdents64\fP(), z szerszymi typami pól \fId_ino\fP i \fId_off\fP. Dodatkowo,
\fBgetdents64\fP() obsługuje wprost pole \fId_type\fP.
.PP
Wywołanie systemowe \fBgetdents64\fP() zachowuje się jak \fBgetdents\fP(), tyle że
jego drugi argument jest wskaźnikiem do bufora zawierającego strukturę
następującego typu:
.PP
.in +4n
.EX
struct linux_dirent64 {
    ino64_t        d_ino;    /* 64\-bitowy numer i\-węzła */
    off64_t        d_off;    /* 64\-bitowy przesun. do następnej strukt. */
    unsigned short d_reclen; /* Rozmiar tego dirent */
    unsigned char  d_type;   /* Typ pliku */
    char           d_name[]; /* Nazwa pliku (zakończona null) */
};
.EE
.in
.SH "WARTOŚĆ ZWRACANA"
Po pomyślnym zakończeniu zwracana jest ilość odczytanych bajtów. Na końcu
katalogu zwracane jest 0. Przy błędzie zwracane jest \-1 i ustawiane \fIerrno\fP
wskazując błąd.
.SH BŁĘDY
.TP 
\fBEBADF\fP
Nieprawidłowy deskryptor \fIfd\fP.
.TP 
\fBEFAULT\fP
Argument wskazuje poza przestrzeń adresową wywołującego procesu.
.TP 
\fBEINVAL\fP
Bufor na wynik jest za mały.
.TP 
\fBENOENT\fP
Nie ma takiego katalogu.
.TP 
\fBENOTDIR\fP
Deskryptor pliku nie odnosi się do katalogu.
.SH STANDARDY
Brak.
.SH HISTORIA
.\" SVr4 documents additional ENOLINK, EIO error conditions.
SVr4.
.TP 
\fBgetdents64\fP()
glibc 2.30.
.SH UWAGI
glibc nie udostępnia opakowania dla \fBgetdents\fP(); należy je wywołać za
pomocą \fBsyscall\fP(2). W takim przypadku konieczne będzie samodzielne
zdefiniowanie struktury \fIlinux_dirent\fP lub \fIlinux_dirent64\fP.
.PP
Zamiast opisywanych wywołań systemowych, prawdopodobnie lepszym pomysłem
będzie użycie \fBreaddir\fP(3).
.PP
Te wywołania zastępują \fBreaddir\fP(2).
.SH PRZYKŁADY
.\" FIXME The example program needs to be revised, since it uses the older
.\" getdents() system call and the structure with smaller field widths.
Program poniżej demonstruje użycie \fBgetdents\fP(). Poniższe wyjście pokazuje
przykład, w którym można zaobserwować działanie tego programu w katalogu
ext2:
.PP
.in +4n
.EX
$\fB ./a.out /testfs/\fP
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- nread=120 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
i\-węzeł#  typ pliku  d_reclen  d_off   d_name
       2  katalog      16         12  .
       2  katalog      16         24  ..
      11  katalog      24         44  lost+found
      12  zwykły       16         56  a
  228929  katalog      16         68  sub
   16353  katalog      16         80  sub2
  130817  katalog      16       4096  sub3
.EE
.in
.SS "Kod źródłowy programu"
.\" SRC BEGIN (getdents.c)
\&
.EX
#define _GNU_SOURCE
#include <dirent.h>     /* Definiuje stałe DT_* */
#include <err.h>
#include <fcntl.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/syscall.h>
#include <unistd.h>
\&
struct linux_dirent {
    unsigned long  d_ino;
    off_t          d_off;
    unsigned short d_reclen;
    char           d_name[];
};
\&
#define BUF_SIZE 1024
\&
int
main(int argc, char *argv[])
{
    int                  fd;
    char                 d_type;
    char                 buf[BUF_SIZE];
    long                 nread;
    struct linux_dirent  *d;
\&
    fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY);
    if (fd == \-1)
        err(EXIT_FAILURE, "open");
\&
    for (;;) {
        nread = syscall(SYS_getdents, fd, buf, BUF_SIZE);
        if (nread == \-1)
            err(EXIT_FAILURE, "getdents");
\&
        if (nread == 0)
            break;
\&
        printf("\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- nread=%ld \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\en", nread);
        printf("i\-węzeł#  typ pliku  d_reclen  d_off   d_name\en");
        for (size_t bpos = 0; bpos < nread;) {
            d = (struct linux_dirent *) (buf + bpos);
            printf("%8lu  ", d\->d_ino);
            d_type = *(buf + bpos + d\->d_reclen \- 1);
            printf("%\-10s ", (d_type == DT_REG) ?  "zwykły" :
                             (d_type == DT_DIR) ?  "katalog" :
                             (d_type == DT_FIFO) ? "FIFO" :
                             (d_type == DT_SOCK) ? "gniazdo" :
                             (d_type == DT_LNK) ?  "dow. symbol." :
                             (d_type == DT_BLK) ?  "urz. blok." :
                             (d_type == DT_CHR) ?  "urz. znak." : "???");
            printf("%4d %10jd  %s\en", d\->d_reclen,
                   (intmax_t) d\->d_off, d\->d_name);
            bpos += d\->d_reclen;
        }
    }
\&
    exit(EXIT_SUCCESS);
}
.EE
.\" SRC END
.SH "ZOBACZ TAKŻE"
\fBreaddir\fP(2), \fBreaddir\fP(3), \fBinode\fP(7)
.PP
.SH TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są:
Przemek Borys <pborys@dione.ids.pl>,
Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl>
i
Michał Kułach <michal.kulach@gmail.com>
.
.PP
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach
licencji można uzyskać zapoznając się z
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License w wersji 3
.UE
lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.
.PP
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy
dyskusyjnej
.MT manpages-pl-list@lists.sourceforge.net
.ME .
