syscall.h

  1/* SPDX-License-Identifier: GPL-2.0-only */
  2/*
  3 * Access to user system call parameters and results
  4 *
  5 * Copyright (C) 2008-2009 Red Hat, Inc.  All rights reserved.
  6 *
  7 * This file is a stub providing documentation for what functions
  8 * arch/ARCH/include/asm/syscall.h files need to define.  Most arch definitions
  9 * will be simple inlines.
 10 *
 11 * All of these functions expect to be called with no locks,
 12 * and only when the caller is sure that the task of interest
 13 * cannot return to user mode while we are looking at it.
 14 */
 15
 16#ifndef _ASM_SYSCALL_H
 17#define _ASM_SYSCALL_H	1
 18
 19struct task_struct;
 20struct pt_regs;
 21
 22/**
 23 * syscall_get_nr - find what system call a task is executing
 24 * @task:	task of interest, must be blocked
 25 * @regs:	task_pt_regs() of @task
 26 *
 27 * If @task is executing a system call or is at system call
 28 * tracing about to attempt one, returns the system call number.
 29 * If @task is not executing a system call, i.e. it's blocked
 30 * inside the kernel for a fault or signal, returns -1.
 31 *
 32 * Note this returns int even on 64-bit machines.  Only 32 bits of
 33 * system call number can be meaningful.  If the actual arch value
 34 * is 64 bits, this truncates to 32 bits so 0xffffffff means -1.
 35 *
 36 * It's only valid to call this when @task is known to be blocked.
 37 */
 38int syscall_get_nr(struct task_struct *task, struct pt_regs *regs);
 39
 40/**
 41 * syscall_set_nr - change the system call a task is executing
 42 * @task:	task of interest, must be blocked
 43 * @regs:	task_pt_regs() of @task
 44 * @nr:		system call number
 45 *
 46 * Changes the system call number @task is about to execute.
 47 *
 48 * It's only valid to call this when @task is stopped for tracing on
 49 * entry to a system call, due to %SYSCALL_WORK_SYSCALL_TRACE or
 50 * %SYSCALL_WORK_SYSCALL_AUDIT.
 51 */
 52void syscall_set_nr(struct task_struct *task, struct pt_regs *regs, int nr);
 53
 54/**
 55 * syscall_rollback - roll back registers after an aborted system call
 56 * @task:	task of interest, must be in system call exit tracing
 57 * @regs:	task_pt_regs() of @task
 58 *
 59 * It's only valid to call this when @task is stopped for system
 60 * call exit tracing (due to %SYSCALL_WORK_SYSCALL_TRACE or
 61 * %SYSCALL_WORK_SYSCALL_AUDIT), after ptrace_report_syscall_entry()
 62 * returned nonzero to prevent the system call from taking place.
 63 *
 64 * This rolls back the register state in @regs so it's as if the
 65 * system call instruction was a no-op.  The registers containing
 66 * the system call number and arguments are as they were before the
 67 * system call instruction.  This may not be the same as what the
 68 * register state looked like at system call entry tracing.
 69 */
 70void syscall_rollback(struct task_struct *task, struct pt_regs *regs);
 71
 72/**
 73 * syscall_get_error - check result of traced system call
 74 * @task:	task of interest, must be blocked
 75 * @regs:	task_pt_regs() of @task
 76 *
 77 * Returns 0 if the system call succeeded, or -ERRORCODE if it failed.
 78 *
 79 * It's only valid to call this when @task is stopped for tracing on exit
 80 * from a system call, due to %SYSCALL_WORK_SYSCALL_TRACE or
 81 * %SYSCALL_WORK_SYSCALL_AUDIT.
 82 */
 83long syscall_get_error(struct task_struct *task, struct pt_regs *regs);
 84
 85/**
 86 * syscall_get_return_value - get the return value of a traced system call
 87 * @task:	task of interest, must be blocked
 88 * @regs:	task_pt_regs() of @task
 89 *
 90 * Returns the return value of the successful system call.
 91 * This value is meaningless if syscall_get_error() returned nonzero.
 92 *
 93 * It's only valid to call this when @task is stopped for tracing on exit
 94 * from a system call, due to %SYSCALL_WORK_SYSCALL_TRACE or
 95 * %SYSCALL_WORK_SYSCALL_AUDIT.
 96 */
 97long syscall_get_return_value(struct task_struct *task, struct pt_regs *regs);
 98
 99/**
100 * syscall_set_return_value - change the return value of a traced system call
101 * @task:	task of interest, must be blocked
102 * @regs:	task_pt_regs() of @task
103 * @error:	negative error code, or zero to indicate success
104 * @val:	user return value if @error is zero
105 *
106 * This changes the results of the system call that user mode will see.
107 * If @error is zero, the user sees a successful system call with a
108 * return value of @val.  If @error is nonzero, it's a negated errno
109 * code; the user sees a failed system call with this errno code.
110 *
111 * It's only valid to call this when @task is stopped for tracing on exit
112 * from a system call, due to %SYSCALL_WORK_SYSCALL_TRACE or
113 * %SYSCALL_WORK_SYSCALL_AUDIT.
114 */
115void syscall_set_return_value(struct task_struct *task, struct pt_regs *regs,
116			      int error, long val);
117
118/**
119 * syscall_get_arguments - extract system call parameter values
120 * @task:	task of interest, must be blocked
121 * @regs:	task_pt_regs() of @task
122 * @args:	array filled with argument values
123 *
124 * Fetches 6 arguments to the system call.  First argument is stored in
125*  @args[0], and so on.
126 *
127 * It's only valid to call this when @task is stopped for tracing on
128 * entry to a system call, due to %SYSCALL_WORK_SYSCALL_TRACE or
129 * %SYSCALL_WORK_SYSCALL_AUDIT.
130 */
131void syscall_get_arguments(struct task_struct *task, struct pt_regs *regs,
132			   unsigned long *args);
133
134/**
135 * syscall_set_arguments - change system call parameter value
136 * @task:	task of interest, must be in system call entry tracing
137 * @regs:	task_pt_regs() of @task
138 * @args:	array of argument values to store
139 *
140 * Changes 6 arguments to the system call.
141 * The first argument gets value @args[0], and so on.
142 *
143 * It's only valid to call this when @task is stopped for tracing on
144 * entry to a system call, due to %SYSCALL_WORK_SYSCALL_TRACE or
145 * %SYSCALL_WORK_SYSCALL_AUDIT.
146 */
147void syscall_set_arguments(struct task_struct *task, struct pt_regs *regs,
148			   const unsigned long *args);
149
150/**
151 * syscall_get_arch - return the AUDIT_ARCH for the current system call
152 * @task:	task of interest, must be blocked
153 *
154 * Returns the AUDIT_ARCH_* based on the system call convention in use.
155 *
156 * It's only valid to call this when @task is stopped on entry to a system
157 * call, due to %SYSCALL_WORK_SYSCALL_TRACE, %SYSCALL_WORK_SYSCALL_AUDIT, or
158 * %SYSCALL_WORK_SECCOMP.
159 *
160 * Architectures which permit CONFIG_HAVE_ARCH_SECCOMP_FILTER must
161 * provide an implementation of this.
162 */
163int syscall_get_arch(struct task_struct *task);
164#endif	/* _ASM_SYSCALL_H */