Typedefs
typedef VOID(*	SYSCALL_ENTRY_CALLBACK) (THREADID threadIndex, CONTEXT ctxt, SYSCALL_STANDARD std, VOID v)

typedef VOID(*	SYSCALL_EXIT_CALLBACK) (THREADID threadIndex, CONTEXT ctxt, SYSCALL_STANDARD std, VOID v)

Functions
PIN_CALLBACK	PIN_AddSyscallEntryFunction (SYSCALL_ENTRY_CALLBACK fun, VOID *val)

PIN_CALLBACK	PIN_AddSyscallExitFunction (SYSCALL_EXIT_CALLBACK fun, VOID *val)

VOID	PIN_SetSyscallArgument (CONTEXT *ctxt, SYSCALL_STANDARD std, UINT32 argNum, ADDRINT val)

ADDRINT	PIN_GetSyscallArgument (const CONTEXT *ctxt, SYSCALL_STANDARD std, UINT32 argNum)

VOID	PIN_SetSyscallNumber (CONTEXT *ctxt, SYSCALL_STANDARD std, ADDRINT val)

ADDRINT	PIN_GetSyscallNumber (const CONTEXT *ctxt, SYSCALL_STANDARD std)

ADDRINT	PIN_GetSyscallReturn (const CONTEXT *ctxt, SYSCALL_STANDARD std)

VOID	PIN_SetSyscallReturn (CONTEXT *ctxt, SYSCALL_STANDARD std, ADDRINT val)

ADDRINT	PIN_GetSyscallErrno (const CONTEXT *ctxt, SYSCALL_STANDARD std)

VOID	PIN_SetSyscallErrno (CONTEXT *ctxt, SYSCALL_STANDARD std, ADDRINT val)

VOID	PIN_ReplaySyscallEntry (THREADID tid, CONTEXT *ctxt, SYSCALL_STANDARD std)

VOID	PIN_ReplaySyscallExit (THREADID tid, CONTEXT *ctxt, SYSCALL_STANDARD std)

Detailed Description

These APIs provide Pin support for extracting information about, or modifying, system calls made by the pinned program.

Typedef Documentation

◆ SYSCALL_ENTRY_CALLBACK

typedef VOID(* SYSCALL_ENTRY_CALLBACK) (THREADID threadIndex, CONTEXT *ctxt, SYSCALL_STANDARD std, VOID *v)

Call-back function before execution of a system call.

Parameters

[in]	threadIndex	The Pin thread ID of the thread that executes the system call.
[in,out]	ctxt	Application's register state immediately before execution of the system call. The tool may change this and affect the new register state.
[in]	std	The system calling standard.
[in]	v	The tool's call-back value.

◆ SYSCALL_EXIT_CALLBACK

typedef VOID(* SYSCALL_EXIT_CALLBACK) (THREADID threadIndex, CONTEXT *ctxt, SYSCALL_STANDARD std, VOID *v)

Call-back function after execution of a system call.

Parameters

[in]	threadIndex	The Pin thread ID of the thread that executed the system call.
[in,out]	ctxt	Application's register state immediately after execution of the system call.The tool may change this and affect the new register state.
[in]	std	The system calling standard.
[in]	v	The tool's call-back value.

Function Documentation

◆ PIN_AddSyscallEntryFunction()

PIN_CALLBACK PIN_AddSyscallEntryFunction	(	SYSCALL_ENTRY_CALLBACK	fun,
		VOID *	val
	)

Register a notification function that is called immediately before execution of a system call.

Parameters

[in]	fun	Function to be called immediately before execution of a system call.
[in]	val	Value to pass to the function.

Returns: PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties

Note: The pin client lock is obtained during the call of this API..; In Linux systems with kernel 5.3 and above, callbacks will be called also when branching to vsyscall area.

Availability:: Mode: JIT
O/S: Linux, Windows
CPU: All

◆ PIN_AddSyscallExitFunction()

PIN_CALLBACK PIN_AddSyscallExitFunction	(	SYSCALL_EXIT_CALLBACK	fun,
		VOID *	val
	)

Register a notification function that is called immediately after execution of a system call.
The notification is called for each system call when it returns to the application, even if the system call changes control flow and does not fall through to the next instruction.

Parameters

[in]	fun	Function to be called immediately after execution of a system call.
[in]	val	Value to pass to the function.

