#include "sal/config.h"
#include "osl/file.h"
#include "osl/security.h"
#include "osl/time.h"
#include "rtl/locale.h"
#include "rtl/ustring.h"
#include "sal/saldllapi.h"

Classes
struct	oslProcessInfo

Macros
#define	osl_Process_WAIT 0x0001 /* wait for completion */

#define	osl_Process_SEARCHPATH 0x0002 /* search path for executable */

#define	osl_Process_DETACHED 0x0004 /* run detached */

#define	osl_Process_NORMAL 0x0000 /* run in normal window */

#define	osl_Process_HIDDEN 0x0010 /* run hidden */

#define	osl_Process_MINIMIZED 0x0020 /* run in minimized window */

#define	osl_Process_MAXIMIZED 0x0040 /* run in maximized window */

#define	osl_Process_FULLSCREEN 0x0080 /* run in fullscreen window */

#define	osl_Process_IDENTIFIER 0x0001 /* retrieves the process identifier */

#define	osl_Process_EXITCODE 0x0002 /* retrieves exit code of the process */

#define	osl_Process_CPUTIMES 0x0004 /* retrieves used cpu time */

#define	osl_Process_HEAPUSAGE 0x0008 /* retrieves the used size of heap */

Typedefs
typedef sal_Int32	oslProcessOption

typedef sal_Int32	oslProcessData

typedef sal_uInt32	oslProcessIdentifier

typedef sal_uInt32	oslProcessExitCode

typedef void *	oslProcess
	Process handle. More...

Enumerations
enum	oslProcessError { osl_Process_E_None, osl_Process_E_NotFound, osl_Process_E_TimedOut, osl_Process_E_NoPermission, osl_Process_E_Unknown, osl_Process_E_InvalidError, osl_Process_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM }

Functions
SAL_DLLPUBLIC oslProcessError	osl_executeProcess (rtl_uString ustrImageName, rtl_uString ustrArguments[], sal_uInt32 nArguments, oslProcessOption Options, oslSecurity Security, rtl_uString ustrDirectory, rtl_uString ustrEnvironments[], sal_uInt32 nEnvironmentVars, oslProcess *pProcess)
	Execute a process. More...

SAL_DLLPUBLIC oslProcessError	osl_executeProcess_WithRedirectedIO (rtl_uString strImageName, rtl_uString ustrArguments[], sal_uInt32 nArguments, oslProcessOption Options, oslSecurity Security, rtl_uString ustrDirectory, rtl_uString ustrEnvironments[], sal_uInt32 nEnvironmentVars, oslProcess pProcess, oslFileHandle pChildInputWrite, oslFileHandle pChildOutputRead, oslFileHandle pChildErrorRead)
	Execute a process and redirect child process standard IO. More...

SAL_DLLPUBLIC oslProcessError	osl_terminateProcess (oslProcess Process)
	Terminate a process. More...

SAL_DLLPUBLIC oslProcess	osl_getProcess (oslProcessIdentifier Ident) SAL_COLD

SAL_DLLPUBLIC void	osl_freeProcessHandle (oslProcess Process)
	Free the specified process-handle. More...

SAL_DLLPUBLIC oslProcessError	osl_joinProcess (oslProcess Process)
	Wait for completion of the specified childprocess. More...

SAL_DLLPUBLIC oslProcessError	osl_joinProcessWithTimeout (oslProcess Process, const TimeValue *pTimeout)
	Wait with a timeout for the completion of the specified child process. More...

SAL_DLLPUBLIC oslProcessError	osl_getProcessInfo (oslProcess Process, oslProcessData Fields, oslProcessInfo *pInfo)
	Retrieves information about a Process. More...

SAL_DLLPUBLIC oslProcessError	osl_getExecutableFile (rtl_uString **strFile)
	Get the filename of the executable. More...

SAL_DLLPUBLIC sal_uInt32	osl_getCommandArgCount (void)

SAL_DLLPUBLIC oslProcessError	osl_getCommandArg (sal_uInt32 nArg, rtl_uString **strCommandArg)
	Get the nArg-th command-line argument passed to the main-function of this process. More...

