home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 May / Pcwk5b98.iso / WEBSERVE / PI3 / PI3WEB.EXE / DEVEL / INCLUDE / PIPlat.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-10-26  |  21.9 KB  |  716 lines
  1. /*____________________________________________________________________________*\
  2.  *
  3.  
  4.  Copyright (c) 1997 John Roy. All rights reserved.
  5.  
  6.  These sources, libraries and applications are
  7.  FREE FOR COMMERCIAL AND NON-COMMERCIAL USE
  8.  as long as the following conditions are adhered to.
  9.  
  10.  Redistribution and use in source and binary forms, with or without
  11.  modification, are permitted provided that the following conditions
  12.  are met:
  13.  
  14.  1. Redistributions of source code must retain the above copyright
  15.     notice, this list of conditions and the following disclaimer. 
  16.  
  17.  2. Redistributions in binary form must reproduce the above copyright
  18.     notice, this list of conditions and the following disclaimer in
  19.     the documentation and/or other materials provided with the
  20.     distribution.
  21.  
  22.  3. Redistributions of any form whatsoever and all advertising materials 
  23.     mentioning features must contain the following
  24.     acknowledgment:
  25.     "This product includes software developed by John Roy
  26.     (http://www.johnroy.com/pi3/)."
  27.  
  28.  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  29.  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30.  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  31.  IN NO EVENT SHALL THE AUTHORS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
  32.  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  33.  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34.  GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35.  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  36.  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  37.  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  38.  OF THE POSSIBILITY OF SUCH DAMAGE.
  39.  
  40.  *____________________________________________________________________________*|
  41.  *
  42.  * $Source: PIPlat.h$
  43.  * $Date: Sun Aug 10 06:29:37 1997$
  44.  *
  45.  Description:
  46.     Definition of platform specific functions.
  47. \*____________________________________________________________________________*/
  48. /* $HeaderTop:$ */
  49.  
  50. #ifndef PIPLAT_H_
  51. #define PIPLAT_H_
  52.  
  53. #include "PiAPI.h"
  54. #include "PISync.h"
  55. #include "PIThread.h"
  56.  
  57. /*____________________________________________________________________________*\
  58.  *
  59.  Typedefs:
  60. \*____________________________________________________________________________*/
  61. typedef void (* PIPlatformFn)(void);
  62. #define PIPLATFORM_VERSION_1_0        100
  63.  
  64. #define PIPLATFORM_POLL_READ        0x1    
  65. #define PIPLATFORM_POLL_WRITE        0x2
  66. #define PIPLATFORM_POLL_NOTIMEOUT    (-1)
  67. #define PIPLATFORM_POLL_NOWAIT        (0)
  68.  
  69. #define PIPLATFORM_FD                int        /* a regular file descriptor */
  70. #define PIPLATFORM_NETFD            int        /* a network file descriptor */
  71. #define PIPLATFORM_FD_INVALID        ((PIPLATFORM_FD)-1)
  72.  
  73. #define PIPLATFORM_TIME                int        /* should be time_t */
  74.  
  75.  
  76. /*____________________________________________________________________________*\
  77.  *
  78.  Name:
  79.     PIPlatform_enter
  80.  
  81.  Synopsis:
  82.     int PIPlatform_enter( const char *pArgv0, int iVersion, PIPlatformFn fn )
  83.     
  84.  Description:
  85.     Initializes the platform facilities including user context threads
  86.     and custom memory management, then calls the user supplied function
  87.     fn. PIPlatform_enter() cleans platform facilities before returning.
  88.  
  89.  Notes:
  90.     The parameter pArgv0 should be passed argv[0] from the main() entry
  91.     point to the program, as certain implementations of dynamic loading
  92.     require this. However this is not essential to the functioning of
  93.     most platform functionality and NULL may be passed instead.
  94.     The constant PLATFORM_VERSION_1_0 should be used as parameter iVersion
  95.     to this function. 
  96.     A typical use of this function is to invoke it immediately on entering
  97.     main() or equivalent function.
  98.     The function fn is run in the main thread with initial priority    
  99.     PITHREAD_PRIORIY_MED.
  100.     
  101. <!--
  102. */
  103. #if 0
  104. --><PRE>
  105.     /* --- globals --- */
  106.     int iArgc;
  107.     char **ppArgv;
  108.     int iRet;
  109.     
  110.     /* --- Main program function --- */
  111.     void foo()
  112.     {
  113.  
  114.         /* ... */
  115.  
  116.         iRet = 0;
  117.     }
  118.  
  119.     /* --- initialize the platform and invoke foo() --- */
  120.     int main( int iArgc, char *ppArgv[] )
  121.     {
  122.     iArgc = iTheArgc;
  123.     ppArgv = ppTheArgv;
  124.     if ( PIPlatform_enter( ppArgv[0], PLATFORM_VERSION_1_0, foo ) )
  125.         {
  126.         printf( "Error initializing platform\n" );
  127.         return 0;
  128.         };
  129.     return iRet;
  130.     }
  131. </PRE>
  132. <!--
  133. #endif 
  134. /*
  135. -->
  136.     
  137.  Return Values:
  138.     PIPlatform_enter() returns zero (PIAPI_COMPLETED) on success.
  139.  
  140.  Errors:
  141.     On error PIPlatform_enter() returns a negative value.
  142.  
  143.     More error information can be retrieved using PIPlatform_getLastError().
  144.  
  145.  See Also:
  146.     PIPlatform_getDescription().
  147. \*____________________________________________________________________________*/
  148. PUBLIC_PIAPI int PIPlatform_enter( const char *pArgv0, int iVersion,
  149.     PIPlatformFn fn );
  150.  
  151. /*____________________________________________________________________________*\
  152.  *
  153.  Name:
  154.     PIPlatform_getDescription
  155.  
  156.  Synopsis:
  157.     const char *PIPlatform_getDescription()
  158.     
  159.  Description:
  160.     Returns a string which describes the range of operating systems
  161.     and machine/processor sets for which this build is compatible.
  162.  
  163.  Notes:
  164.     The description is of the form 
  165.         
  166.         Operating system ( machine processor )
  167.  
  168.  Return Values:
  169.     Returns an internally allocated pointer to a string. The caller should
  170.     not modify this string.
  171.  
  172.  Errors:
  173.     PIPlatform_getDescription returns NULL if PIPlatform_Init() has not
  174.     been called.
  175.  
  176.     More error information can be retrieved using PIPlatform_getLastError().
  177.  
  178.  See Also:
  179.     PIPlatform_enter().
  180. \*____________________________________________________________________________*/
  181. PUBLIC_PIAPI const char *PIPlatform_getDescription();
  182.  
  183. /*____________________________________________________________________________*\
  184.  *
  185.  Name:
  186.     PIPlatform_allocLocalMutex
  187.  
  188.  Synopsis:
  189.     PISync *PIPlatform_allocLocalMutex()
  190.     
  191.  Description:
  192.     Returns a new local mutex which can be used to synchronize threads of
  193.     control within a process.
  194.  
  195.  Notes:
  196.     The synchronization object should be destroyed using PISync_delete() when
  197.     it is no longer needed.
  198.  
  199.  Return Values:
  200.     Returns a pointer to a new synchronization object or NULL on error.
  201.  
  202.  Errors:
  203.     NULL may be returned if a new syncronization object could not be
  204.     created due to exhausted memory, kernel mutexes or user mutexes.
  205.  
  206.     More information can be retrieved using PIPlatform_getLastError().
  207.  
  208.  See Also:
  209.     PISync_lock(), PISync_unlock(), PISync_tryLock(), PISync_delete().
  210. \*____________________________________________________________________________*/
  211. PUBLIC_PIAPI PISync *PIPlatform_allocLocalMutex();
  212.  
  213. /*____________________________________________________________________________*\
  214.  *
  215.  Name:
  216.     PIPlatform_allocLocalSemaphore
  217.  
  218.  Synopsis:
  219.     PISync *PIPlatform_allocLocalSemaphore( int iInitalCount, int iMaxCount )
  220.     
  221.  Description:
  222.     Returns a new local semaphore which can be used to synchronize 
  223.     threads of control within a process.
  224.  
  225.  Notes:
  226.     The synchronization object should be destroyed using PISync_delete() when
  227.     it is no longer needed.
  228.  
  229.  Return Values:
  230.     Returns a pointer to a new synchronization object or NULL on error.
  231.  
  232.  Errors:
  233.     NULL may be returned if a new syncronization object could not be
  234.     created due to exhausted memory, kernel semaphores or user semaphores.
  235.  
  236.     More specific error information can be retrieved using 
  237.     PIPlatform_getLastError().
  238.  
  239.  See Also:
  240.     PISync_lock(), PISync_unlock(), PISync_tryLock(), PISync_delete().
  241. \*____________________________________________________________________________*/
  242. PUBLIC_PIAPI PISync *PIPlatform_allocLocalSemaphore( int iInitialCount,
  243.     int iMaxCount );
  244.  
  245. /*____________________________________________________________________________*\
  246.  *
  247.  Name:
  248.     PIPlatform_pollNetFD
  249.  
  250.  Synopsis:
  251.     int PIPlatform_pollNetFD( PIPLATFORM_NETFD fdSocket, int iFlags,
  252.         int iTimeout )
  253.     
  254.  Description:
  255.     Waits for the activity on the specified network file descriptor
  256.     (socket). The value iFlags is formed by OR'ing together any 
  257.     combination of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE.
  258.     The value piTimeout is a pointer to an integer containing a time to
  259.     wait in seconds.
  260.  
  261.  Notes:
  262.     A value of PIPLATFORM_NOTIMEOUT for iTimeout specifies no timeout.
  263.     A value of PIPLATFORM_NOWAIT for iTimeout specifies that
  264.     PIPlatform_pollNetFD() should test for activity on fdSocket but return
  265.     immediately even if there is none.
  266.  
  267.  Return Values:
  268.     On success PIPlatform_pollNetFD() returns a value formed by OR'ing
  269.     some of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE together
  270.     indicating which operations may be performed on socket fdSocket
  271.     without blocking.
  272.     If the specified timeout period expires, PIPlatform_pollNetFD() returns
  273.     a value of zero.
  274.  
  275.  Errors:
  276.     On failure PIPlatform_pollNetFD() returns a negative value.
  277.  
  278.     More specific error information can be retreived using 
  279.     PIPlatform_getLastError().
  280.  
  281.  See Also:
  282.     PIPlatform_pollFD(), PIPlatform_pollPipeFD(), PIPlatform_sleep().
  283. \*____________________________________________________________________________*/
  284. PUBLIC_PIAPI int PIPlatform_pollNetFD( PIPLATFORM_NETFD fdSocket, int iFlags,
  285.     int iTimeout );
  286.  
  287. /*____________________________________________________________________________*\
  288.  *
  289.  Name:
  290.     PIPlatform_pollPipeFD
  291.  
  292.  Synopsis:
  293.     int PIPlatform_pollPipeFD( PIPLATFORM_FD fd, int iFlags,
  294.         int iTimeout )
  295.     
  296.  Description:
  297.     Waits for activity on the specified pipe.
  298.     The value iFlags is formed by OR'ing together any 
  299.     combination of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE.
  300.     The value piTimeout is a pointer to an integer containing a time to
  301.     wait in seconds.
  302.  
  303.  Notes:
  304.     A value of PIPLATFORM_NOTIMEOUT for iTimeout specifies no timeout.
  305.     A value of PIPLATFORM_NOWAIT for iTimeout specifies that
  306.     PIPlatform_pollNetFD() should test for activity on fd but return
  307.     immediately even if there is none.
  308.  
  309.     On systems where differences between pipes and file descriptors
  310.     are transparent, PIPlatform_pollPipeFD() is implemented using
  311.     PIPlatform_pollFD(). On other systems PIPlatform_pollPipeFD() may not
  312.     be implemented, see below under 'Errors'.
  313.  
  314.  Return Values:
  315.     On success PIPlatform_pollPipeFD() returns a value formed by OR'ing
  316.     some of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE
  317.     together indicating which operations may be performed on
  318.     pipe fd without blocking.
  319.     If the specified timeout period expires, PIPlatform_pollPipeFD()
  320.     returns a value of zero.
  321.  
  322.  Errors:
  323.     On failure PIPlatform_pollNetFD() returns a negative value.
  324.  
  325.     More specific error information can be retreived using 
  326.     PIPlatform_getLastError().
  327.  
  328.     On some systems PIPlatform_pollPipeFD() is not yet implemented, in this
  329.     case a value of PIAPI_ERROR will be returned and
  330.     PIPlatform_getLastError() will return a value of PIAPI_NOTSUPPORTED.
  331.  
  332.  See Also:
  333.     PIPlatform_pollPipeFD(), IPlatform_pollNetFD(), PIPlatform_sleep().
  334. \*____________________________________________________________________________*/
  335. PUBLIC_PIAPI int PIPlatform_pollPipeFD( PIPLATFORM_FD fd, int iFlags,
  336.     int iTimeout );
  337.  
  338. /*____________________________________________________________________________*\
  339.  *
  340.  Name:
  341.     PIPlatform_pollFD
  342.  
  343.  Synopsis:
  344.     int PIPlatform_pollFD( PIPLATFORM_FD fd, int iFlags,
  345.         int iTimeout )
  346.     
  347.  Description:
  348.     Waits for the activity on the specified file descriptor.
  349.     The value iFlags is formed by OR'ing together any 
  350.     combination of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE.
  351.     The value piTimeout is a pointer to an integer containing a time to
  352.     wait in seconds.
  353.  
  354.  Notes:
  355.     A value of PIPLATFORM_NOTIMEOUT for iTimeout specifies no timeout.
  356.     A value of PIPLATFORM_NOWAIT for iTimeout specifies that
  357.     PIPlatform_pollNetFD() should test for activity on fd but return
  358.     immediately even if there is none.
  359.  
  360.     On systems where differences between sockets and file descriptors
  361.     are transparent, PIPlatform_pollFD() is implemented using
  362.     PIPlatform_pollNetFD(). On other systems PIPlatform_pollFD() may not
  363.     be implemented, see below under 'Errors'.
  364.  
  365.  Return Values:
  366.     On success PIPlatform_pollFD() returns a value formed by OR'ing
  367.     some of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE together
  368.     indicating which operations may be performed on file description fd
  369.     without blocking.
  370.     If the specified timeout period expires, PIPlatform_pollFD() returns
  371.     a value of zero.
  372.  
  373.  Errors:
  374.     On failure PIPlatform_pollNetFD() returns a negative value.
  375.  
  376.     More specific error information can be retreived using 
  377.     PIPlatform_getLastError().
  378.  
  379.     On some systems PIPlatform_pollFD() is not yet implemented, in this
  380.     case a value of PIAPI_ERROR will be returned and PIPlatform_getLastError()
  381.     will return a value of PIAPI_NOTSUPPORTED.
  382.  
  383.  See Also:
  384.     PIPlatform_pollNetFD(), PIPlatform_pollPipeFD(), PIPlatform_sleep().
  385. \*____________________________________________________________________________*/
  386. PUBLIC_PIAPI int PIPlatform_pollFD( PIPLATFORM_FD fd, int iFlags,
  387.     int iTimeout );
  388.  
  389. /*____________________________________________________________________________*\
  390.  *
  391.  Name:
  392.     PIPlatform_sleep
  393.  
  394.  Synopsis:
  395.     int PIPlatform_sleep( int iMilliseconds )
  396.     
  397.  Description:
  398.     Causes the current thread to sleep for at least iMilliseconds
  399.     thousandths of a second. The current thread may sleep for longer
  400.     than the specified time period. This is particularly true where
  401.     user context threads are in use.
  402.  
  403.  Notes:
  404.     If user context threads are being used and no other threads are
  405.     runnable PIPlatform_sleep() will cause the process to enter a 
  406.     'tight loop'. This may be expensive on CPU utilization with some
  407.     programs.
  408.  
  409.  Return Values:
  410.     On success PIPlatform_sleep() returns a value of 0. 
  411.  
  412.  Errors:
  413.     On failure PIPlatform_sleep() returns a negative value.
  414.     
  415.     PIPlatform_getLastError() returns more specific error information.
  416.  
  417.  See Also:
  418.     PIPlatform_pollNetFD(), PIPlatform_pollFD().
  419. \*____________________________________________________________________________*/
  420. PUBLIC_PIAPI int PIPlatform_sleep( int iMilliseconds );
  421.  
  422. /*____________________________________________________________________________*\
  423.  *
  424.  Name:
  425.     PIPlatform_getLastError
  426.  
  427.  Synopsis:
  428.     int PIPlatform_getLastError()
  429.     
  430.  Description:
  431.     Returns the last error code for the current thread.
  432.  
  433.  Notes:
  434.     Error codes are only set on error. Except where noted they are
  435.     not cleared on success.
  436.  
  437.  Return Values:
  438.     PIPlatform_getLastError() always returns the last error code.
  439.  
  440.  Errors:
  441.     This function does not generate an error.
  442.  
  443.  See Also:
  444.     PIPlatform_setLastError(), Errors.
  445. \*____________________________________________________________________________*/
  446. PUBLIC_PIAPI int PIPlatform_getLastError();
  447.  
  448. /*____________________________________________________________________________*\
  449.  *
  450.  Name:
  451.     PIPlatform_setLastError
  452.  
  453.  Synopsis:
  454.     void PIPlatform_setLastError( int iErrorCode )
  455.     
  456.  Description:
  457.     Set the error code for this thread. Subsequent calls to 
  458.     PIPlatform_getLastError() will return this error code.
  459.  
  460.  Notes:
  461.  
  462.  Return Values:
  463.     PIPlatform_setLastError() does not return a value.
  464.  
  465.  Errors:
  466.     This function does not generate an error.
  467.  
  468.  See Also:
  469.     PIPlatform_getLastError(), Errors
  470. \*____________________________________________________________________________*/
  471. PUBLIC_PIAPI void PIPlatform_setLastError( int iErrorCode );
  472.  
  473. /*____________________________________________________________________________*\
  474.  *
  475.  Name:
  476.     PIPlatform_catchExceptions
  477.  
  478.  Synopsis:
  479.     void PIPlatform_catchExceptions( void (*)(void *), void * )
  480.     
  481.  Description:
  482.     Not yet documented.
  483.  
  484.  Notes:
  485.  Return Values:
  486.  Errors:
  487.  See Also:
  488. \*____________________________________________________________________________*/
  489. PUBLIC_PIAPI void PIPlatform_catchExceptions(
  490.     void (*)(void *), void * );
  491.  
  492. /*____________________________________________________________________________*\
  493.  *
  494.  Name:
  495.     PIPlatform_beforeUnsafeBlock
  496.  
  497.  Synopsis:
  498.     int PIPlatform_beforeUnsafeBlock()
  499.     
  500.  Description:
  501.     Protects reentrance into non-thread safe blocks by blocking on a 
  502.     semaphore.
  503.  
  504.  Notes:
  505.     Calls to PIPlatform_beforeUnsafeBlock() must be matched by calls to
  506.     PIPlatform_afterUnsafeBlock().
  507.  
  508.  Return Values:
  509.     Returns 0 on success.
  510.     
  511.  Errors:
  512.     On error a non-zero value is returned, the function
  513.     PIPlatform_getLastError() can be used to get more specific error
  514.     information.
  515.  
  516.  See Also:
  517.     PIPlatform_afterUnsafeBlock
  518. \*____________________________________________________________________________*/
  519. PUBLIC_PIAPI int PIPlatform_beforeUnsafeBlock();
  520.  
  521. /*____________________________________________________________________________*\
  522.  *
  523.  Name:
  524.     PIPlatform_afterUnsafeBlock
  525.  
  526.  Synopsis:
  527.     int PIPlatform_afterUnsafeBlock()
  528.     
  529.  Description:
  530.     Ends a block protected by reentrance with PIPlatform_beforeUnsafeBlock().
  531.  
  532.  Notes:
  533.  Return Values:
  534.     Returns 0 on success.
  535.  
  536.  Errors:
  537.     On error a non-zero value is returned, the function
  538.     PIPlatform_getLastError() can be used to get more specific error
  539.     information.
  540.  
  541.  See Also:
  542.     PIPlatform_beforeUnsafeBlock
  543. \*____________________________________________________________________________*/
  544. PUBLIC_PIAPI int PIPlatform_afterUnsafeBlock();
  545.  
  546. /*____________________________________________________________________________*\
  547.  *
  548.  Name:
  549.     PIPlatform_getCurrentDirectory
  550.  
  551.  Synopsis:
  552.     int PIPlatform_getCurrentDirectory( char *pBuffer, int iMaxLen )
  553.     
  554.  Description:
  555.     Retrieve the current directory for the process and write it
  556.     into the buffer pBuffer up to iMaxLen characters.
  557.  
  558.     The buffer pBuffer may not be null terminated if the length
  559.     of the current directory is greater than or equal to iMaxLen.
  560.     
  561.  Notes:
  562.  Return Values:
  563.     Returns the length of the current directory. Although no more
  564.     than iMaxLen characters will be written into pBuffer, 
  565.     PIPlatform_getCurrentDirectory() may return a length greater
  566.     than iMaxLen.
  567.       
  568.  
  569.  Errors:
  570.     On error PIPlatform_getCurrentDirectory() returns 0.
  571.     PIPlatform_getLastError() can be used to get more specific error
  572.     information.
  573.  
  574.  See Also:
  575. \*____________________________________________________________________________*/
  576. PUBLIC_PIAPI int PIPlatform_getCurrentDirectory( char *pBuffer, int iMaxLen );
  577.  
  578. /*____________________________________________________________________________*\
  579.  *
  580.  Name:
  581.     PIPlatform_getProcess
  582.  
  583.  Synopsis:
  584.     int PIPlatform_getProcess()
  585.     
  586.  Description:
  587.     Retrieve the platform specific identifier or handle for the current
  588.     process.
  589.     
  590.  Notes:
  591.  Return Values:
  592.     Idenifier or handle of Current process.
  593.       
  594.  Errors:
  595.     PIPlatform_getProcess() does not generate errors.
  596.  
  597.  See Also:
  598.     PIPlatform_getProcessId().
  599. \*____________________________________________________________________________*/
  600. PUBLIC_PIAPI int PIPlatform_getProcess();
  601.  
  602. /*____________________________________________________________________________*\
  603.  *
  604.  Name:
  605.     PIPlatform_getProcessId
  606.  
  607.  Synopsis:
  608.     int PIPlatform_getProcessId()
  609.     
  610.  Description:
  611.     Retrieve the platform specific identifier for the current
  612.     process.
  613.     
  614.  Notes:
  615.     PIPlatform_getProcessId() differs from PIPlatform_getProcess() in that
  616.     PIPlatform_getProcessId() always returns an integer process index that
  617.     can be used to reference a specific process across all processes. 
  618.     PIPlatform_getProcess() returns the native reference to a process and
  619.     may only be valid within the process space of the current process.
  620.  
  621.  Return Values:
  622.     Identifier for the Current process.
  623.       
  624.  Errors:
  625.     PIPlatform_getProcessId() does not generate errors.
  626.  
  627.  See Also:
  628.     PIPlatform_getProcess().
  629. \*____________________________________________________________________________*/
  630. PUBLIC_PIAPI int PIPlatform_getProcessId();
  631.  
  632. /*____________________________________________________________________________*\
  633.  *
  634.  Name:
  635.     PIPlatform_waitForProcess
  636.  
  637.  Synopsis:
  638.     int PIPlatform_waitForProcess( int tProcess, int iFlags, int
  639.         iTimeout )
  640.     
  641.  Description:
  642.     Cause the current thread to sleep until the process specified by the
  643.     operating system specific identifier or handle (tProcess) has 
  644.     terminated. iFlags is reserved for future use and should always be 0.
  645.     iTimeout specifies the maximum time to wait, measured in seconds.
  646.     
  647.  Notes:
  648.     The parameter iFlags must be passed the value 0.
  649.  
  650.  Return Values:
  651.     Returns PIAPI_COMPLETED on success, PIAPI_TIMEOUT on timeout,
  652.     otherwise PIAPI_ERROR.
  653.       
  654.  Errors:
  655.     On error PIAPI_ERROR is returned. The function PIPlatform_getLastError()
  656.     can be used to retreive more specific error information.
  657.  
  658.  See Also:
  659. \*____________________________________________________________________________*/
  660. PUBLIC_PIAPI int PIPlatform_waitForProcess( int tProcess, int iFlags,
  661.     int iTimeout );
  662.  
  663. /*____________________________________________________________________________*\
  664.  *
  665.  Name:
  666.     PIPlatform_advisaryLockFd
  667.  
  668.  Synopsis:
  669.     PIPlatform_advisaryLockFd( PIPLATFORM_FD tFD )
  670.  
  671.  Description:
  672.     Place an advisary lock on a file descriptor, blocking until the
  673.     the lock can be obtained. The blocking is performed in an
  674.     efficient manner for the process and thread model beng used.
  675.     
  676.  Notes:
  677.  Return Values:
  678.     On success PIPlatform_advisaryLockFd() returns zero (PIAPI_COMPLETED).
  679.  
  680.  Errors:
  681.     On error, the function PIPlatform_getLastError() can be used to get 
  682.     more specific error information.
  683.         
  684.  See Also:
  685.     PIPlatform_advisaryUnlockFd()
  686. \*____________________________________________________________________________*/
  687. PUBLIC_PIAPI int PIPlatform_advisaryLockFd( PIPLATFORM_FD tFD );
  688.  
  689. /*____________________________________________________________________________*\
  690.  *
  691.  Name:
  692.     PIPlatform_advisaryUnlockFd
  693.  
  694.  Synopsis:
  695.     PIPlatform_advisaryUnlockFd( PIPLATFORM_FD tFD )
  696.  
  697.  Description:
  698.     Release an advisary lock from a file descriptor, previously placed
  699.     with PIPlatform_advisaryLockFd().
  700.     
  701.  Notes:
  702.  Return Values:
  703.     On success PIPlatform_advisaryUnlockFd() returns zero (PIAPI_COMPLETED).
  704.  
  705.  Errors:
  706.     On error, the function PIPlatform_getLastError() can be used to get 
  707.     more specific error information.
  708.         
  709.  See Also:
  710.     PIPlatform_advisaryLockFd()
  711. \*____________________________________________________________________________*/
  712. PUBLIC_PIAPI int PIPlatform_advisaryUnlockFd( PIPLATFORM_FD tFD );
  713.  
  714. #endif    /* PIPLAT_H_ */
  715.  
  716.