Note: In order to monitor all possible control transfers from the operating system to the user mode application, the tool has to register both a SYSCALL_EXIT_CALLBACK and a CONTEXT_CHANGE_CALLBACK callback functions. This can be done using the corresponding registration functions: PIN_AddSyscallExitFunction() and PIN_AddContextChangeFunction().
When a system call returns to the application, the tool receives the SYSCALL_EXIT_CALLBACK notification. Usually, this callback immediately follows the corresponding SYSCALL_ENTRY_CALLBACK notification and there is no application code executed between these two events. However, some (Windows) system calls can be interrupted by a system event (APC, Windows callback, exception) before they return to the application. If this happens, the tool receives the corresponding CONTEXT_CHANGE_CALLBACK notification just before the (user mode) handler of the system event gets executed. Eventually, when the event handler and the interrupted system call are completed, the SYSCALL_EXIT_CALLBACK notification is delivered to the tool.

Returns: PIN_CALLBACK A handle to a callback that can be used to further modify this callback's properties

Note: The pin client lock is obtained during the call of this API.; In Linux systems with kernel 5.3 and above, callbacks will be called also when branching to vsyscall area.

Availability:: Mode: JIT
O/S: Linux, Windows
CPU: All

◆ PIN_GetSyscallArgument()

ADDRINT PIN_GetSyscallArgument	(	const CONTEXT *	ctxt,
		SYSCALL_STANDARD	std,
		UINT32	argNum
	)

Get the value of the argument of the system call to be executed in the specified context.
It is a user's responsibility to make sure that the specified context and the current memory content represent the state of a system call before execution. For example, this function can be safely used in the scope of SYSCALL_ENTRY_CALLBACK. Applying this function to an inappropriate context results in undefined behavior and even may cause crash on systems in which system call arguments are located in memory.

Parameters

[in]	ctxt	context before the system call execution
[in]	std	system calling standard
[in]	argNum	ordinal number of the argument whose value is requested. Ordinal numbers start from zero for the first argument

Returns: value of the argument

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetSyscallErrno()

ADDRINT PIN_GetSyscallErrno	(	const CONTEXT *	ctxt,
		SYSCALL_STANDARD	std
	)

Get the error code of the system call which is just returned with the specified context.
It is a user's responsibility to make sure that the specified context represents the state of a system call after execution. For example, this function can be safely used in the scope of SYSCALL_EXIT_CALLBACK. Applying this function to an inappropriate context results in undefined behavior.

Parameters

[in]	ctxt	context after the system call execution
[in]	std	system calling standard

Returns: error code, if the system call failed;
zero, if the system call succeeded

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetSyscallNumber()

ADDRINT PIN_GetSyscallNumber	(	const CONTEXT *	ctxt,
		SYSCALL_STANDARD	std
	)

Get the number (ID) of the system call to be executed in the specified context.
It is a user's responsibility to make sure that the specified context represents the state of a system call before execution. For example, this function can be safely used in the scope of SYSCALL_ENTRY_CALLBACK, but not in a SYSCALL_EXIT_CALLBACK. Applying this function to an inappropriate context results in undefined behavior.

If you need the system call number in a SYSCALL_EXIT_CALLBACK, you should use a SYSCALL_ENTRY_CALLBACK to save the system call number into thread local storage so that you can get it from there in your SYSCALL_EXIT_CALLBACK. Beware, though of interruptable system calls, to handle those you will need to worry about other context changes (see the discussion in PIN_AddSyscallExitFunction ).

In Linux systems with kernel 5.3 and above, calling this API while jumping to vsyscall area will return special number - VSYSCALL_NR.

Parameters

[in]	ctxt	context before the system call execution
[in]	std	system calling standard

Returns: system call number

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_GetSyscallReturn()

ADDRINT PIN_GetSyscallReturn	(	const CONTEXT *	ctxt,
		SYSCALL_STANDARD	std
	)

Get the return value of the system call which has just returned with the specified context.
It is a user's responsibility to make sure that the specified context represents the state of a system call after execution. For example, this function can be safely used in the scope of SYSCALL_EXIT_CALLBACK. Applying this function to an inappropriate context results in undefined behavior.

Parameters

[in]	ctxt	context after the system call execution
[in]	std	system calling standard

Returns: return value of the system call.
On Linux and macOS* the function returns -1 if the system call failed

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_ReplaySyscallEntry()

VOID PIN_ReplaySyscallEntry	(	THREADID	tid,
		CONTEXT *	ctxt,
		SYSCALL_STANDARD	std
	)

Additional client side interface to pin vm containing the interfaces useful for a replay tool. These mainly allow a PinTool to request that Pin execute callbacks associated with specific events.

This API is intended for use by tools that replay the execution of an application and need to behave as if a system call has been made, calling all callbacks registered with PIN_AddSysCallEntry function. However, no system call is actually performed.