SAL_DLLPUBLIC void	osl_setCommandArgs (int argc, char **argv)
	Set the command-line arguments as passed to the main-function of this process. More...

SAL_DLLPUBLIC oslProcessError	osl_getEnvironment (rtl_uString strVar, rtl_uString *strValue)
	Get the value of one environment variable. More...

SAL_DLLPUBLIC oslProcessError	osl_setEnvironment (rtl_uString strVar, rtl_uString strValue)
	Set the value of one environment variable. More...

SAL_DLLPUBLIC oslProcessError	osl_clearEnvironment (rtl_uString *strVar)
	Unsets the value of one environment variable. More...

SAL_DLLPUBLIC oslProcessError	osl_getProcessWorkingDir (rtl_uString **pustrWorkingDir)
	Get the working directory of the current process as a file URL. More...

SAL_DLLPUBLIC oslProcessError	osl_getProcessLocale (rtl_Locale **ppLocale)
	Get the locale the process is currently running in. More...

SAL_DLLPUBLIC oslProcessError	osl_setProcessLocale (rtl_Locale *pLocale)
	Change the locale of the process. More...

Macro Definition Documentation

◆ osl_Process_CPUTIMES

#define osl_Process_CPUTIMES 0x0004 /* retrieves used cpu time */

◆ osl_Process_DETACHED

#define osl_Process_DETACHED 0x0004 /* run detached */

◆ osl_Process_EXITCODE

#define osl_Process_EXITCODE 0x0002 /* retrieves exit code of the process */

◆ osl_Process_FULLSCREEN

#define osl_Process_FULLSCREEN 0x0080 /* run in fullscreen window */

◆ osl_Process_HEAPUSAGE

#define osl_Process_HEAPUSAGE 0x0008 /* retrieves the used size of heap */

◆ osl_Process_HIDDEN

#define osl_Process_HIDDEN 0x0010 /* run hidden */

◆ osl_Process_IDENTIFIER

#define osl_Process_IDENTIFIER 0x0001 /* retrieves the process identifier */

◆ osl_Process_MAXIMIZED

#define osl_Process_MAXIMIZED 0x0040 /* run in maximized window */

◆ osl_Process_MINIMIZED

#define osl_Process_MINIMIZED 0x0020 /* run in minimized window */

◆ osl_Process_NORMAL

#define osl_Process_NORMAL 0x0000 /* run in normal window */

◆ osl_Process_SEARCHPATH

#define osl_Process_SEARCHPATH 0x0002 /* search path for executable */

◆ osl_Process_WAIT

#define osl_Process_WAIT 0x0001 /* wait for completion */

Typedef Documentation

◆ oslProcess

typedef void* oslProcess

Process handle.

See also: osl_executeProcess; osl_terminateProcess; osl_freeProcessHandle; osl_getProcessInfo; osl_joinProcess

◆ oslProcessData

typedef sal_Int32 oslProcessData

◆ oslProcessExitCode

typedef sal_uInt32 oslProcessExitCode

◆ oslProcessIdentifier

typedef sal_uInt32 oslProcessIdentifier

◆ oslProcessOption

typedef sal_Int32 oslProcessOption

Enumeration Type Documentation

◆ oslProcessError

enum oslProcessError

Enumerator
osl_Process_E_None
osl_Process_E_NotFound
osl_Process_E_TimedOut
osl_Process_E_NoPermission
osl_Process_E_Unknown
osl_Process_E_InvalidError
osl_Process_E_FORCE_EQUAL_SIZE

Function Documentation

◆ osl_clearEnvironment()

SAL_DLLPUBLIC oslProcessError osl_clearEnvironment ( rtl_uString * strVar )

Unsets the value of one environment variable.

Parameters

[in] strVar denotes the name of the variable to unset.

Since: UDK 3.2.13

◆ osl_executeProcess()

