1 .\"
2 .\" Mach Operating System
3 .\" Copyright (c) 1991,1990 Carnegie Mellon University
4 .\" All Rights Reserved.
5 .\"
6 .\" Permission to use, copy, modify and distribute this software and its
7 .\" documentation is hereby granted, provided that both the copyright
8 .\" notice and this permission notice appear in all copies of the
9 .\" software, derivative works or modified versions, and any portions
10 .\" thereof, and that both notices appear in supporting documentation.
11 .\"
12 .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
13 .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
14 .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
15 .\"
16 .\" Carnegie Mellon requests users of this software to return to
17 .\"
18 .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
19 .\" School of Computer Science
20 .\" Carnegie Mellon University
21 .\" Pittsburgh PA 15213-3890
22 .\"
23 .\" any improvements or extensions that they make and grant Carnegie Mellon
24 .\" the rights to redistribute these changes.
25 .\"
26 .\"
27 .\" HISTORY
28 .\" $Log: vm_allocate.man,v $
29 .\" Revision 2.5 93/03/18 15:16:34 mrt
30 .\" corrected types
31 .\" [93/03/12 16:55:09 lli]
32 .\"
33 .\" Revision 2.4 91/05/14 17:15:11 mrt
34 .\" Correcting copyright
35 .\"
36 .\" Revision 2.3 91/02/14 14:15:56 mrt
37 .\" Changed to new Mach copyright
38 .\" [91/02/12 18:16:54 mrt]
39 .\"
40 .\" Revision 2.2 90/08/07 18:47:08 rpd
41 .\" Created.
42 .\"
43 .TH vm_allocate 2 9/19/86
44 .CM 4
45 .SH NAME
46 .nf
47 vm_allocate \- allocates virtual memory for a task
48 .SH SYNOPSIS
49 .nf
50 .ft B
51 #include <mach.h>
52
53 .nf
54 .ft B
55 kern_return_t vm_allocate(target_task, address, size, anywhere)
56 mach_port_t target_task;
57 vm_address_t *address; /* in/out */
58 vm_size_t size;
59 boolean_t anywhere;
60
61
62 .fi
63 .ft P
64 .SH ARGUMENTS
65 .TP 15
66 .B
67 target_task
68 Task whose virtual address space is to be affected.
69 .TP 15
70 .B
71 address
72 Starting address. If the
73 .B anywhere
74 option is false,
75 an attempt is made to allocate virtual memory starting at
76 this virtual address. If this address is not at the beginning
77 of a virtual page, it will be rounded down to one.
78 If there is not enough space at this address, no memory will be allocated.
79 If the anywhere option is true, the input value of this address will
80 be ignored, and the space will be allocated wherever it is available.
81 In either case, the address at which memory was actually allocated will
82 be returned in
83 .B address
84 .
85 .TP 15
86 .B
87 size
88 Number of bytes to allocate (rounded by the system in a
89 machine dependent way to an integral number of virtual pages).
90 .TP 15
91 .B
92 anywhere
93 If true, the kernel should find and allocate any region of
94 the specified size, and return the address of the resulting region in
95 .B address
96 . If false, virtual memory will be allocated starting at
97 .B address
98 , rounded to a virtual page boundary if there
99 is sufficient space.
100
101 .SH DESCRIPTION
102 .B vm_allocate
103 allocates a region of virtual memory, placing it in the
104 specified task's address space. The physical memory is not actually
105 allocated until the new virtual memory is referenced. By default,
106 the kernel rounds all addresses down
107 to the nearest page boundary and all memory sizes up to the nearest page
108 size. The global variable
109 .B vm_page_size
110 contains the page size.
111 .B task_self_
112 returns
113 the value of the current task port which should be used as
114 the
115 .B target_task
116 argument in order to allocate
117 memory in the caller's address space. For languages other than C, these values
118 can be obtained by the calls
119 .B vm_statistics
120 and
121 .B task_self
122 .
123 Initially, the pages of allocated memory will be protected
124 to allow all forms of access, and will be inherited in child tasks as
125 a copy. Subsequent calls to
126 .B vm_protection
127 and
128 .B vm_inheritance
129 may
130 be used to change these properties. The allocated region is always
131 zero-filled.
132
133 .SH DIAGNOSTICS
134 .TP 25
135 KERN_SUCCESS
136 Memory allocated.
137 .TP 25
138 KERN_INVALID_ADDRESS
139 Illegal address specified.
140 .TP 25
141 KERN_NO_SPACE
142 Not enough space left to satisfy this request
143
144 .SH SEE ALSO
145 .B vm_deallocate, vm_inherit, vm_protect, vm_regions, vm_statistics,
146 .B task_self_
147
148
Cache object: 497203244244acaf54fadb5e97462002
|