home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d2xx / d282 / rcs.lha / RCS / rcs.zoo / rcs / rsbx.lib / rsbx.lib.doc < prev    next >
Text File  |  1989-11-08  |  15KB  |  516 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. rsbx.lib/ChildStatus()
  6. rsbx.lib/CreateFamily()
  7. rsbx.lib/EmptyMorgue()
  8. rsbx.lib/EscapeAdditions()
  9. rsbx.lib/EscapeString()
  10. rsbx.lib/LaunchChildl()
  11. rsbx.lib/LaunchChildv()
  12. rsbx.lib/OrphanChild()
  13. rsbx.lib/OrphanChildren()
  14. rsbx.lib/pclose()
  15. rsbx.lib/popenl()
  16. rsbx.lib/popenv()
  17. rsbx.lib/WaitChild()
  18.  
  19.  
  20. rsbx.lib/ChildStatus()                                   rsbx.lib/ChildStatus()
  21.  
  22.    NAME
  23.     ChildStatus -- Check completion status of child process.
  24.  
  25.    SYNOPSIS
  26.     completion = ChildStatus(child, status)
  27.  
  28.     struct ChildNode *ChildStatus(struct ChildNode *, long *);
  29.  
  30.    FUNCTION
  31.     Checks if a child process has completed and sets status to the return
  32.         code from the child process if it has.
  33.  
  34.    INPUTS
  35.     child         - Child process identifier returned from LaunchChildX();
  36.     status        - Pointer to a long to place the return code from the
  37.                     child process in.
  38.  
  39.    RESULT
  40.     completion    - Child process identifier if child is a child process
  41.                     of this process and has completed. If child is a child
  42.                     process of this process and has not completed, then
  43.             completion is 0 and status is set to 0. If child is
  44.                     not a child procewss of this process, then completion
  45.                     is 0 and status will be non-zero.
  46.  
  47.    NOTES
  48.  
  49.    SEE ALSO
  50.     CreateFamily(), EmptyMorgue(), LaunchChildl(), LaunchChildv(),
  51.     OrphanChild(), OrphanChildren(), WaitChild().
  52.  
  53.    BUGS
  54.     None known.
  55.  
  56.  
  57. rsbx.lib/CreateFamily()                                 rsbx.lib/CreateFamily()
  58.  
  59.    NAME
  60.     CreateFamily -- 
  61.  
  62.    SYNOPSIS
  63.     success = CreateFamily()
  64.  
  65.     int CreateFamily( void );
  66.  
  67.    FUNCTION
  68.     This function initializes the structures used to keep track of child
  69.         processes of this process.
  70.  
  71.    INPUTS
  72.  
  73.    RESULT
  74.     success       - Zero if unable to allocate and initialize needed
  75.                     structures.
  76.  
  77.    NOTES
  78.  
  79.    SEE ALSO
  80.     ChildStatus(), EmptyMorgue(), LaunchChildl(), LaunchChildv(),
  81.     OrphanChild(), OrphanChildren(), WaitChild().
  82.  
  83.    BUGS
  84.     None Known.
  85.  
  86.  
  87. rsbx.lib/EmptyMorgue()                                   rsbx.lib/EmptyMorgue()
  88.  
  89.    NAME
  90.     EmptyMorgue -- Process child termination messages.
  91.  
  92.    SYNOPSIS
  93.     EmptyMorgue()
  94.  
  95.     void EmptyMorgue( void );
  96.  
  97.    FUNCTION
  98.     This function processes any termination messages from child processes
  99.         of this process.
  100.  
  101.    INPUTS
  102.  
  103.    RESULT
  104.  
  105.    NOTES
  106.  
  107.    SEE ALSO
  108.     ChildStatus(), CreateFamily(), LaunchChildl(), LaunchChildv(),
  109.     OrphanChild(), OrphanChildren(), WaitChild().
  110.  
  111.    BUGS
  112.     None Known.
  113.  
  114.  
  115. rsbx.lib/EscapeAdditions()                           rsbx.lib/EscapeAdditions()
  116.  
  117.    NAME
  118.     EscapeAdditions -- Return number of characters to escape an argument.
  119.  
  120.    SYNOPSIS
  121.     escapes = EscapeAdditions(argv)
  122.  
  123.     int EscapeAdditions(char *);
  124.  
  125.    FUNCTION
  126.     Determines the number of extra characters that are needed to escape
  127.         a command argument for AmigaDos command parsing.
  128.  
  129.    INPUTS
  130.     argv          - Argument to check.
  131.  
  132.    RESULT
  133.     escapes       - The number of characters that need to be added to the
  134.                     argument to escape the characters special to AmigaDos.
  135.  
  136.    NOTES
  137.     Characters special to AmigaDos are " [0x22], * [0x2a], ESC [0x1b],
  138.         LF [0x0a], SP [0x20].
  139.  
  140.    SEE ALSO
  141.     EscapeAdditions(), EscapeString().
  142.  
  143.    BUGS
  144.     Thinks spaces need an AmigaDos escape character preceeding them.
  145.  
  146.  
  147. rsbx.lib/EscapeString()                                 rsbx.lib/EscapeString()
  148.  
  149.    NAME
  150.     EscapeString -- Copy argument to buffer escaping as needed.
  151.  
  152.    SYNOPSIS
  153.     dest = EscapeString(buffer, argv)
  154.  
  155.     char *EscapeAdditions(char *, char *);
  156.  
  157.    FUNCTION
  158.     Copies a string containing a single argument to a buffer, escaping
  159.         characters special to AmigaDos.
  160.  
  161.    INPUTS
  162.     buffer        - Buffer for escaped argument string.
  163.     argv          - Argument string to escape.
  164.  
  165.    RESULT
  166.     dest          - The same as buffer.
  167.  
  168.    NOTES
  169.     Characters special to AmigaDos are " [0x22], * [0x2a], ESC [0x1b],
  170.         LF [0x0a], SP [0x20].
  171.  
  172.    SEE ALSO
  173.     EscapeAdditions(), EscapeString().
  174.  
  175.    BUGS
  176.     Thinks spaces need an AmigaDos escape character preceeding them.
  177.  
  178.  
  179. rsbx.lib/LaunchChildl()                                 rsbx.lib/LaunchChildl()
  180.  
  181.    NAME
  182.     LaunchChildl -- Launch a child process with argument list.
  183.  
  184.    SYNOPSIS
  185.     cpid = LaunchChildl(envp, name, arg0, ..., argn, NULL)
  186.  
  187.     struct ChildNode *LaunchChildl(struct LAUNCHENV *, char *, char *, ...);
  188.  
  189.    FUNCTION
  190.     This function behaves like a combination of the Unix 'fork' and 'execl'
  191.         functions. That is, a new process is created, as with 'fork', and
  192.         executes a load module, as with 'execl'.
  193.  
  194.    INPUTS
  195.     envp          - Pointer to a LAUNCHENV structure that has been
  196.                     initialized with apropriate values prior to calling
  197.                     this function. The LAUNCHENV structure only need exist
  198.                     during the execution of this function.
  199.     name          - Name of the file to execute.
  200.     arg0          - Same as name, by Unix convention.
  201.        ...           - Other command line arguments needed by the file to be
  202.                     executed.
  203.     NULL          - Zero.
  204.  
  205.    RESULT
  206.     cpid          - Pointer to a ChildNode structure, used to identify the
  207.                     child process.
  208.  
  209.    NOTES
  210.     struct LAUNCHENV
  211.             {
  212.             long priority;   priority for child process
  213.             ULONG stack;     stack size for child process.
  214.                               If zero, stack size of calling
  215.                               process will be used.
  216.             BPTR std_in;     AmigaDos filehandle for child's
  217.                               Input() stream. If zero, Input()
  218.                               stream of calling process used.
  219.             BPTR std_out;    AmigaDos filehandle for child's
  220.                               Output() stream. If zero, Output()
  221.                               stream of calling process used.
  222.             BPTR console;    console window handler port for
  223.                               child.
  224.             BPTR le_fh1;     AmigaDos filehandle for child to
  225.                               close at exit.
  226.             BPTR le_fh2;     AmigaDos filehandle for child to
  227.                               close at exit.
  228.             };
  229.  
  230.    SEE ALSO
  231.     ChildStatus(), CreateFamily(), EmptyMorgue(), LaunchChildv(),
  232.     OrphanChild(), OrphanChildren(), WaitChild().
  233.  
  234.    BUGS
  235.     This function does not create a complete CLI enviroment for the child
  236.         process. Use of this function with a command that expects a BCPL
  237.         environment will crash the system.
  238.  
  239.  
  240. rsbx.lib/LaunchChildv()                                 rsbx.lib/LaunchChildv()
  241.  
  242.    NAME
  243.     LaunchChildv -- Launch a child process with argument list.
  244.  
  245.    SYNOPSIS
  246.     cpid = LaunchChildv(envp, name, argv)
  247.  
  248.     struct ChildNode *LaunchChildv(struct LAUNCHENV *, char **);
  249.  
  250.    FUNCTION
  251.     This function behaves like a combination of the Unix 'fork' and 'execv'
  252.         functions. That is, a new process is created, as with 'fork', and
  253.         executes a load module, as with 'execv'.
  254.  
  255.    INPUTS
  256.     envp          - Pointer to a LAUNCHENV structure that has been
  257.                     initialized with apropriate values prior to calling
  258.                     this function. The LAUNCHENV structure only need exist
  259.                     during the execution of this function.
  260.     name          - Name of the file to execute.
  261.     argv          - An array of pointers to the argument strings for the
  262.                     command. The last argument pointer must be followed
  263.                     by a 0 pointer. The first pointer, argv[0], is the
  264.                     same as name, by unix convention.
  265.  
  266.    RESULT
  267.     cpid          - Pointer to a ChildNode structure, used to identify the
  268.                     child process.
  269.  
  270.    NOTES
  271.     struct LAUNCHENV
  272.             {
  273.             long priority;   priority for child process
  274.             ULONG stack;     stack size for child process.
  275.                               If zero, stack size of calling
  276.                               process will be used.
  277.             BPTR std_in;     AmigaDos filehandle for child's
  278.                               Input() stream. If zero, Input()
  279.                               stream of calling process used.
  280.             BPTR std_out;    AmigaDos filehandle for child's
  281.                               Output() stream. If zero, Output()
  282.                               stream of calling process used.
  283.             BPTR console;    console window handler port for
  284.                               child.
  285.             BPTR le_fh1;     AmigaDos filehandle for child to
  286.                               close at exit.
  287.             BPTR le_fh2;     AmigaDos filehandle for child to
  288.                               close at exit.
  289.             };
  290.  
  291.    SEE ALSO
  292.     ChildStatus(), CreateFamily(), EmptyMorgue(), LaunchChildl(),
  293.     OrphanChild(), OrphanChildren(), WaitChild().
  294.  
  295.    BUGS
  296.     This function does not create a complete CLI enviroment for the child
  297.         process. Use of this function with a command that expects a BCPL
  298.         environment will crash the system.
  299.  
  300.  
  301. rsbx.lib/OrphanChild()                                   rsbx.lib/OrphanChild()
  302.  
  303.    NAME
  304.     OrphanChild -- Dis-associate a child process from this process.
  305.  
  306.    SYNOPSIS
  307.     success = OrphanChild(child)
  308.  
  309.     int OrphanChild(struct ChildNode * );
  310.  
  311.    FUNCTION
  312.     This function will dis-associate a child process from this process and
  313.         free the structures used to track the child process.
  314.  
  315.    INPUTS
  316.     child         - Child identifier returned by LaunchChildl() or by
  317.                     LaunchChildv().
  318.  
  319.    RESULT
  320.     success       - Zero if invalid child identifier.
  321.  
  322.    NOTES
  323.  
  324.    SEE ALSO
  325.     ChildStatus(), CreateFamily(), EmptyMorgue(), LaunchChildl(),
  326.     LaunchChildv(), OrphanChildren(), WaitChild().
  327.  
  328.    BUGS
  329.     None Known.
  330.  
  331.  
  332. rsbx.lib/OrphanChildren()                             rsbx.lib/OrphanChildren()
  333.  
  334.    NAME
  335.     OrphanChildren -- Orphan all child processes of this process.
  336.  
  337.    SYNOPSIS
  338.     OrphanChildren()
  339.  
  340.     void OrphanChildren( void );
  341.  
  342.    FUNCTION
  343.     This function orphans all child processes of this process and frees
  344.         the memory used to keep track of the children.
  345.  
  346.    INPUTS
  347.  
  348.    RESULT
  349.  
  350.    NOTES
  351.  
  352.    SEE ALSO
  353.     ChildStatus(), CreateFamily(), EmptyMorgue(), LaunchChildl(),
  354.     LaunchChildv(), OrphanChild(), WaitChild().
  355.  
  356.    BUGS
  357.     None Known.
  358.  
  359.  
  360. rsbx.lib/pclose()                                             rsbx.lib/pclose()
  361.  
  362.    NAME
  363.     pclose -- Closes pipe opened by popenl() or by popenv().
  364.  
  365.    SYNOPSIS
  366.     status = pclose(pipe)
  367.  
  368.     int pclose(FILE *);
  369.  
  370.    FUNCTION
  371.     Waits for the command associated with the pipe to exit, closes the
  372.         stream, and returns the return code from the command.
  373.  
  374.    INPUTS
  375.     pipe          - Stream pointer returned by a call to popenl() or to
  376.                     popenv().
  377.  
  378.    RESULT
  379.     status        - The return code from the command executed, or -1 if
  380.                     pipe wasn't opened by popenl() or by popenv().
  381.  
  382.    NOTES
  383.  
  384.    SEE ALSO
  385.     popenl(), popenv().
  386.  
  387.    BUGS
  388.     None known.
  389.  
  390.  
  391. rsbx.lib/popenl()                                             rsbx.lib/popenl()
  392.  
  393.    NAME
  394.     popenl -- Initiate I/O to or from a command.
  395.  
  396.    SYNOPSIS
  397.     pipe = popenl(arg0, ..., argn, NULL, mode)
  398.  
  399.     FILE *popenl(char *, char *, ...);
  400.  
  401.    FUNCTION
  402.     Creates a stream between the calling process and the stdin or stdout
  403.         streams of the command it executes. Mode should be "r" to read
  404.         the stdout stream of the command, or "w" to write to the stdin
  405.         stream of the command. 
  406.  
  407.    INPUTS
  408.     arg0          - Name of file to execute.
  409.        ...           - Other command line arguments needed by the file to be
  410.                     executed.
  411.     NULL          - Zero.
  412.     mode          _ I/O mode string.
  413.  
  414.    RESULT
  415.     pipe          - File pointer to use to read or write to the command
  416.                     with.
  417.  
  418.    NOTES
  419.     A stream opened by popenl() should be closed by pclose().
  420.  
  421.    SEE ALSO
  422.     popenv(), pclose().
  423.  
  424.    BUGS
  425.     This function does not create a complete CLI enviroment for the child
  426.         process. Use of this function with a command that expects a BCPL
  427.         environment will crash the system. The Unix function 'popen' takes
  428.         as arguments a command string which it passes to the shell, and a
  429.         mode string.
  430.  
  431.  
  432. rsbx.lib/popenv()                                             rsbx.lib/popenv()
  433.  
  434.    NAME
  435.     popenv -- Initiate I/O to or from a command.
  436.  
  437.    SYNOPSIS
  438.     pipe = popenv(argv, mode)
  439.  
  440.     FILE *popenv(char **, char *);
  441.  
  442.    FUNCTION
  443.     Creates a stream between the calling process and the stdin or stdout
  444.         streams of the command it executes. Mode should be "r" to read
  445.         the stdout stream of the command, or "w" to write to the stdin
  446.         stream of the command. 
  447.  
  448.    INPUTS
  449.     argv          - An array of pointer to the argument strings for the
  450.                     command. The last pointer must be followed by a 0
  451.                     pointer. The first pointer, argv[0], is the name of
  452.                     file to execute.
  453.     mode          _ I/O mode string.
  454.  
  455.    RESULT
  456.     pipe          - File pointer to use to read or write to the command
  457.                     with.
  458.  
  459.    NOTES
  460.     A stream opened by popenv() should be closed by pclose().
  461.  
  462.    SEE ALSO
  463.     popenl(), pclose().
  464.  
  465.    BUGS
  466.     This function does not create a complete CLI enviroment for the child
  467.         process. Use of this function with a command that expects a BCPL
  468.         environment will crash the system. The Unix function 'popen' takes
  469.         as arguments a command string which it passes to the shell, and a
  470.         mode string.
  471.  
  472.  
  473. rsbx.lib/WaitChild()                                       rsbx.lib/WaitChild()
  474.  
  475.    NAME
  476.     WaitChild -- Wait for child process to terminate.
  477.  
  478.    SYNOPSIS
  479.     term = WaitChild(child, status)
  480.  
  481.     struct ChildNode *WaitChild(struct ChildNode *, long * );
  482.  
  483.    FUNCTION
  484.     This function waits for a child process to terminate, and places the
  485.         child's return val in the long pointed to by status. If the child
  486.         identifier provided doen't belong to a child of this process, then
  487.         0 is returned. If the child identifier is zero, returns the child
  488.         identifier of a child that has terminated and sets the long status
  489.         points to to its return val. If the child identifier is zero and
  490.         no child has yet terminated, wait for any child to terminate and
  491.         return its identifier and set the long status points to to its
  492.         return val. If the child identifier is zero and there are no child
  493.         processes of this process, return zero.
  494.  
  495.    INPUTS
  496.     child         - Child identifier as returned by LaunchChildl() or by
  497.                     LaunchChildv().
  498.     status        - Pointer to a long to store the return val of the child
  499.                     in.
  500.  
  501.    RESULT
  502.     term          - Child identifier of the child process whos return val
  503.                     was stored in the long pointed to by status, or zero
  504.                     if there was an error.
  505.  
  506.    NOTES
  507.  
  508.    SEE ALSO
  509.     ChildStatus(), CreateFamily(), EmptyMorgue(), LaunchChildl(),
  510.     LaunchChildv(), OrphanChild(), OrphanChildren().
  511.  
  512.    BUGS
  513.     None Known.
  514.  
  515.  
  516.