This API can be called from an analysis routine or a replacement routine, but not from a call-back.

Parameters

[in]	tid	The ID of the thread in which the system call appears to execute.
[in]	from	The register state at the point when the system call appears to execute.
[in]	std	The calling standard of the system call.

Note: The vm and pin client locks are obtained during the call of this API.

Availability:: Mode: JIT
O/S: Linux,Windows,BSD
CPU: All

◆ PIN_ReplaySyscallExit()

VOID PIN_ReplaySyscallExit	(	THREADID	tid,
		CONTEXT *	ctxt,
		SYSCALL_STANDARD	std
	)

This API is intended for use by tools that replay the execution of an application and need to behave as if a system call has been made, calling all callbacks registered with PIN_AddSysCallExit function. However, no system call is actually performed.

This API can be called from an analysis routine or a replacement routine, but not from a call-back.

Parameters

[in]	tid	The ID of the thread in which the system call appears to execute.
[in]	from	The register state at the point after the system call has executed.
[in]	std	The calling standard of the system call.

Note: The vm and pin client locks are obtained during the call of this API.

Availability:: Mode: JIT
O/S: Linux,Windows,BSD
CPU: All

◆ PIN_SetSyscallArgument()

VOID PIN_SetSyscallArgument	(	CONTEXT *	ctxt,
		SYSCALL_STANDARD	std,
		UINT32	argNum,
		ADDRINT	val
	)

Set the given value for the argument of the system call to be executed in the specified context.
It is a user's responsibility to make sure that the specified context and the current memory content represent the state of a system call before execution. For example, this function can be safely used in the scope of SYSCALL_ENTRY_CALLBACK. Applying this function to an inappropriate context results in undefined behavior and even may cause crash on systems in which system call arguments are located in memory.

Parameters

[in,out]	ctxt	context before the system call execution
[in]	std	system calling standard
[in]	argNum	ordinal number of the argument whose value is to be set. Ordinal numbers start from zero for the first argument
[in]	val	new value of the argument

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_SetSyscallErrno()

VOID PIN_SetSyscallErrno	(	CONTEXT *	ctxt,
		SYSCALL_STANDARD	std,
		ADDRINT	val
	)

Set the error code of the system call which is just returned with the specified context.
It is a user's responsibility to make sure that the specified context represents the state of a system call after execution. For example, this function can be safely used in the scope of SYSCALL_EXIT_CALLBACK. Applying this function to an inappropriate context results in undefined behavior.
The user should set in Linux a negative error value.

Parameters

[in]	ctxt	context after the system call execution
[in]	std	system calling standard
[in]	val	the error value to set for the syscall

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_SetSyscallNumber()

VOID PIN_SetSyscallNumber	(	CONTEXT *	ctxt,
		SYSCALL_STANDARD	std,
		ADDRINT	val
	)

Set the number (ID) of the system call to be executed in the specified context.
It is a user's responsibility to make sure that the specified context represents the state of a system call before execution. For example, this function can be safely used in the scope of SYSCALL_ENTRY_CALLBACK. Applying this function to an inappropriate context results in undefined behavior.

Parameters

[in]	ctxt	context before the system call execution
[in]	std	system calling standard
[in]	val	new system call number

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

◆ PIN_SetSyscallReturn()

VOID PIN_SetSyscallReturn	(	CONTEXT *	ctxt,
		SYSCALL_STANDARD	std,
		ADDRINT	val
	)

Set the return value of the system call which has just returned with the specified context.
It is a user's responsibility to make sure that the specified context represents the state of a system call after execution. For example, this function can be safely used in the scope of SYSCALL_EXIT_CALLBACK. Applying this function to an inappropriate context results in undefined behavior.

Parameters

[in]	ctxt	context after the system call execution
[in]	std	system calling standard
[in]	val	the return value to set for the syscall

Availability:: Mode: JIT
O/S: Linux, Windows & macOS*
CPU: IA-32 and Intel(R) 64 architectures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SYSCALL_ENTRY_CALLBACK

◆ SYSCALL_EXIT_CALLBACK

Function Documentation

◆ PIN_AddSyscallEntryFunction()

◆ PIN_AddSyscallExitFunction()

◆ PIN_GetSyscallArgument()

◆ PIN_GetSyscallErrno()

◆ PIN_GetSyscallNumber()

◆ PIN_GetSyscallReturn()

◆ PIN_ReplaySyscallEntry()

◆ PIN_ReplaySyscallExit()

◆ PIN_SetSyscallArgument()

◆ PIN_SetSyscallErrno()

◆ PIN_SetSyscallNumber()

◆ PIN_SetSyscallReturn()