Process control v0.1.0

Starting processes with CreateProcessW, their startup information, inherited handles and waits.

`SecurityAttributes`

pub struct SecurityAttributes {
    pub length: uint32;
    pub securityDescriptor: *opaque;
    pub inheritHandle: bool32;
}

The SECURITY_ATTRIBUTES a pipe or file is created with: here only whether its handle is inheritable.

Source

Fields

Name	Type	Description
`length`	`uint32`	The structure's size in bytes.
`securityDescriptor`	`*opaque`	A security descriptor, or null for the default.
`inheritHandle`	`bool32`	Non-zero when a child process may inherit the handle.

`StartupInfo`

pub struct StartupInfo {
    pub size: uint32;
    pub reserved: *opaque;
    pub desktop: *uint16;
    pub title: *uint16;
    pub x: uint32;
    pub y: uint32;
    pub xSize: uint32;
    pub ySize: uint32;
    pub xCountChars: uint32;
    pub yCountChars: uint32;
    pub fillAttribute: uint32;
    pub flags: uint32;
    pub showWindow: uint16;
    pub reserved2Size: uint16;
    pub reserved2: *opaque;
    pub standardInput: *opaque;
    pub standardOutput: *opaque;
    pub standardError: *opaque;
}

The STARTUPINFOW a new process is started with; this package fills in its standard handles.

Source

Fields

Name	Type	Description
`size`	`uint32`	The structure's size in bytes.
`reserved`	`*opaque`	Reserved; null.
`desktop`	`*uint16`	The desktop, or null.
`title`	`*uint16`	The console title, or null.
`x`	`uint32`	The window's left edge, when `flags` says so.
`y`	`uint32`	The window's top edge, when `flags` says so.
`xSize`	`uint32`	The window's width, when `flags` says so.
`ySize`	`uint32`	The window's height, when `flags` says so.
`xCountChars`	`uint32`	The console buffer's width in characters, when `flags` says so.
`yCountChars`	`uint32`	The console buffer's height in characters, when `flags` says so.
`fillAttribute`	`uint32`	The console's text and background colors, when `flags` says so.
`flags`	`uint32`	Which fields the system reads, such as `STARTF_USESTDHANDLES`.
`showWindow`	`uint16`	How the window is shown, when `flags` says so.
`reserved2Size`	`uint16`	Reserved; zero.
`reserved2`	`*opaque`	Reserved; null.
`standardInput`	`*opaque`	The child's standard input.
`standardOutput`	`*opaque`	The child's standard output.
`standardError`	`*opaque`	The child's standard error.

`ProcessInformation`

pub struct ProcessInformation {
    pub process: *opaque;
    pub thread: *opaque;
    pub processId: uint32;
    pub threadId: uint32;
}

The PROCESS_INFORMATION CreateProcessW fills in: the new process and its first thread.

Source

Fields

Name	Type	Description
`process`	`*opaque`	The new process's handle, to wait on and close.
`thread`	`*opaque`	Its first thread's handle, to close.
`processId`	`uint32`	The process identifier.
`threadId`	`uint32`	The first thread's identifier.

`STARTF_USESTDHANDLES`

pub const STARTF_USESTDHANDLES: uint32 = 0x00000100;

STARTF_USESTDHANDLES: the standard handles in StartupInfo are the child's.

Source

`CREATE_UNICODE_ENVIRONMENT`

pub const CREATE_UNICODE_ENVIRONMENT: uint32 = 0x00000400;

CREATE_UNICODE_ENVIRONMENT: the environment block is UTF-16.

Source

`HANDLE_FLAG_INHERIT`

pub const HANDLE_FLAG_INHERIT: uint32 = 0x00000001;

HANDLE_FLAG_INHERIT: the handle is inherited by child processes.

Source

`DUPLICATE_SAME_ACCESS`

pub const DUPLICATE_SAME_ACCESS: uint32 = 0x00000002;

DUPLICATE_SAME_ACCESS: a duplicated handle has the access of the original.

Source

`WAIT_TIMEOUT`

pub const WAIT_TIMEOUT: uint32 = 0x00000102;

WAIT_TIMEOUT: a wait ended because its time ran out.

Source

`ERROR_BROKEN_PIPE`

pub const ERROR_BROKEN_PIPE: uint32 = 109;

ERROR_BROKEN_PIPE: the other end of the pipe was closed.

Source

`CreateProcessW`

pub extern func CreateProcessW(
    applicationName: *uint16,
    commandLine: *var uint16,
    processAttributes: *SecurityAttributes,
    threadAttributes: *SecurityAttributes,
    inheritHandles: bool32,
    creationFlags: uint32,
    environment: *opaque,
    currentDirectory: *uint16,
    startupInfo: *StartupInfo,
    processInformation: *var ProcessInformation
) -> bool32

