Lines Matching full:system

1 Adding a New System Call
4 This document describes what's involved in adding a new system call to the
9 System Call Alternatives
12 The first thing to consider when adding a new system call is whether one of
13 the alternatives might be suitable instead.  Although system calls are the
32  - If you're just exposing runtime system information, a new node in sysfs
40    :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so
46    with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so
54 A new system call forms part of the API of the kernel, and has to be supported
60 together with the corresponding follow-up system calls --
65 For simpler system calls that only take a couple of arguments, the preferred
67 system call.  To make sure that userspace programs can safely use flags
69 flags, and reject the system call (with ``EINVAL``) if it does::
76 For more sophisticated system calls that involve a larger number of arguments,
106 If your new system call allows userspace to refer to a kernel object, it
111 If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
121 If your system call returns a new file descriptor, you should also consider
122 what it means to use the :manpage:`poll(2)` family of system calls on that file
127 If your new :manpage:`xyzzy(2)` system call involves a filename argument::
147 If your new :manpage:`xyzzy(2)` system call involves a parameter describing an
151 If your new :manpage:`xyzzy(2)` system call involves privileged functionality,
160 If your new :manpage:`xyzzy(2)` system call manipulates a process other than
167 system call parameters that are explicitly 64-bit fall on odd-numbered
176 To make new system calls easy to review, it's best to divide up the patchset
180  - The core implementation of the system call, together with prototypes,
182  - Wiring up of the new system call for one particular architecture, usually
184  - A demonstration of the use of the new system call in userspace via a
186  - A draft man-page for the new system call, either as plain text in the
189 New system call proposals, like any change to the kernel's API, should always
193 Generic System Call Implementation
196 The main entry point for your new :manpage:`xyzzy(2)` system call will be called
199 number of arguments to the system call, and the macro takes the system call name
201 this macro allows metadata about the new system call to be made available for
205 ``include/linux/syscalls.h``, marked as asmlinkage to match the way that system
212 new system call to the generic list by adding an entry to the list in
218 Also update the __NR_syscalls count to reflect the additional system call, and
219 note that if multiple new system calls are added in the same merge window,
223 system call, returning ``-ENOSYS``.  Add your new system call here too::
227 Your new kernel functionality, and the system call that controls it, should
231  - Include a description of the new functionality and system call controlled
248 x86 System Call Implementation
251 To wire up your new system call for x86 platforms, you need to update the
252 master syscall tables.  Assuming your new system call isn't special in some
266 Compatibility System Calls (Generic)
269 For most system calls the same 64-bit implementation can be invoked even when
270 the userspace program is itself 32-bit; even if the system call's parameters
278 64-bit values.  In particular, this is needed whenever a system call argument
288 system call's arguments has a type that is explicitly 64-bit even on a 32-bit
293 (Note that a system call argument that's a pointer to an explicit 64-bit type
295 type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.)
297 The compatibility version of the system call is called ``compat_sys_xyzzy()``,
306 ``include/linux/compat.h``, marked as asmlinkage to match the way that system
311 If the system call involves a structure that is laid out differently on 32-bit
337 The generic system call list also needs adjusting to allow for the compat
353 Compatibility System Calls (x86)
356 To wire up the x86 architecture of a system call with a compatibility version,
366 the new system call.  There's a choice here: the layout of the arguments
378 If no pointers are involved, then it is preferable to re-use the 64-bit system
387 System Calls Returning Elsewhere
390 For most system calls, once the system call is complete the user program
392 stack the same and most of the registers the same as before the system call,
395 However, a few system calls do things differently.  They might return to a
400 To allow for this, the kernel implementation of the system call may need to
402 control of where and how execution continues after the system call.
405 that save/restore additional registers and invoke the real system call entry
421 If the system call needs a compatibility layer (as in the previous section)
423 of the system call rather than the native 64-bit version.  Also, if the x32 ABI
440 Most of the kernel treats system calls in a generic way, but there is the
441 occasional exception that may need updating for your particular system call.
444 functions that classify some special types of system call -- specifically
446 socket multiplexor (``socketcall``) operations. If your new system call is
447 analogous to one of these, then the audit system should be updated.
449 More generally, if there is an existing system call that is analogous to your
450 new system call, it's worth doing a kernel-wide grep for the existing system
457 A new system call should obviously be tested; it is also useful to provide
458 reviewers with a demonstration of how user space programs will use the system
462 For a new system call, there will obviously be no libc wrapper function and so
463 the test will need to invoke it using ``syscall()``; also, if the system call
482 All new system calls should come with a complete man page, ideally using groff
491 Do not call System Calls in the Kernel
494 System calls are, as stated above, interaction points between userspace and
495 the kernel.  Therefore, system call functions such as ``sys_xyzzy()`` or
506 call system call functions in the kernel.  It uses a different calling
507 convention for system calls where ``struct pt_regs`` is decoded on-the-fly in a
525  - LWN article from Michael Kerrisk on use of flags argument in system calls:
527  - LWN article from Michael Kerrisk on how to handle unknown flags in a system
529  - LWN article from Jake Edge describing constraints on 64-bit system call
531  - Pair of LWN articles from David Drysdale that describe the system call
537  - Architecture-specific requirements for system calls are discussed in the
547    system call should come in the same email thread:
549  - Recommendation from Michael Kerrisk that a new system call should come with
553  - Suggestion from Greg Kroah-Hartman that it's good for new system calls to
555  - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension:
557  - Suggestion from Ingo Molnar that system calls that involve multiple
572  - Recommendation from Linus Torvalds that x32 system calls should prefer