SAL_DLLPUBLIC oslProcessError osl_executeProcess	(	rtl_uString *	ustrImageName,
		rtl_uString *	ustrArguments[],
		sal_uInt32	nArguments,
		oslProcessOption	Options,
		oslSecurity	Security,
		rtl_uString *	ustrDirectory,
		rtl_uString *	ustrEnvironments[],
		sal_uInt32	nEnvironmentVars,
		oslProcess *	pProcess
	)

Execute a process.

Executes the program image provided in strImageName in a new process.

Parameters

[in]	ustrImageName	The file URL of the executable to be started. Can be NULL in this case the file URL of the executable must be the first element in ustrArguments.
[in]	ustrArguments	An array of argument strings. Can be NULL if strImageName is not NULL. If strImageName is NULL it is expected that the first element contains the file URL of the executable to start.
[in]	nArguments	The number of arguments provided. If this number is 0 strArguments will be ignored.
[in]	Options	A combination of int-constants to describe the mode of execution.
[in]	Security	The user and his rights for which the process is started. May be NULL in which case the process will be started in the context of the current user.
[in]	ustrDirectory	The file URL of the working directory of the new process. If the specified directory does not exist or is inaccessible the working directory of the newly created process is undefined. If this parameter is NULL or the caller provides an empty string the new process will have the same current working directory as the calling process.
[in]	ustrEnvironments	An array of strings describing environment variables that should be merged into the environment of the new process. Each string has to be in the form "variable=value". This parameter can be NULL in which case the new process gets the same environment as the parent process.
[in]	nEnvironmentVars	The number of environment variables to set.
[out]	pProcess	Pointer to a oslProcess variable, which receives the handle of the newly created process. This parameter must not be NULL.

Return values

osl_Process_E_None	on success
osl_Process_E_NotFound	if the specified executable could not be found
osl_Process_E_InvalidError	if invalid parameters will be detected
osl_Process_E_Unknown	if arbitrary other errors occur

See also: oslProcessOption; osl_executeProcess_WithRedirectedIO; osl_freeProcessHandle; osl_loginUser

◆ osl_executeProcess_WithRedirectedIO()

SAL_DLLPUBLIC oslProcessError osl_executeProcess_WithRedirectedIO	(	rtl_uString *	strImageName,
		rtl_uString *	ustrArguments[],
		sal_uInt32	nArguments,
		oslProcessOption	Options,
		oslSecurity	Security,
		rtl_uString *	ustrDirectory,
		rtl_uString *	ustrEnvironments[],
		sal_uInt32	nEnvironmentVars,
		oslProcess *	pProcess,
		oslFileHandle *	pChildInputWrite,
		oslFileHandle *	pChildOutputRead,
		oslFileHandle *	pChildErrorRead
	)

Execute a process and redirect child process standard IO.

Parameters

[in]	strImageName	The file URL of the executable to be started. Can be NULL in this case the file URL of the executable must be the first element in ustrArguments.
[in]	ustrArguments	An array of argument strings. Can be NULL if strImageName is not NULL. If strImageName is NULL it is expected that the first element contains the file URL of the executable to start.
[in]	nArguments	The number of arguments provided. If this number is 0 strArguments will be ignored.
[in]	Options	A combination of int-constants to describe the mode of execution.
[in]	Security	The user and his rights for which the process is started. May be NULL in which case the process will be started in the context of the current user.
[in]	ustrDirectory	The file URL of the working directory of the new process. If the specified directory does not exist or is inaccessible the working directory of the newly created process is undefined. If this parameter is NULL or the caller provides an empty string the new process will have the same current working directory as the calling process.
[in]	ustrEnvironments	An array of strings describing environment variables that should be merged into the environment of the new process. Each string has to be in the form "variable=value". This parameter can be NULL in which case the new process gets the same environment as the parent process.
[in]	nEnvironmentVars	The number of environment variables to set.
[out]	pProcess	Pointer to a oslProcess variable, which receives the handle of the newly created process. This parameter must not be NULL.
[out]	pChildInputWrite	Pointer to a oslFileHandle variable that receives the handle which can be used to write to the child process standard input device. The returned handle is not random accessible. The handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
[out]	pChildOutputRead	Pointer to a oslFileHandle variable that receives the handle which can be used to read from the child process standard output device. The returned handle is not random accessible. The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
[out]	pChildErrorRead	Pointer to a oslFileHandle variable that receives the handle which can be used to read from the child process standard error device. The returned handle is not random accessible. The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.

