Argument flags

Argument flags określa, czy aktualizacje mapowania są widoczne dla innych procesów mapowanych do tego samego miejsca i czy aktualizacje są przenoszone na sam plik. To zachowanie zależy od podanej, dokładnie jednej z poniższych wartości flags:

MAP_SHARED

Dzieli zadane mapowanie. Aktualizacje mapowania są widoczne dla innych procesów mapowanych do tego samego miejsca i (w przypadku mapowań opartych na pliku) są przenoszone do samego pliku (aby kontrolować dokładnie, kiedy aktualizacje są przenoszone na sam plik, konieczne jest użycie msync(2)).

MAP_SHARED_VALIDATE (od Linuksa 4.15)

Znacznik zapewnia takie same zachowanie jak MAP_SHARED z tą różnicą, że mapowania MAP_SHARED ignorują nieznane znaczniki we flags. Przy tworzeniu mapowań z użyciem MAP_SHARED_VALIDATE, jądro sprawdza natomiast, czy wszystkie przekazane znaczniki są znane i odmawia mapowania z błędem EOPNOTSUPP, jeśli wystąpią nieznane znaczniki. Ten typ mapowania jest również wymagany, aby móc korzystać z niektórych znaczników mapowań (np. MAP_SYNC).

MAP_PRIVATE

Tworzy prywatne mapowanie, typu „kopiowanie podczas zapisu”. Aktualizacje mapowania nie są widoczne dla innych procesów mapujących ten sam plik i nie są przenoszone na sam plik. Nie jest określone, czy zmiany zawartości pliku wykonane po wywołaniu mmap() będą uwidocznione w mapowanym obszarze.

MAP_SHARED i MAP_PRIVATE są opisane w POSIX.1-2001 i POSIX.1-2008. MAP_SHARED_VALIDATE jest rozszerzeniem Linuksa.

Ponadto, zero lub więcej poniższych wartości można zsumować bitowo (OR) we flags:

MAP_32BIT (od Linuksa 2.4.20, 2.6)

Umieszcza mapowanie w pierwszych 2 gigabajtach przestrzeni adresowej procesu. Znacznik jest obsługiwany tylko na architekturze x86-64, w przypadku programów 64-bitowych. Znacznik dodano, aby pozwolić stosom wątków na zaalokowanie w pierwszych 2 GB pamięci, co usprawniało wydajność przełączania kontekstów na pewnych wczesnych procesorach 64-bitowych. Współczesne procesory x86-64 nie mają takiego problemu z wydajnością, zatem znacznik ten nie jest wymagany na tych systemach. Znacznik MAP_32BIT jest ignorowany, gdy ustawiony jest MAP_FIXED.

MAP_ANON

Równoważne MAP_ANONYMOUS; istnieje dla kompatybilności z innymi implementacjami.

MAP_ANONYMOUS

Mapowanie nie jest oparte na pliku; jego zawartość jest inicjowana jako zero. Argument fd jest ignorowany, jednak niektóre implementacje wymagają, aby fd wynosiło -1 jeśli podano MAP_ANONYMOUS (lub MAP_ANON), dlatego przenośne aplikacje powinny używać tej wartości. Argument offset powinien wynosić zero. Obsługę MAP_ANONYMOUS w połączeniu z MAP_SHARED dodano w Linuksie 2.4.

MAP_DENYWRITE

Ten znacznik jest ignorowany (dawno temu — Linux 2.0 i wcześniejsze — sygnalizował on, że próba zapisu to mapowanego pliku powinna zawieść z ETXTBSY; było to jednak źródłem ataków blokujących usługę (DoS)).

MAP_EXECUTABLE

Ten znacznik jest ignorowany.

MAP_FILE

Znacznik służący zgodności. Ignorowany.

MAP_FIXED

Nie interpretuje addr jako wskazówki: umieszcza mapowanie dokładnie na podanym adresie. addr musi być właściwie wyrównany: w przypadku większości architektur, wystarczająca jest wielokrotność rozmiaru strony; jednak niektóre architektury mogą narzucać dodatkowe ograniczenia. Jeśli obszar pamięci podany w addr i length nachodzi na strony jakiegoś istniejącego mapowania, to te nachodzące części istniejącego mapowania zostaną odrzucone. Jeśli podany adres nie może być użyty, wywołanie mmap() zawiedzie.

Oprogramowanie, które ma zamiar być przenośne, powinno bardzo ostrożnie korzystać ze znacznika MAP_FIXED, mając na względzie, że dokładny schemat mapowań pamięci procesu może się znacznie zmieniać pomiędzy wersjami Linuksa, wersjami biblioteki C i wydaniami systemu operacyjnego. Proszę dokładnie przeczytać omówienie tego znacznika w UWAGACH!

MAP_FIXED_NOREPLACE (od Linuksa 4.17)