Starts a program as a new process.

Source

Parameters

Name	Type	Description
`applicationName`	`*uint16`	the program's path, or null to take it from the command line
`commandLine`	`*var uint16`	the command line, which the call may modify
`processAttributes`	`*SecurityAttributes`	the process handle's security, or null
`threadAttributes`	`*SecurityAttributes`	the thread handle's security, or null
`inheritHandles`	`bool32`	non-zero to let the child inherit the parent's inheritable handles
`creationFlags`	`uint32`	flags such as `CREATE_UNICODE_ENVIRONMENT`
`environment`	`*opaque`	the environment block, or null to inherit the parent's
`currentDirectory`	`*uint16`	the child's working directory, or null for the parent's
`startupInfo`	`*StartupInfo`	how the child starts, including its standard handles
`processInformation`	`*var ProcessInformation`	receives the new process and thread

Returns: non-zero on success, and zero on failure with the reason in GetLastError

`GetExitCodeProcess`

pub extern func GetExitCodeProcess(
    process: *opaque,
    exitCode: *var uint32
) -> bool32

Reads a process's exit code, or STILL_ACTIVE while it runs.

Source

Parameters

Name	Type	Description
`process`	`*opaque`	the process handle
`exitCode`	`*var uint32`	receives the code

Returns: non-zero on success, and zero on failure with the reason in GetLastError

`TerminateProcess`

pub extern func TerminateProcess(
    process: *opaque,
    exitCode: uint32
) -> bool32

Ends a process and all its threads.

Source

Parameters

Name	Type	Description
`process`	`*opaque`	the process handle
`exitCode`	`uint32`	the code the process ends with

Returns: non-zero on success, and zero on failure with the reason in GetLastError

`CreatePipe`

pub extern func CreatePipe(
    readPipe: *var *opaque,
    writePipe: *var *opaque,
    attributes: *SecurityAttributes,
    size: uint32
) -> bool32

Creates an anonymous pipe.

Source

Parameters

Name	Type	Description
`readPipe`	`var opaque`	receives the read end
`writePipe`	`var opaque`	receives the write end
`attributes`	`*SecurityAttributes`	whether the ends are inheritable, or null
`size`	`uint32`	the buffer size suggestion, or zero for the default

Returns: non-zero on success, and zero on failure with the reason in GetLastError

`SetHandleInformation`

pub extern func SetHandleInformation(
    handle: *opaque,
    mask: uint32,
    flags: uint32
) -> bool32

Changes a handle's flags, such as whether it is inherited.

Source

Parameters

Name	Type	Description
`handle`	`*opaque`	the handle
`mask`	`uint32`	the flags to change
`flags`	`uint32`	their new values

Returns: non-zero on success, and zero on failure with the reason in GetLastError

`DuplicateHandle`

pub extern func DuplicateHandle(
    sourceProcess: *opaque,
    sourceHandle: *opaque,
    targetProcess: *opaque,
    targetHandle: *var *opaque,
    desiredAccess: uint32,
    inheritHandle: bool32,
    options: uint32
) -> bool32

Duplicates a handle, here into the same process with different inheritance.

Source

Parameters

Name	Type	Description
`sourceProcess`	`*opaque`	the process that owns the handle
`sourceHandle`	`*opaque`	the handle
`targetProcess`	`*opaque`	the process to duplicate it into
`targetHandle`	`var opaque`	receives the duplicate
`desiredAccess`	`uint32`	the access to grant, ignored with `DUPLICATE_SAME_ACCESS`
`inheritHandle`	`bool32`	non-zero to make the duplicate inheritable
`options`	`uint32`	flags such as `DUPLICATE_SAME_ACCESS`

Returns: non-zero on success, and zero on failure with the reason in GetLastError

`GetCurrentProcess`

pub extern func GetCurrentProcess() -> *opaque

Returns a pseudo-handle for the calling process, which needs no closing.

Source

Returns: the pseudo-handle

`SetEnvironmentVariableW`

pub extern func SetEnvironmentVariableW(
    name: *uint16,
    value: *uint16
) -> bool32

Sets or removes an environment variable of the calling process.

Source

Parameters

Name	Type	Description
`name`	`*uint16`	the variable's name, NUL-terminated
`value`	`*uint16`	its new value, NUL-terminated, or null to remove it

Returns: non-zero on success, and zero on failure with the reason in GetLastError

Processes and threads

Exiting, threads, waiting and loading libraries.

Address waits

WaitOnAddress and the calls that wake its waiters.

Edit this page on GitHub