/*
Copyright (c) 1993 Xerox Corporation.  All rights reserved.
*/
/*
$Id$

$Date$
 *
 */
/* Chauser, October 28, 1993 3:33 pm PDT */

#ifndef __PCR_Base_h
#   define __PCR_Base_h 1

#include <config/PCR_StdTypes.h>
#include <base/PCR_BaseArgs.h>

#include <stdarg.h>

/*
 * Startup
 */

extern /* readonly */ PCR_BaseArgs_Templates
PCR_Base_startArgsTemplates;

extern /* readonly */ const char *
PCR_Base_cmdName;

extern /* readonly */ int
PCR_Base_startNArgs;

extern /* readonly */ const char **
PCR_Base_startArgs;


extern PCR_ERes
PCR_Base_Start(
    const char * cmdName,
    int nArgs,
    const char ** args,
    PCR_ProcPtr proc,
    PCR_Any data,
    char *msgBuf, int msgBufLen
);
/*
    Startup.
    The cmdName is used as a source of symbol information
      to initialize dynamic loading.  It may be NIL, in which case
      dynamic loading is disabled (unless proc enables it
      using the PCR_IL.h interface).
    The args are used to configure PCR itself..
    N.B. args[0] is *not* the command name.
    If arg parsing fails, or the startup fails for any other reason,
      return an error with an appropriate message stored in msgBuf.
    Otherwise, (*proc)(data) is invoked in an initial thread.
    If (*proc)(data) returns, the equivalent of PCR_Base_Exit(0)
      occurs.
    This call never returns successfully.
*/

/*
 * System message printing
 *
 * These may be called at any time, though it is not recommended
 *   that they be used from threads for performance reasons.
 *
 * They are the *only* way to print before PCR_Base_Start has been called. 
 *
 * The only format specifications allowed are
 *   %c %s %d %o %x
 */

extern int
PCR_Base_vsprintf(char *s, const char *fmt, va_list ap);

extern int
PCR_Base_sprintf(char *s, const char *fmt, ...);

extern int
PCR_Base_vprintf(const char *fmt, va_list ap);

extern int
PCR_Base_printf(const char *fmt, ...);

extern int
PCR_Base_Msg(const char *fmt, ...);

/*
 * Shutdown
 */

extern void
PCR_Base_AtExit(
    PCR_ProcPtr proc,
    PCR_Any data
);
/*
   Registered AtExit procs are called by PCR_Base_Exit(...).
   ??? Is it okay to call AtExit before calling Start ???
*/

extern void
PCR_Base_Exit(int status);

/*
 * Finding a full path name for an executable file 
 */

typedef PCR_ERes PCR_Base_AccessProc(const char *path, PCR_Any data);

extern PCR_ERes
PCR_Base_FindFileUsingSearchRules(
    const char *cmdName,
    const char *cwd,
    char *buf,
    int buflen,
    PCR_Base_AccessProc access,
    PCR_Any accessData
);

/* 
 * PCR_Base_FindFileUsingSearchRues uses the OS-specific search rules
 * to try to find the full path name of a file with cmdName as its name.
 * The caller must supply the current working directory, and buf
 * into which the answer is stored (if it fits).  The access procedure
 * should return PCR_ERes_okay if the path name given to it is 
 * acceptable to the client.
 * Return values:
 *    PCR_ERes_okay  -- buf contains a path name accepted by accept
 *    EINVAL         -- relative cmdName and null cwd
 *    EINVAL         -- null buf or 0 buflen
 *    ERANGE         -- some enumerated full path wouldn't fit in buf
 */

/*
 * System panic messages.
 *
 * Avoid these except for catastrophic failures!
 */

typedef void PCR_Base_PanicFunc(const char *fmt, ...);

extern PCR_Base_PanicFunc *
PCR_Base__Panic(const char *file, int line);

extern void
PCR_Base_Panic(const char *fmt, ...);
#define PCR_Base_Panic \
	(*(PCR_Base__Panic(__FILE__, __LINE__)))

extern void
PCR_Base__NYI(const char *file, int line, PCR_Bool fatal);

extern void
PCR_Base_NYI(PCR_Bool fatal);
#define PCR_Base_NYI(fatal) \
	PCR_Base__NYI(__FILE__, __LINE__,(fatal))


#endif /* !__PCR_Base_h */
/*
$Log$
*/