Znacznik zapewnia zachowanie podobne do MAP_FIXED, jeśli chodzi o wymuszenie adresu addr, lecz z tą różnicą, że MAP_FIXED_NOREPLACE nigdy nie narusza wcześniejszego zakresu mapowania. Jeśli żądany zakres kolidowałby z istniejącym mapowaniem, to wywołanie zawiedzie z błędem EEXIST. Znacznik ten może zatem posłużyć do niepodzielnej (z uwzględnieniem innym wątków) próby mapowania zakresu adresowego: u jednego wątku powiedzie się to, wszystkie inne zawiodą.

Proszę zauważyć, że starsze jądra, które nie rozpoznają znacznika MAP_FIXED_NOREPLACE, zwykle (po wykryciu kolizji z wcześniejszym mapowaniem) awaryjnie zachowają się jak „nie-MAP_FIXED”: zwrócą adres, który jest odmienny od adresu żądanego. Oprogramowanie, które ma być kompatybilne wstecznie, powinno zatem sprawdzać zwracany adres z adresem żądanym.

MAP_GROWSDOWN

Znacznik jest używany do stosów. Wskazuje systemowi pamięci wirtualnej jądra, że mapowanie ma kontynuować się w dół pamięci. Zwracany adres jest o jedną stronę niżej, niż obszar pamięci, który jest w rzeczywistości tworzony w wirtualnej przestrzeni adresowej procesu. Dotknięcie adresu w „strzeżonej” stronie (guard page) poniżej mapowania spowoduje zwiększenie mapowania o jedną stronę. Ten wzrost można powtarzać do momentu, gdy mapowanie osiągnie wysoki koniec strony następnego niższego mapowania; wówczas dotknięcie „strzeżonej” strony spowoduje sygnał SIGSEGV.

MAP_HUGETLB (od Linuksa 2.6.32)

Przydziela mapowanie za pomocą dużych („huge”) stron. Więcej informacji w pliku Documentation/admin-guide/mm/hugetlbpage.rst w źródłach jądra Linux oraz w UWAGACH poniżej.

MAP_HUGE_2MB

MAP_HUGE_1GB (od Linuksa 3.8)

Używane w połączeniu z MAP_HUGETLB, do wybrania alternatywnych rozmiarów strony hugetlb (odpowiednio, 2 MB i 1 GB) w systemach, które obsługują wiele rozmiarów stron hugetlb.

Ogólniej, żądany rozmiar dużych stron można skonfigurować, podając logarytm o podstawie 2, żądanego rozmiaru strony, w sześciu bitach na przesunięciu MAP_HUGE_SHIFT (wartość zero w tym polu bitowym oznacza domyślny rozmiar dużej strony; można go sprawdzić za pomocą pola Hugepagesize ujawnianego w /proc/meminfo). Zatem, powyższe dwie stałe są zdefiniowane jako:

#define MAP_HUGE_2MB    (21 << MAP_HUGE_SHIFT)
#define MAP_HUGE_1GB    (30 << MAP_HUGE_SHIFT)

Zakres obsługiwanych rozmiarów dużych stron w systemie można sprawdzić, wypisując podkatalogi w katalogu /sys/kernel/mm/hugepages.

MAP_LOCKED (od Linuksa 2.5.37)

Oznacza mapowany obszar jako zablokowany w ten sam sposób, jak robi to mlock(2). Ta implementacja postara się wypełnić (prefault) cały zakres, lecz wywołanie mmap() nie zawodzi z błędem ENOMEM gdy się to nie powiedzie. Z tego względu później mogą wystąpić główne chybienia stron (ang. major page fault). Semantyka ta nie jest zatem tak mocna jak mlock(2). Jeśli po zainicjowaniu mapowania nie są później dopuszczalne główne chybienia stron, należy korzystać w zamian z mmap() wraz z mlock(2). Znacznik MAP_LOCKED jest ignorowany przez starsze jądra.

MAP_NONBLOCK (od Linuksa 2.5.46)

Znacznik ten ma znaczenie tylko w połączeniu z MAP_POPULATE. Nie przeprowadza odczytu naprzód: wpisy tablicy stron są tworzone tylko w przypadku stron, które są już obecne w RAM. Od Linuksa 2.6.23, znacznik ten nie ma wpływu na MAP_POPULATE. W przyszłości, połączenie MAP_POPULATE z MAP_NONBLOCK może zostać na nowo zaimplementowane.

MAP_NORESERVE

Poleca nie rezerwować przestrzeni wymiany dla tego mapowania. Gdy przestrzeń wymiany jest zarezerwowana, ma się gwarancję, że istnieje możliwość modyfikacji mapowania. Gdy przestrzeń wymiany nie jest zarezerwowana, można otrzymać SIGSEGV podczas zapisu, jeśli braknie pamięci fizycznej. Proszę zapoznać się również z opisem pliku /proc/sys/vm/overcommit_memory w proc(5). Przed Linuksem 2.6, znacznik ten działał tylko dla prywatnych, zapisywalnych mapowań.

