-*-Text-*-

HUMBLE - Functions for hacking inferiors.


    #include <sys/humble.h>

The header file for using the humble package.


    int j_create()

Creates an inferior, returns an FD or -1 if failure

This FD can be used just like any other file FD.  It can even be used to do
I/O, although that is of limited utility.  Conversely, a file FD obtained
from open() (by opening "USR:COMSAT IV" for example) will work with the
rest of the functions in the humble package, you don't have to use
j_create().  Although in that case it is kind of hard to control the
details of opening the USR: device.

Possible errors:
 - Already have 8 inferiors.
 - This job has no free channels.
 - The system has no free job slots.


    int j_kill(fd)
      int fd;

Kills the specified inferior.  Just like close() except it actually
destroys the job.  Can only be applied to the last open FD.  (Although I
don't see much advantage to dup'ing a job FD, it will work...)

Possible errors:
 - Not a job FD.
 - Not the last open FD.


    int j_read(fd, addr, buf, count)
	int fd, addr, *buf, count;

Copies COUNT words into BUF from the inferior starting at ADDR.  Normally
returns 0.  If error, it returns the number of words left to be written.

Possible errors:
 - Not a job FD, negative count, negative or huge address.
 - Tried to read nonexistent memory.


    int j_write(fd, addr, buf, count)
	int fd, addr, *buf, count;

Copies COUNT words from BUF into the inferior starting at ADDR.  Creating
memory if it doesn't exist.  Normally returns 0.  If error it returns the
number of words left to be written.

Possible errors:
 - Not a job FD, negative count, negative or huge address.
 - System doesn't currently have enough virtual address space.
 - Can't write into a foreign job.


    int j_dump(job_fd, file_fd)
	int job_fd, file_fd;

Writes a PDUMP file for the job on the freshly opened file.
Returns 0 if success and -1 if failure.

Possible errors:
 - Not a job FD.
 - File FD isn't open to DSK.
 - DSK or directory full, etc.


    int j_load(job_fd, file_fd)
	int job_fd, file_fd;

Loads a PDUMP or SBLK file into the job from the freshly opened file.
Returns 0 if success and -1 if failure.

Possible errors:
 - Not a job FD.
 - File FD isn't open to DSK.
 - File is in the wrong format.


    int j_vread(fd, var, loc)
      int fd, var, *loc;

Read a user variable.  Returns 0 if it wins, -1 if failure.
VAR is a user variable specifier.  LOC is where to store the result.

The header file humble.h defines the macro SIXBIT so that user variable
specifiers can be easily constructed.  SIXBIT("USTP") returns the integer
that is the sixbit of "USTP".  Other specifiers acceptable to .CALL USRVAR
will work as well.

Possible errors:
 - Not a job FD.
 - No such user variable.


    int j_vwrite(fd, var, val)
      int fd, var, val;

Write a user variable.  Returns 0 if it wins, -1 if failure.
VAR is a user variable specifier.  VAL is the new value.

Possible errors:
 - Not a job FD.
 - No such user variable.
 - Can't write into this job.


    int j_atty(fd)
      int fd;

Allow an inferior to make use of the TTY.  Returns 0 if it wins, -1
if failure.
Possible errors:
 - Not a job FD.
 - Job isn't an inferior.


    int j_dtty()

Devour the TTY.  Always returns 0.  Can't possibly fail!