home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / listings / v_06_08 / v6n8073a.txt < prev    next >
Text File  |  1989-09-28  |  7KB  |  210 lines
  1. /*
  2.  * Listing 5 :
  3.  * 
  4.  * Syntax of QNX specific functions used in listings 1 thru 4
  5.  */
  6.  
  7. /*
  8.  * createl() - start a task on any network CPU and attach to any tty device.
  9.  * 
  10.  * int createl(
  11.  *     (void *) cmd_buffer,  /* Work buffer, NULL will cause createl() to calloc() one. */
  12.  *     (unsigned) node_num,  /* Node number to run task on */
  13.  *     (unsigned) tty_num,   /* TTY number to attach task to */
  14.  *     (unsigned) transform, /* 0 = start new task, 1 = chain current task */
  15.  *     (unsigned) flags,     /* Create flags, defined in <task_msgs.h> */
  16.  *     (unsigned) priority,  /* Priority to run at */
  17.  *     (char *) stdin_str,   /* Device/file to open for stdin */
  18.  *     (char *) stdout_str,  /* Device/file to open for stdout */
  19.  *     (char *) stderr_str,  /* Device/file to open for stderr */
  20.  *     (char *) command_path,/* Command to execute */
  21.  *     (char *) arg1,        /* Argument passed to command */
  22.  *     .                                    "
  23.  *     .                                    "
  24.  *     .                                    "
  25.  *     (char *) argn,                       "
  26.  *     0                     /* End of arguments */
  27.  * );
  28.  * 
  29.  * Returns the task id if run concurrent or background, otherwise
  30.  * it will return the exit status of the task when it terminates.
  31.  * If the created task is not run concurrently or in the background,
  32.  * the current task will be suspended until the new task terminates.
  33.  * 
  34.  */
  35.  
  36. /*
  37.  * send() - send a message to another task.
  38.  * 
  39.  * The current (sending) task will block until the receiving task replies.
  40.  * 
  41.  * int send(
  42.  *     (unsigned) task_id,    /* Task to send message to */
  43.  *     (char *) sent_message, /* Buffer containing message sent */
  44.  *     (char *) reply_message,/* Buffer to receive reply in */
  45.  *     (unsigned) msg_size    /* Size of message to send */
  46.  * );
  47.  * 
  48.  * Returns the id of the task the message was sent to.
  49.  * 0 means the remote task doesn't exist or died before it replied.
  50.  * -1 means that an exception condition occured.
  51.  * 
  52.  */
  53.  
  54. /*
  55.  * receive() - receive a message from any or a specified task.
  56.  * 
  57.  * The current (receiving) task will block until a message is received.
  58.  * 
  59.  * int receive(
  60.  *     (unsigned) task_id,      /* Task id to receive message from */
  61.  *                              /* An id of 0 will receive from anyone */
  62.  *     (char *) message_buffer, /* Buffer to receive message into */
  63.  *     (unsigned) msg_size      /* Maximum message size to receive */
  64.  * );
  65.  * 
  66.  * Returns the id of the task the message was received from.
  67.  * 0 means the requested task does not exist or died before sending.
  68.  * -1 means an exception condition occured.
  69.  * 
  70.  */
  71.  
  72. /*
  73.  * reply() - reply to a received message.
  74.  * 
  75.  * This does not block the task, and replies can be made to sending tasks
  76.  * in any order.
  77.  * 
  78.  * void reply(
  79.  *     (unsigned) task_id,     /* Task to reply to */
  80.  *     (char *) reply_message, /* Message to send */
  81.  *     (unsigned) msg_size     /* Number of bytes of message to send */
  82.  * );
  83.  * 
  84.  * This is a void function.
  85.  * A reply to a non-existent task or a task that is not awaiting a reply
  86.  * is a null operation.  The task replied to will unblock and resume
  87.  * processing.
  88.  * 
  89.  */
  90.  
  91. /*
  92.  * error() - prints a formatted error message.
  93.  * 
  94.  * The syntax is identical to printf() except that it doesn't return.
  95.  * 
  96.  * void error(
  97.  *     (char *) format,  /* Pointer to format string */
  98.  *     arg1,             /* Argument to place in output */
  99.  *     .                                 "
  100.  *     .                                 "
  101.  *     .                                 "
  102.  *     argn                              "
  103.  * );
  104.  * 
  105.  * This function is identical to the following :
  106.  * {
  107.  *     printf(fmt, arg1, . . ., argn)
  108.  *     exit(-1);
  109.  * }
  110.  * 
  111.  */
  112.  
  113. /*
  114.  * term_load() - loads terminal definition into a structure tcap_entry
  115.  * 
  116.  * int term_load( (FILE *) fp);
  117.  * 
  118.  * (FILE *) fp can be any open device, but usually stdout or stderr will
  119.  * be the device used.
  120.  * 
  121.  */
  122.  
  123. /*
  124.  * term_cur() - position cursor at row, col of output device.
  125.  * 
  126.  * void term_cur(
  127.  *     (int) row,        /* 0,0 is upper left corner of display */
  128.  *     (int) col
  129.  * );
  130.  * 
  131.  */
  132.  
  133. /*
  134.  * term_restore_image() - restores display from a memory buffer.
  135.  * 
  136.  * int term_restore_image(
  137.  *     (int) row, (int) col, /* Where to position the text */
  138.  *     (char *) buffer,      /* Pointer to buffer containing screen data */
  139.  *     (int) length,         /* Number of characters to put on screen */
  140.  *     (unsigned) segment    /* Segment that contains the buffer */
  141.  * );
  142.  * 
  143.  * Returns number of bytes per character, including attribute bytes.
  144.  * This will always be 3 on "dumb" terminals.
  145.  * 
  146.  * This function is identical to video_restore_image() except that it
  147.  * will function on any supported "dumb" terminal.
  148.  * 
  149.  * NOTE : If video_save_image() is used to read a display, and
  150.  * term_restore_image() is used to restore the data to another device,
  151.  * both must support the same number of bytes per character, otherwise
  152.  * the effect on the terminal that the image is restored to is likely
  153.  * to be chaos!
  154.  * 
  155.  */
  156.  
  157. /*
  158.  * term_video_on() - sets up a "shadow" screen buffer for use with
  159.  * term_restore_image(), term_save_image(), etc.
  160.  * 
  161.  * void term_video_on();
  162.  * 
  163.  * Uses no arguments.
  164.  */
  165.  
  166. /*
  167.  * video_save_image() - save a portion of the display to a buffer.
  168.  * 
  169.  * int video_save_image(
  170.  *     (int) device,         /* Window to save, -1 = current window */
  171.  *     (int) row, (int) col, /* Where to start the save */
  172.  *     (char *) buffer,      /* A buffer to save the screen data */
  173.  *     (int) length,         /* The number of characters to save */
  174.  *     (unsigned) segment    /* The segment where buffer is found */
  175.  * );
  176.  * 
  177.  * Returns number of bytes stored per character, including attribute bytes.
  178.  * This function is identical to term_save_image() except that it only
  179.  * works on a console (direct video) device, not a "dumb" terminal.
  180.  * 
  181.  */
  182.  
  183. /*
  184.  * video_get_size() - get the size of the video device specified.
  185.  * 
  186.  * unsigned video_get_size(
  187.  *     (unsigned) device    /* Window number, -1 = current window */
  188.  * );
  189.  * 
  190.  * Returns a word if size information where :
  191.  *     n = video_get_size(-1);
  192.  *     rows = (n >> 8) & 0xff;
  193.  *     cols = n & 0xff;
  194.  * 
  195.  */
  196.  
  197. /*
  198.  * video_get_state() - returns the display state information.
  199.  * 
  200.  * void video_get_state(
  201.  *     (int) device,           /* The device to read, -1 = current window */
  202.  *     (struct state_entry *) buffer  /* A pointer to a structure defined */
  203.  * );                                 /* in <dev.h> */
  204.  * 
  205.  * A void function.
  206.  * The buffer will contain cursor position, screen size, default attributes,
  207.  * and other display information.
  208.  * 
  209.  */
  210.