MAP_POPULATE (od Linuksa 2.5.46)

Wypełnia (prefault) tablice strony dla mapowania. W przypadku mapowania pliku, powoduje to odczyt z wyprzedzeniem pliku. W ten sposób redukuje się blokowanie, przy późniejszych chybieniach stron (ang. page fault). Wywołanie mmap() nie zawodzi, jeśli nie da się wypełnić mapowania (np. ze względu na ograniczenie liczby mapowanych dużych (huge) stron, za pomocą MAP_HUGETLB). Obsługę MAP_POPULATE w połączeniu z mapowaniami prywatnymi dodano w Linuksie 2.6.23.

MAP_STACK (od Linuksa 2.6.27)

Przydziela mapowanie na adresie odpowiednim dla stosu: procesu lub wątku.

Znacznik ten jest w Linuksie instrukcją pustą. Jednak podając go, przenośne aplikacje mogą zapewnić zyskanie obsługi znacznika, gdy zostanie on w przyszłości zaimplementowany. Z tego względu jest używany w implementacji wątkowania glibc, aby uwzględnić fakt, że niektóre architektury mogą (w przyszłości) wymagać specjalnego traktowania przy alokowaniu stosu. Kolejnym powodem korzystania z tego znacznika jest przenośność: MAP_STACK istnieje (i działa) na niektórych innych systemach (np. niektórych BSD).

MAP_SYNC (od Linuksa 4.15)

Znacznik ten jest dostępny jedynie z typem mapowania MAP_SHARED_VALIDATE; mapowania typu MAP_SHARED po cichu go zignorują. Znacznik ten jest obsługiwany jedynie dla plików obsługujących DAX (bezpośrednie mapowanie do pamięci trwałej). W przypadku innych plików, utworzenie mapowania z tym znacznikiem spowoduje wystąpienie błędu EOPNOTSUPP.

Dzielone mapowania pliku z tym znacznikiem zapewniają gwarancję, że choć pewna część pamięci będzie zmapowana jako zapisywalna w przestrzeni adresowej procesu, będzie ona widoczna w tym samym pliku, na tym samym przesunięciu, nawet po załamaniu lub przeładowaniu systemu. W połączeniu z odpowiednimi instrukcjami procesora, użytkownicy takich mapowań mają zapewnioną lepszy tryb czynienia modyfikacji danych trwałymi.

MAP_UNINITIALIZED (od Linuksa 2.6.33)

Nie czyści stron anonimowych. Znacznik ten ma polepszyć wydajność na urządzeniach wbudowanych. Znacznik jest przestrzegany tylko, gdy jądro skonfigurowano z opcją CONFIG_MMAP_ALLOW_UNINITIALIZED. Ze względu na skutki w zakresie bezpieczeństwa, opcja ta jest zwykle włączana wyłącznie na urządzeniach wbudowanych (tj. mających całkowitą kontrolę nad zawartością pamięci użytkownika).

Z powyższych znaczników, jedynie MAP_FIXED jest określony przez POSIX.1-2001 i POSIX.1-2008. Większość systemów obsługuje jednak także MAP_ANONYMOUS (lub jego synonim MAP_ANON).

munmap()

Wywołanie systemowe munmap() usuwa mapowanie z podanego zakresu adresów i powoduje, że dalsze odwołania do adresów z tego zakresu będą generować nieprawidłowe odwołania do pamięci. Mapowanie obszaru jest również automatycznie usuwane, gdy proces się zakończy. Z drugiej strony, zamknięcie deskryptora pliku nie usuwa mapowania obszaru.

Adres addr musi być wielokrotnością rozmiaru strony (ale length już nie musi). Usuwane jest mapowanie wszystkich stron zawierających fragmenty ze wskazanego zakresu, wszystkie późniejsze odwołania do tych stron wygenerują SIGSEGV. Nie jest błędem, gdy brak w podanym zakresie zamapowanych stron.

Różnice biblioteki C/jądra

Niniejszy podręcznik opisuje interfejs zapewniany przez funkcję opakowującą mmap() z glibc. Pierwotnie, funkcja ta przywoływała wywołanie systemowe o tej samej nazwie. Od Linuksa 2.4, to wywołanie zostało zastąpione wywołaniem mmap2(2), dlatego obecnie funkcja opakowująca mmap() z glibc przywołuje mmap2(2) z odpowiednio dostosowanymi wartościami offset.

Bezpieczne korzystanie z MAP_FIXED