Return values

osl_Process_E_None	on success
osl_Process_E_NotFound	if the specified executable could not be found
osl_Process_E_InvalidError	if invalid parameters will be detected
osl_Process_E_Unknown	if arbitrary other errors occur

See also: oslProcessOption; osl_executeProcess; osl_freeProcessHandle; osl_loginUser; osl_closeFile

◆ osl_freeProcessHandle()

SAL_DLLPUBLIC void osl_freeProcessHandle ( oslProcess Process )

Free the specified process-handle.

Parameters

[in] Process

◆ osl_getCommandArg()

SAL_DLLPUBLIC oslProcessError osl_getCommandArg	(	sal_uInt32	nArg,
		rtl_uString **	strCommandArg
	)

Get the nArg-th command-line argument passed to the main-function of this process.

Parameters

[in]	nArg	The number of the argument to return.
[out]	strCommandArg	The string receives the nArg-th command-line argument.

Returns: osl_Process_E_None or does not return.

See also: osl_executeProcess

◆ osl_getCommandArgCount()

SAL_DLLPUBLIC sal_uInt32 osl_getCommandArgCount ( void )

Returns: the number of commandline arguments passed to the main-function of this process

See also: osl_getCommandArg

◆ osl_getEnvironment()

SAL_DLLPUBLIC oslProcessError osl_getEnvironment	(	rtl_uString *	strVar,
		rtl_uString **	strValue
	)

Get the value of one environment variable.

Parameters

[in]	strVar	denotes the name of the variable to get.
[out]	strValue	string that receives the value of environment variable.

◆ osl_getExecutableFile()

SAL_DLLPUBLIC oslProcessError osl_getExecutableFile ( rtl_uString ** strFile )

Get the filename of the executable.

Parameters

[out] strFile the string that receives the executable file path.

Returns: osl_Process_E_None or does not return.

See also: osl_executeProcess

Ideally this will return the true executable file path as a file: URL, but actually in case something else happens to have been passed as argv[0] to osl_setCommandArgs(), it will return that either as a file URL, or as such in case it doesn't look like an absolute pathname.

◆ osl_getProcess()

SAL_DLLPUBLIC oslProcess osl_getProcess ( oslProcessIdentifier Ident )

Deprecated:

Retrieve the process handle of a process identifier

Parameters

[in] Ident a process identifier

Returns: the process handle on success, NULL in all other cases

◆ osl_getProcessInfo()

SAL_DLLPUBLIC oslProcessError osl_getProcessInfo	(	oslProcess	Process,
		oslProcessData	Fields,
		oslProcessInfo *	pInfo
	)

Retrieves information about a Process.

Parameters

