1__GET_USER_PAGES(9)       Memory Management in Linux       __GET_USER_PAGES(9)
2
3
4

NAME

6       __get_user_pages - pin user pages in memory
7

SYNOPSIS

9       int __get_user_pages(struct task_struct * tsk, struct mm_struct * mm,
10                            unsigned long start, int nr_pages,
11                            unsigned int gup_flags, struct page ** pages,
12                            struct vm_area_struct ** vmas);
13

ARGUMENTS

15       tsk
16           task_struct of target task
17
18       mm
19           mm_struct of target mm
20
21       start
22           starting user address
23
24       nr_pages
25           number of pages from start to pin
26
27       gup_flags
28           flags modifying pin behaviour
29
30       pages
31           array that receives pointers to the pages pinned. Should be at
32           least nr_pages long. Or NULL, if caller only intends to ensure the
33           pages are faulted in.
34
35       vmas
36           array of pointers to vmas corresponding to each page. Or NULL if
37           the caller does not require them.
38

DESCRIPTION

40       Returns number of pages pinned. This may be fewer than the number
41       requested. If nr_pages is 0 or negative, returns 0. If no pages were
42       pinned, returns -errno. Each page returned must be released with a
43       put_page call when it is finished with. vmas will only remain valid
44       while mmap_sem is held.
45
46       Must be called with mmap_sem held for read or write.
47
48       __get_user_pages walks a process´s page tables and takes a reference to
49       each struct page that each user address corresponds to at a given
50       instant. That is, it takes the page that would be accessed if a user
51       thread accesses the given user virtual address at that instant.
52
53       This does not guarantee that the page exists in the user mappings when
54       __get_user_pages returns, and there may even be a completely different
55       page there in some cases (eg. if mmapped pagecache has been invalidated
56       and subsequently re faulted). However it does guarantee that the page
57       won´t be freed completely. And mostly callers simply care that the page
58       contains data that was valid *at some point in time*. Typically, an IO
59       or similar operation cannot guarantee anything stronger anyway because
60       locks can´t be held over the syscall boundary.
61
62       If gup_flags & FOLL_WRITE == 0, the page must not be written to. If the
63       page is written to, set_page_dirty (or set_page_dirty_lock, as
64       appropriate) must be called after the page is finished with, and before
65       put_page is called.
66
67       In most cases, get_user_pages or get_user_pages_fast should be used
68       instead of __get_user_pages. __get_user_pages should be used only if
69       you need some special gup_flags.
70

72Kernel Hackers Manual 2.6.         June 2019               __GET_USER_PAGES(9)
Impressum