---
name: "balloc"
section: "3g"
platform: "linux"
package: "libxg-dev"
version: "4.3-14"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/balloc"
---

# balloc(3g)

allocating, freeing, reading, writing bitmaps

## NAME

balloc, bfree, rdbitmap, wrbitmap, rdbitmapfile, wrbitmapfile - allocating, freeing, reading, writing bitmaps

## SYNOPSIS

```

```

**#include \<libc.h\>** **#include \<libg.h\>**

**Bitmap	\*balloc(Rectangle r, int ldepth)**

**void	bfree(Bitmap \*b)**

**void	rdbitmap(Bitmap \*b, int miny, int maxy, uchar \*data)**

**void	wrbitmap(Bitmap \*b, int miny, int maxy, uchar \*data)**

**Bitmap	\*rdbitmapfile(int fd)**

**void	wrbitmapfile(int fd, Bitmap \*b)**

## DESCRIPTION

A new bitmap is allocated with **balloc**; it will have the extent and depth given by its arguments, and will be filled with zeros. The *id* field contains the handle of the X **Pixmap** associated with the bitmap and the *cache* field is zero. *Balloc* returns 0 if the server has run out of bitmap resources. **Bfree** frees the resources used by its argument bitmap.

The remaining functions deal with moving groups of pixel values between bitmaps and user space or external files. There is a fixed format for the bitmap data in user space or on external files. A pixel with x-coordinate = *x* in a bitmap with **ldepth** = *l* will appear as w = 2^l contiguous bits in a byte, with the pixel's high order bit starting at the byte's bit number w\*(x mod 8/w), where bits within a byte are numbered 0 to 7 from the high order to the low order bit. If *w* is greater than 8, it is a multiple of 8, so pixel values take up an integral number of bytes. A *row* of bitmap *b* consists of the byte containing pixel *b***.r.min.x** and all the bytes up to and including the byte containing pixel *b***.r.max.x−1.**

*Rdbitmap* reads rows of pixels from bitmap *b* into *data*. The rows read have *y*=*ymin*,*ymin*+1, ...  *ymax*−1. Those rows must be within the range allowed by *b***.r.**

**Wrbitmap** replaces the specified rows of pixels in bitmap *b* with *data*.

*Rdbitmapfile* creates a bitmap from data contained an external file; *fd* should be a file descriptor obtained by opening such a file for reading. The external file should start with 5 ASCII integers: **ldepth**, **r.min.x**, **r.min.y**, **r.max.x**, and **r.max.y**. Each number is right-justified in 11 characters, followed by a blank. The rows of bitmap data, formatted as described above, follow the header. The returned bitmap is allocated using *balloc .* *Rdbitmapfile* returns 0 if the server has run out of bitmap resources.

*Wrbitmapfile* writes bitmap *b* onto file descriptor *fd*, which should be open for writing. The format is as just described for *rdbitmapfile*.

*Rdbitmapfile* and *wrbitmapfile* don't close *fd*.

## DIAGNOSTICS

Some errors can occur when accessing the internal bitmaps, when trying to malloc, or when trying to read or write the argument file descriptors; the graphics error function (see [*graphics*(3g)](/graphics/3g.md)) is called when this happens.

## SEE ALSO

[*bitmap*(7g)](/bitmap/7g.md), [*graphics*(3g)](/graphics/3g.md), [*bitblt*(3g)](/bitblt/3g.md).