<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>__get_user_pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="The Linux Kernel API" /><link rel="up" href="ch04s03.html" title="More Memory Management Functions" /><link rel="prev" href="API-zap-vma-ptes.html" title="zap_vma_ptes" /><link rel="next" href="API-vm-insert-page.html" title="vm_insert_page" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span class="phrase">__get_user_pages</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-zap-vma-ptes.html">Prev</a> </td><th width="60%" align="center">More Memory Management Functions</th><td width="20%" align="right"> <a accesskey="n" href="API-vm-insert-page.html">Next</a></td></tr></table><hr /></div><div class="refentry"><a id="API---get-user-pages"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>__get_user_pages —
pin user pages in memory
</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">long <strong class="fsfunc">__get_user_pages </strong>(</code></td><td>struct task_struct * <var class="pdparam">tsk</var>, </td></tr><tr><td> </td><td>struct mm_struct * <var class="pdparam">mm</var>, </td></tr><tr><td> </td><td>unsigned long <var class="pdparam">start</var>, </td></tr><tr><td> </td><td>unsigned long <var class="pdparam">nr_pages</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">gup_flags</var>, </td></tr><tr><td> </td><td>struct page ** <var class="pdparam">pages</var>, </td></tr><tr><td> </td><td>struct vm_area_struct ** <var class="pdparam">vmas</var>, </td></tr><tr><td> </td><td>int * <var class="pdparam">nonblocking</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a id="idm139749899595936"></a><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>tsk</code></em></span></dt><dd><p>
task_struct of target task
</p></dd><dt><span class="term"><em class="parameter"><code>mm</code></em></span></dt><dd><p>
mm_struct of target mm
</p></dd><dt><span class="term"><em class="parameter"><code>start</code></em></span></dt><dd><p>
starting user address
</p></dd><dt><span class="term"><em class="parameter"><code>nr_pages</code></em></span></dt><dd><p>
number of pages from start to pin
</p></dd><dt><span class="term"><em class="parameter"><code>gup_flags</code></em></span></dt><dd><p>
flags modifying pin behaviour
</p></dd><dt><span class="term"><em class="parameter"><code>pages</code></em></span></dt><dd><p>
array that receives pointers to the pages pinned.
Should be at least nr_pages long. Or NULL, if caller
only intends to ensure the pages are faulted in.
</p></dd><dt><span class="term"><em class="parameter"><code>vmas</code></em></span></dt><dd><p>
array of pointers to vmas corresponding to each page.
Or NULL if the caller does not require them.
</p></dd><dt><span class="term"><em class="parameter"><code>nonblocking</code></em></span></dt><dd><p>
whether waiting for disk IO or mmap_sem contention
</p></dd></dl></div></div><div class="refsect1"><a id="idm139749899578400"></a><h2>Description</h2><p>
Returns number of pages pinned. This may be fewer than the number
requested. If nr_pages is 0 or negative, returns 0. If no pages
were pinned, returns -errno. Each page returned must be released
with a <code class="function">put_page</code> call when it is finished with. vmas will only
remain valid while mmap_sem is held.
</p><p>
Must be called with mmap_sem held for read or write.
</p><p>
__get_user_pages walks a process's page tables and takes a reference to
each struct page that each user address corresponds to at a given
instant. That is, it takes the page that would be accessed if a user
thread accesses the given user virtual address at that instant.
</p><p>
This does not guarantee that the page exists in the user mappings when
__get_user_pages returns, and there may even be a completely different
page there in some cases (eg. if mmapped pagecache has been invalidated
and subsequently re faulted). However it does guarantee that the page
won't be freed completely. And mostly callers simply care that the page
contains data that was valid *at some point in time*. Typically, an IO
or similar operation cannot guarantee anything stronger anyway because
locks can't be held over the syscall boundary.
</p><p>
If <em class="parameter"><code>gup_flags</code></em> & FOLL_WRITE == 0, the page must not be written to. If
the page is written to, set_page_dirty (or set_page_dirty_lock, as
appropriate) must be called after the page is finished with, and
before put_page is called.
</p><p>
If <em class="parameter"><code>nonblocking</code></em> != NULL, __get_user_pages will not wait for disk IO
or mmap_sem contention, and if waiting is needed to pin all pages,
*<em class="parameter"><code>nonblocking</code></em> will be set to 0.
</p><p>
In most cases, get_user_pages or get_user_pages_fast should be used
instead of __get_user_pages. __get_user_pages should be used only if
you need some special <em class="parameter"><code>gup_flags</code></em>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-zap-vma-ptes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch04s03.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-vm-insert-page.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">zap_vma_ptes</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">vm_insert_page</span></td></tr></table></div></body></html>
distrib
>
Fedora
>
18
>
x86_64
>
media
>
updates
>
by-pkgid
>
1a595394b241504ff370a8d12ebfcea7
>
files
>
2322
