DESCRIPTION

These procedures manage a collection of bitmaps (one-plane
pixmaps) being used by an application. The procedures
allow bitmaps to be re-used efficiently, thereby avoiding
server overhead, and also allow bitmaps to be named with
character strings.

Tk_AllocBitmapFromObj returns a Pixmap identifier for a |
bitmap that matches the description in objPtr and is suit |
able for use in tkwin. It re-uses an existing bitmap, if |
possible, and creates a new one otherwise. ObjPtr's value |
must have one of the following forms:
containing a bitmap description in the
standard X11 or X10 format.

name Name must be the name of a bitmap
defined previously with a call to
Tk_DefineBitmap. The following names
are pre-defined by Tk:

error The international "don't"
symbol: a circle with a
diagonal line across it.

gray75 ||
75% gray: a checkerboard |
pattern where three out of |
four bits are on.

gray50 50% gray: a checkerboard
pattern where every other
bit is on.

gray25 ||
25% gray: a checkerboard |
pattern where one out of |
every four bits is on.

gray12 12.5% gray: a pattern
where one-eighth of the
bits are on, consisting of
every fourth pixel in
every other row.

hourglass An hourglass symbol.

info A large letter ``i''.

questhead The silhouette of a human
head, with a question mark
in it.

question A large question-mark.

warning A large exclamation point.

In addition, the following pre-defined
names are available only on the Macin
tosh platform:

document A generic document.

stationery Document stationery.

accessory A desk accessory.

folder Generic folder icon.

pfolder A locked folder.

trash A trash can.

floppy A floppy disk.

ramdisk A floppy disk with c

ptrace - process trace

SYNOPSIS
#include <sys/ptrace.h>

long int ptrace(enum __ptrace_request request, pid_t pid,
void * addr, void * data)

DESCRIPTION
The ptrace system call provides a means by which a parent
process may observe and control the execution of another
process, and examine and change its core image and regis
ters. It is primarily used to implement breakpoint debug
ging and system call tracing.

The parent can initiate a trace by calling fork(2) and
having the resulting child do a PTRACE_TRACEME, followed
(typically) by an exec(2). Alternatively, the parent may
commence trace of an existing process using PTRACE_ATTACH.

While being traced, the child will stop each time a signal
is delivered, even if the signal is being ignored. (The
exception is SIGKILL, which has its usual effect.) The
parent will be notified at its next wait(2) and may
inspect and modify the child process while it is stopped.
The parent then causes the child to continue, optionally
ignoring the delivered signal (or even delivering a dif
ferent signal instead).

When the parent is finished tracing, it can terminate the
child with PTRACE_KILL or cause it to continue executing
in a normal, untraced mode via PTRACE_DETACH.

The value of request determines the action to be per
formed:

PTRACE_TRACEME
Indicates that this process is to be traced by its
parent. Any signal (except SIGKILL) delivered to
this process will cause it to stop and its parent
to be notified via wait. Also, all subsequent
calls to exec by this process will cause a SIGTRAP
to be sent to it, giving the parent a chance to
gain control before the new program begins execu
tion. A process probably shouldn't make this
request if its parent isn't expecting to trace it.
(pid, addr, and data are ignored.)

The above request is used only by the child process; the
rest are used only by the parent. In the following
requests, pid specifies the child process to be acted on.
For requests other than PTRACE_KILL, the child process
Reads a word at the location addr in the child's
memory, returning the word as the result of the
ptrace call. Linux does not have separate text and
data address spaces, so the two requests are cur
rently equivalent. (data is ignored.)

PTRACE_PEEKUSER
Reads a word at offset addr in the child's USER
area, which holds the registers and other informa
tion about the process (see <linux/user.h> and
<sys/user.h>). The word is returned as the result
of the ptrace call. Typically the offset must be
word-aligned, though this might vary by architec
ture. (data is ignored.)

PTRACE_POKETEXT, PTRACE_POKEDATA
Copies a word from location data in the parent's
memory to location addr in the child's memory. As
above, the two requests are currently equivalent.

PTRACE_POKEUSER
Copies a word from location data in the parent's
memory to offset addr in the child's USER area. As
above, the offset must typically be word-alignable image. The same bitmap file could be
read at run-time using Tk_GetBitmap: |
Pixmap bitmap; |
bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap");|
The second form is a bit more flexible (the file could be
modified after the program has been compiled, or a differ
ent string could be provided to read a different file),
but it is a little slower and requires the bitmap file to
exist separately from the program.

Tk maintains a database of all the bitmaps that are cur
rently in use. Whenever possible, it will return an
existing bitmap rather than creating a new one. When a
bitmap is no longer used, Tk will release it automati
cally. This approach can substantially reduce server
overhead, so Tk_AllocBitmapFromObj and Tk_GetBitmap should
generally be used in preference to Xlib procedures like
XReadBitmapFile.

The bitmaps returned by Tk_AllocBitmapFromObj and Tk_Get
Bitmap are shared, so callers should never modify them.
If a bitmap must be modified dynamically, then it should
be created by calling Xlib procedures such as XReadBitmap
File or XCreatePixmap directly.
Tk_GetBitmap. Given an X Pixmap argument, it returns the
textual description that was passed to Tk_GetBitmap when
the bitmap was created. Bitmap must have been the return
value from a previous call to Tk_AllocBitmapFromObj or
Tk_GetBitmap.

Tk_SizeOfBitmap returns the dimensions of its bitmap argu
ment in the words pointed to by the widthPtr and heightPtr
arguments. As with Tk_NameOfBitmap, bitmap must have been
created by Tk_AllocBitmapFromObj or Tk_GetBitmap.

When a bitmap is no longer needed, Tk_FreeBitmapFromObj or |
Tk_FreeBitmap should be called to release it. For |
Tk_FreeBitmapFromObj the bitmap to release is specified |
with the same information used to create it; for |
Tk_FreeBitmap the bitmap to release is specified with its |
Pixmap token. There should be exactly one call to |
Tk_FreeBitmapFromObj or Tk_FreeBitmap for each call to |
Tk_AllocBitmapFromObj or Tk_GetBitmap.

BUGS
In determining whether an existing bitmap can be used to
satisfy a new request, Tk_AllocBitmapFromObj and Tk_Get
Bitmap consider only the immediate value of the string
description. For example, when a file name is passed to
Tk_GetBitmap, Tk_GetBitmap will assume it is safe to re-
use an existing bitmap created from the same file name:
it will not check to see whether the file itself has
changed, or whether the current directory has changed,
thereby causing the name to refer to a different file.

KEYWORDS
bitmap, pixmap

Man(1) output converted with
man2html