[in]	Process	the process handle of the process
[in]	Fields	the information which is to be retrieved this can be one or more of osl_Process_IDENTIFIER osl_Process_EXITCODE osl_Process_CPUTIMES osl_Process_HEAPUSAGE
[out]	pInfo	a pointer to a valid oslProcessInfo structure. the Size field has to be initialized with the size of the oslProcessInfo structure. on success the Field member holds the (or'ed) retrieved valid information fields.

Return values

osl_Process_E_None	on success
osl_Process_E_Unknown	on failure

◆ osl_getProcessLocale()

SAL_DLLPUBLIC oslProcessError osl_getProcessLocale ( rtl_Locale ** ppLocale )

Get the locale the process is currently running in.

Parameters

[out] ppLocale a pointer that receives the currently selected locale structure

◆ osl_getProcessWorkingDir()

SAL_DLLPUBLIC oslProcessError osl_getProcessWorkingDir ( rtl_uString ** pustrWorkingDir )

Get the working directory of the current process as a file URL.

The file URL is encoded as common for the OSL file API.

Parameters

[out] pustrWorkingDir string that receives the working directory file URL.

◆ osl_joinProcess()

SAL_DLLPUBLIC oslProcessError osl_joinProcess ( oslProcess Process )

Wait for completion of the specified childprocess.

Parameters

[in] Process

Return values

ols_Process_E_None

See also: osl_executeProcess

◆ osl_joinProcessWithTimeout()

SAL_DLLPUBLIC oslProcessError osl_joinProcessWithTimeout	(	oslProcess	Process,
		const TimeValue *	pTimeout
	)

Wait with a timeout for the completion of the specified child process.

Parameters

[in]	Process	A process identifier.
[in]	pTimeout	A timeout value or NULL for infinite waiting. The unit of resolution is second.

Return values

osl_Process_E_None	on success
osl_Process_E_TimedOut	waiting for the child process timed out
osl_Process_E_Unknown	an error occurred or the parameter are invalid

See also: osl_executeProcess

◆ osl_setCommandArgs()

SAL_DLLPUBLIC void osl_setCommandArgs	(	int	argc,
		char **	argv
	)

Set the command-line arguments as passed to the main-function of this process.

Deprecated: This function is only for internal use. Passing the args from main will only work for Unix, on Windows there's no effect, the full command line will automatically be taken. This is due to Windows 9x/ME limitation that don't allow UTF-16 wmain to provide a osl_setCommandArgsU( int argc, sal_Unicode **argv );

Parameters

[in]	argc	The number of elements in the argv array.
[in]	argv	The array of command-line arguments.

See also: osl_getExecutableFile; osl_getCommandArgCount; osl_getCommandArg

◆ osl_setEnvironment()

SAL_DLLPUBLIC oslProcessError osl_setEnvironment	(	rtl_uString *	strVar,
		rtl_uString *	strValue
	)

Set the value of one environment variable.

Parameters

[in]	strVar	denotes the name of the variable to set.
[in]	strValue	string of the new value of environment variable.

Since: UDK 3.2.13

◆ osl_setProcessLocale()

SAL_DLLPUBLIC oslProcessError osl_setProcessLocale ( rtl_Locale * pLocale )

Change the locale of the process.

Parameters

[in] pLocale a pointer to the locale to be set

Deprecated:: LibreOffice itself does not use this, and client code should not have good use for it either. It may eventually be removed.

◆ osl_terminateProcess()

SAL_DLLPUBLIC oslProcessError osl_terminateProcess ( oslProcess Process )

Terminate a process.

Parameters

[in] Process the handle of the process to be terminated

See also: osl_executeProcess; osl_getProcess; osl_joinProcess

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ osl_Process_CPUTIMES

◆ osl_Process_DETACHED

◆ osl_Process_EXITCODE

◆ osl_Process_FULLSCREEN

◆ osl_Process_HEAPUSAGE

◆ osl_Process_HIDDEN

◆ osl_Process_IDENTIFIER

◆ osl_Process_MAXIMIZED

◆ osl_Process_MINIMIZED

◆ osl_Process_NORMAL

◆ osl_Process_SEARCHPATH

◆ osl_Process_WAIT

Typedef Documentation

◆ oslProcess

◆ oslProcessData

◆ oslProcessExitCode

◆ oslProcessIdentifier

◆ oslProcessOption

Enumeration Type Documentation

◆ oslProcessError

Function Documentation

◆ osl_clearEnvironment()

◆ osl_executeProcess()

◆ osl_executeProcess_WithRedirectedIO()

◆ osl_freeProcessHandle()

◆ osl_getCommandArg()

◆ osl_getCommandArgCount()

◆ osl_getEnvironment()

◆ osl_getExecutableFile()

◆ osl_getProcess()

◆ osl_getProcessInfo()

◆ osl_getProcessLocale()

◆ osl_getProcessWorkingDir()

◆ osl_joinProcess()

◆ osl_joinProcessWithTimeout()

◆ osl_setCommandArgs()

◆ osl_setEnvironment()

◆ osl_setProcessLocale()

◆ osl_terminateProcess()