Version | Date | Change |
---|---|---|
0.1 | 2008-01-10 | Initial contribution |
0.2 | 2009-02-26 | Added signal and environment commands, and properties for standard I/O redirection |
Processes service provides access to the target OS's process information, allows to start and terminate a process, and allows to attach and detach a process for debugging. Debug services, like Memory and Run Control, require a process to be attached before they can access it.
If a process is started by this service, its standard input/output streams are available for client to read/write using Streams Service. Stream type of such streams is set to "Processes".
Command and event parameters are encoded as zero terminated JSON strings.
The service uses standard format for error reports, see Error Report Format.
C • <token> • Processes • getContext • <string: context ID> •
The command retrieves context info for given context ID. A context corresponds to an execution thread, process, address space, etc. Context IDs are valid across TCF services, so it is allowed to issue 'Processes.getContext' command with a context that was obtained, for example, from Memory service. However, 'Processes.getContext' is supposed to return only process specific data. If the ID is not a process ID, 'Processes.getContext' may not return any useful information.
Reply:
R • <token> • <error report> • <context data> • <context data> ⇒ null ⇒ <object>
Context data object should, at least, contain member "ID" : <string>.
Predefined process context properties are:
"ID" : <string>
- ID of the context, same as getContext command argument.
"ParentID" : <string>
- parent context ID.
"Name" : <string>
- process name. Client UI can show this name to a user.
"Attached" : <boolean>
- true if the context is attached to debugger.
"CanTerminate" : <boolean>
- true if the service can terminate the process.
"StdInID" : <string>
- process standard input stream ID.
"StdOutID" : <string>
- process standard output stream ID.
"StdErrID" : <string>
- process standard error stream ID.
C • <token> • Processes • getChildren • <string: parent context ID> • <boolean: attached only> •
The command requests a list of contexts available for process control commands.
Parent context ID can be null – to retrieve top level of the hierarchy, can be one of context IDs retrieved by previous getChildren commands, or it can be obtained from another service. Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to choose layout that is most descriptive for a given target.
If <boolean: attached only> is true, the command returns only those processes that are attached for debugging.
Reply:
R • <token> • <error report> • <array of context IDs> • <array of context IDs> ⇒ null ⇒ [ ] ⇒ [ <context ID list> ] <context ID list> ⇒ <string: context ID> ⇒ <context ID list> , <string: context ID>
C • <token> • Processes • attach • <string: context ID> •
The command attaches debugger to a process. Services like Run Control, Memory, Breakpoints work only with attached processes.
Reply:
R • <token> • <error report> •
C • <token> • Processes • detach • <string: context ID> •
The command detaches debugger from a process.
Reply:
R • <token> • <error report> •
C • <token> • Processes • terminate • <string: context ID> •
The command terminates a process.
Reply:
R • <token> • <error report> •
C • <token> • Processes • getSignalList • <string: context ID> •
The command returns a complete list of available signals. The list containg all signals that can be sent to a given context.
Reply:
R • <token> • <error report> • <array of signal descriptions> • <array of signal descriptions> ⇒ null ⇒ [ ] ⇒ [ <signal description list> ] <signal description list> ⇒ <object: signal description> ⇒ <signal description list> , <object: signal description>
Signal description is a list of properties. Predefined signal properties are:
"Index" : <int>
- bit position of the signal in bitsets that are used by Get Signal Mask and Set Signal Mask commands.
"Name" : <string>
- signal name. Client UI can show this name to a user.
"Code" : <string>
- human readable description of the signal.
C • <token> • Processes • getSignalMask • <string: context ID> •
The command returns signal mask of a process or a thread. Bits in the mask control how signals should be handled by debug agent. When new context is created it inherits the mask from its parent. If context is not attached the command will return an error.
Reply:
R • <token> • <error report> • <int: don't stop bitset> • <int: don't pass bitset> • <int: pending bitset> •
C • <token> • Processes • setSignalMask • <string: context ID> • <int: don't stop bitset> • <int: don't pass bitset> •
The command sets signal mask of a process or a thread. Bits in the mask control how signals should be handled by debug agent. If context is not attached the command will return an error.
Reply:
R • <token> • <error report> •
C • <token> • Processes • signal • <string: context ID> • <int: signal> •
The command sends a signal to a context.
Reply:
R • <token> • <error report> •
C • <token> • Processes • getEnvironment •
The command returns default set of environment variables used to start a new process.
Reply:
R • <token> • <error report> • <object: environment variables> •
C • <token> • Processes • start • <string: working directory> • <string: program image file> • <string array: command line> • <object: environment variables> • <boolean: attach> • <string array> ⇒ null ⇒ [ ] ⇒ [ <string list> ] <string list> ⇒ <string> ⇒ <string list> , <string>
The command starts a new process on remote machine.
Reply:
R • <token> • <error report> • <context data> •
On success the command returns context data for created process. Context data has same format as Get Context result.
Processes service broadcasts notification event when a proceess exits. Only processes that were started by the service will generate exit event.
E • Processes • exited • <string: process ID> • <int: exit code> •
public interface IProcesses extends IService { static final String NAME = "Processes"; /** * Retrieve context info for given context ID. * A context corresponds to an execution thread, process, address space, etc. * Context IDs are valid across TCF services, so it is allowed to issue * 'IProcesses.getContext' command with a context that was obtained, * for example, from Memory service. * However, 'Processes.getContext' is supposed to return only process specific data, * If the ID is not a process ID, 'IProcesses.getContext' may not return any * useful information * * @param id – context ID. * @param done - call back interface called when operation is completed. */ IToken getContext(String id, DoneGetContext done); /** * Client call back interface for getContext(). */ interface DoneGetContext { /** * Called when contexts data retrieval is done. * @param error – error description if operation failed, null if succeeded. * @param context – context data. */ void doneGetContext(IToken token, Exception error, ProcessContext context); } /** * Retrieve children of given context. * * @param parent_context_id – parent context ID. Can be null – * to retrieve top level of the hierarchy, or one of context IDs retrieved * by previous getContext or getChildren commands. * @param attached_only - if true return only attached process IDs. * @param done - call back interface called when operation is completed. */ IToken getChildren(String parent_context_id, boolean attached_only, DoneGetChildren done); /** * Client call back interface for getChildren(). */ interface DoneGetChildren { /** * Called when contexts data retrieval is done. * @param error – error description if operation failed, null if succeeded. * @param context_ids – array of available context IDs. */ void doneGetChildren(IToken token, Exception error, String[] context_ids); } /** * Context property names. */ static final String /** The TCF context ID */ PROP_ID = "ID", /** The TCF parent context ID */ PROP_PARENTID = "ParentID", /** Is the context attached */ PROP_ATTACHED = "Attached", /** Can terminate the context */ PROP_CAN_TERMINATE = "CanTerminate", /** Process name. Client UI can show this name to a user */ PROP_NAME = "Name", /** Process standard input stream ID */ PROP_STDIN_ID = "StdInID", /** Process standard output stream ID */ PROP_STDOUT_ID = "StdOutID", /** Process standard error stream ID */ PROP_STDERR_ID = "StdErrID"; interface ProcessContext { /** * Get context ID. * Same as getProperties().get(“ID”) */ String getID(); /** * Get parent context ID. * Same as getProperties().get(“ParentID”) */ String getParentID(); /** * Get process name. * Client UI can show this name to a user. * Same as getProperties().get(“Name”) */ String getName(); /** * Utility method to read context property PROP_ATTACHED. * Services like IRunControl, IMemory, IBreakpoints work only with attached processes. * @return value of PROP_ATTACHED. */ boolean isAttached(); /** * Utility method to read context property PROP_CAN_TERMINATE. * @return value of PROP_CAN_TERMINATE. */ boolean canTerminate(); /** * Get all available context properties. * @return Map 'property name' -> 'property value' */ Map<String, Object> getProperties(); /** * Attach debugger to a process. * Services like IRunControl, IMemory, IBreakpoints work only with attached processes. * @param done - call back interface called when operation is completed. * @return pending command handle, can be used to cancel the command. */ IToken attach(DoneCommand done); /** * Detach debugger from a process. * Process execution will continue without debugger supervision. * @param done - call back interface called when operation is completed. * @return pending command handle, can be used to cancel the command. */ IToken detach(DoneCommand done); /** * Terminate a process. * @param done - call back interface called when operation is completed. * @return pending command handle, can be used to cancel the command. */ IToken terminate(DoneCommand done); } interface DoneCommand { void doneCommand(IToken token, Exception error); } /** * Signal property names used by "getSignalList" command. */ static final String /** Number, bit position in the signal mask */ SIG_INDEX = "Index", /** String, signal name, for example "SIGHUP" */ SIG_NAME = "Name", /** Number, signal code, as defined by OS */ SIG_CODE = "Code", /** String, human readable description of the signal */ SIG_DESCRIPTION = "Description"; /** * Get list of signals that can be send to the context. * @param done - call back interface called when operation is completed. * @return pending command handle, can be used to cancel the command. */ IToken getSignalList(String context_id, DoneGetSignalList done); /** * Call-back interface to be called when "getSignalList" command is complete. */ interface DoneGetSignalList { void doneGetSignalList(IToken token, Exception error, Collection