Returns the area that contains the given address (within your own team's address space). The argument needn't be the starting address of an area, nor must it start on a page boundary: If the address lies anywhere within one of your application's areas, the ID of that area is returned.

Since the address is taken to be in the local address space, the area that's returned will also be local—it will have been created or cloned by your application.

See also: find_area()

Creates a new area (the clone area) that maps to the same physical memory as an existing area (the source area).

The cloned area inherits the source area's locking scheme.

Usually, the source area and clone area are in two different applications. It's possible to clone an area from a source that's in the same application, but there's not much reason to do so unless you want the areas to have different protections.

If clone_area() clone is successful, the clone's area_id is returned. Otherwise, it returns a descriptive error code, listed below.

Creates a new area and returns its area_id.

/* Set the address to a page boundary. */
char *addr = (char *)(B_PAGE_SIZE * 100);

/* Pass the address of addr as the second argument. */
create_area( "my area", &addr, ...);

If create_area() is successful, the new area_id number is returned. If it's unsuccessful, one of the following error constants is returned.

Deletes the designated area. If no one other area maps to the physical memory that this area represents, the memory is freed. After being deleted, the area value is invalid as an area identifier.

Warning

Currently, anybody can delete any area—the act isn't denied if, for example, the area_id argument was created by another application. This freedom will be rescinded in a later release. Until then, try to avoid deleting other application's areas.

Returns an area that has a name that matches the argument. Area names needn't be unique—successive calls to this function with the same argument value may not return the same area_id.

What you do with the area you've found depends on where it came from:

• If you're finding an area that your own application created or cloned, you can use the returned ID directly.

• If the area was created or cloned by some other application, you should immediately clone the area (unless you're doing something truly innocuous, such as simply examining the area's info structure).

See also: area_for()

struct {} area_info

Copies information about a particular area into the area_info structure designated by info. The first version of the function designates the area directly, by area_id.

The get_next_area_info() version lets you step through the list of a team's areas through iterated calls on the function. The team argument identifies the team you want to look at; a team value of 0 means the team of the calling thread. The cookie argument is a placemark; you set it to 0 on your first call, and let the function do the rest. The function returns B_BAD_VALUE when there are no more areas to visit:

/* Get the area_info for every area in this team. */
area_info info;
int32 cookie = 0;

while (get_next_area_info(0, &cookie, &info) == B_OK)
   ...

The area_info structure is:

typedef struct area_info {
    area_id area;
    char    name[B_OS_NAME_LENGTH];
    size_t  size;
    uint32  lock;
    uint32  protection;
    team_id team;
    size_t  ram_size;
    uint32  copy_count;
    uint32  in_count;
    uint32  out_count;
    void*   address;
} area_info;

The fields are:

The final four fields give information about the area that's useful in diagnosing system use. The fields are particularly valuable if you're hunting for memory leaks:

Sets the size of the designated area to new_size, measured in bytes. The new_size argument must be a multiple of B_PAGE_SIZE (4096).

Size modifications affect the end of the area's existing memory allocation: If you're increasing the size of the area, the new memory is added to the end of area; if you're shrinking the area, end pages are released and freed. In neither case does the area's starting address change, nor is existing data modified (except, of course, for data that's lost due to shrinkage).

Resizing affects all areas that refer to this areas physical memory. For example, if B is a clone of A, and you resize A, B will be automatically resized (if possible).

Sets the given area's read and write protection. The new_protection argument is a mask that specifies one or both of the values B_READ_AREA and B_WRITE_AREA. The former means that the area can be read; the latter, that it can be written to. An area's protection only applies to access to the underlying memory through that specific area. Different area clones that refer to the same memory may have different protections.