Using image as a mask in cairo (a c library)

I'm using cairo but have run into a snag. I want to load a raster image (a .png file) and then use that image as a mask. The image I am loading is black, and I would like to use it as clipping mask, or regular mask and 'stamp' so that I could change the image from black to another color (or gradient.) Pseudo-code or comments greatly appreciated. And this for my own project, not homework. Thanks.

I should probably add that the .png I am loading is a shape, a closed path, e.g. a palm tree.

And how much of the online manual have you read this time?

That is, before I go and read it for you (which is getting kinda boring)

Figured it out, and I have read the online manual several times. It does not cover masking from a raster file. (Not masking a raster file, that's easy) There is a heck of a lot of cairo that is essentially undocumented, save for the api, which is not a replacement for simple usage examples. Still cairo does rock. For the record, I had to create a new surface from a png file. Create a mask from that surface. Set the source, mask a new context , and then write that context back to the original surface.