Jedyne bezpieczne zastosowanie MAP_FIXED jest wtedy, gdy podany za pomocą addr i length zakres adresów był uprzednio zarezerwowany przy użyciu innego mapowania; w przeciwnym przypadku MAP_FIXED jest niebezpieczne, ponieważ przymusowo usuwa wcześniejsze mapowania, przez co w przypadku procesów wielowątkowych, łatwe staje się uszkodzenie swojej przestrzeni adresowej.

Przykładowo załóżmy, że wątek A przegląda /proc/pid/maps, aby odszukać nieużywany zakres adresów, które można zmapować przy użyciu MAP_FIXED, a wątek B w tym samym czasie uzyska część lub całość tego samego zakresu adresów. Gdy wątek A następnie użyje mmap(MAP_FIXED), efektywnie naruszy mapowanie, które utworzył wątek B. W opisywanym scenariuszu, wątek B nie musi bezpośrednio tworzyć mapowania; wystarczy utworzenie wywołania bibliotecznego, które wewnętrznie korzysta z dlopen(3) do załadowania jakiejś innej biblioteki współdzielonej. Wywołanie dlopen(3) zmapuje bibliotekę do przestrzeni adresowej procesu. Co więcej, niemal każde wywołanie biblioteczne może być zaimplementowane w sposób, który dodaje mapowania pamięci do przestrzeni adresowej, albo za pomocą tej techniki, albo jedynie alokując pamięć. Przykładem mogą być brk(2), malloc(3), pthread_create(3) i biblioteki PAM http://www.linux-pam.org.

Od Linuksa 4.17, program wielowątkowy może skorzystać ze znacznika MAP_FIXED_NOREPLACE, aby uniknąć niebezpieczeństwa opisanego wyżej, przy tworzeniu mapowania pod konkretnym adresem, który nie został zarezerwowany wcześniejszym mapowaniem.

Zmiany znaczników czasu w przypadku mapowań opartych na plikach

Dla mapowań opartych na plikach pole st_atime zamapowanego pliku może zostać zaktualizowane w dowolnym momencie pomiędzy mmap() i usunięciem odpowiedniego mapowania; pierwsze odwołanie do zamapowanej strony spowoduje zaktualizowanie tego pola, jeśli nie stało się to wcześniej.

Pola st_ctime i st_mtime pliku zamapowanego z PROT_WRITE i MAP_SHARED zostanie zaktualizowane po zapisie do mapowanego obszaru, a przed późniejszym wywołaniem msync(2) ze znacznikiem MS_SYNC lub MS_ASYNC, jeśli taki wywołanie wystąpi.

Mapowania dużych stron (Huge TLB)

W przypadku mapowań korzystających z dużych (huge) stron, wymagania dotyczące argumentów mmap() i munmap() różnią się nieco, od wymagań mapowań, korzystających z natywnego systemowego rozmiaru strony.

W przypadku mmap(), offset musi być wielokrotnością używanego rozmiaru dużej strony. System automatycznie wyrówna length do wielokrotności używanego rozmiaru dużej strony.

W przypadku munmap(), addr i length muszą być wielokrotnościami używanego systemowego rozmiaru dużej strony.

Kod źródłowy programu

#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#define handle_error(msg) \
    do { perror(msg); exit(EXIT_FAILURE); } while (0)
int
main(int argc, char *argv[])
{
    int          fd;
    char         *addr;
    off_t        offset, pa_offset;
    size_t       length;
    ssize_t      s;
    struct stat  sb;
    if (argc < 3 || argc > 4) {
        fprintf(stderr, "%s file offset [length]\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    fd = open(argv[1], O_RDONLY);
    if (fd == -1)
        handle_error("open");
    if (fstat(fd, &sb) == -1)           /* To obtain file size */
        handle_error("fstat");
    offset = atoi(argv[2]);
    pa_offset = offset & ~(sysconf(_SC_PAGE_SIZE) - 1);
        /* offset for mmap() must be page aligned */
    if (offset >= sb.st_size) {
        fprintf(stderr, "offset is past end of file\n");
        exit(EXIT_FAILURE);
    }
    if (argc == 4) {
        length = atoi(argv[3]);
        if (offset + length > sb.st_size)
            length = sb.st_size - offset;
                /* Can't display bytes past end of file */
    } else {    /* No length arg ==> display to end of file */
        length = sb.st_size - offset;
    }
    addr = mmap(NULL, length + offset - pa_offset, PROT_READ,
                MAP_PRIVATE, fd, pa_offset);
    if (addr == MAP_FAILED)
        handle_error("mmap");
    s = write(STDOUT_FILENO, addr + offset - pa_offset, length);
    if (s != length) {
        if (s == -1)
            handle_error("write");
        fprintf(stderr, "partial write");
        exit(EXIT_FAILURE);
    }
    munmap(addr, length + offset - pa_offset);
    close(fd);
    exit(EXIT_SUCCESS);
}