{anchor:top}
h1. {anchor:CHP-SYSCALL} {{syscall}} Provider
The {{syscall}} provider makes available a probe at the entry to and return from every system call in the system. Because system calls are the primary interface between user-level applications and the operating system kernel, the {{syscall}} provider can offer tremendous insight into application behavior with respect to the system.
[Top|#top]
h2. {anchor:CHP-SYSCALL-1} Probes
{{syscall}} provides a pair of probes for each system call: an {{entry}} probe that fires before the system call is entered, and a {{return}} probe that fires after the system call has completed but before control has transferred back to user-level. For all {{syscall}} probes, the function name is set to be the name of the instrumented system call and the module name is undefined.\\
\\The names of the system calls as provided by the {{syscall}} provider may be found in the {{/etc/name_to_sysnum}} file. Often, the system call names provided by {{syscall}} correspond to names in Section 2 of the man pages. However, some probes provided by the {{syscall}} provider do not directly correspond to any documented system call. There common reasons for this discrepancy are described in this section.
[Top|#top]
h3. {anchor:CHP-SYSCALL-2} System Call Anachronisms
In some cases, the name of the system call as provided by the {{syscall}} provider is actually a reflection of an ancient implementation detail. For example, for reasons dating back to UNIX™ antiquity, the name of [{{exit}}(2)|http://docs.sun.com/doc/819-2241/exit-2?a=view] in {{/etc/name_to_sysnum}} is {{rexit}}. Similarly, the name of [{{time}}(2)|http://docs.sun.com/doc/819-2241/time-2?a=view] is {{gtime}}, and the name of both [{{execle}}(2)|http://docs.sun.com/doc/819-2241/execle-2?a=view] and [{{execve}}(2)|http://docs.sun.com/doc/819-2241/execve-2?a=view] is {{exece}}.
[Top|#top]
h3. {anchor:CHP-SYSCALL-3} Subcoded System Calls
Some system calls as presented in Section 2 are implemented as suboperations of an undocumented system call. For example, the system calls related to System V semaphores ([{{semctl}}(2)|http://docs.sun.com/doc/819-2241/semctl-2?a=view], [{{semget}}(2)|http://docs.sun.com/doc/819-2241/semget-2?a=view], [{{semids}}(2)|http://docs.sun.com/doc/819-2241/semids-2?a=view], [{{semop}}(2)|http://docs.sun.com/doc/819-2241/semop-2?a=view], and [{{semtimedop}}(2)|http://docs.sun.com/doc/819-2241/semtimedop-2?a=view]) are implemented as suboperations of a single system call, {{semsys}}. The {{semsys}} system call takes as its first argument an implementation-specific _subcode_ denoting the specific system call required: {{SEMCTL}}, {{SEMGET}}, {{SEMIDS}}, {{SEMOP}} or {{SEMTIMEDOP}}, respectively. As a result of overloading a single system call to implement multiple system calls, there is only a single pair of syscall probes for System V semaphores: {{syscall::semsys:entry}} and {{syscall::semsys:return}}.
[Top|#top]
h3. {anchor:CHP-SYSCALL-4} Large File System Calls
A 32-bit program that supports _large files_ that exceed four gigabytes in size must be able to process 64–bit file offsets. Because large files require use of large offsets, large files are manipulated through a parallel set of system interfaces, as described in [{{lf64}}(5)|http://docs.sun.com/doc/819-2252/lf64-5?a=view]. These interfaces are documented in {{lf64}}, but they do not have individual man pages. Each of these large file system call interfaces appears as its own {{syscall}} probe as shown in [Table 21–1|#TBL-SYSCALL].
h6. {anchor:TBL-SYSCALL} {{sycall}} Large File Probes
||Large File {{syscall}} Probe||System Call||
|{{creat64}}|[{{creat}}(2)|http://docs.sun.com/doc/819-2241/creat-2?a=view]|
|{{fstat64}}|[{{fstat}}(2)|http://docs.sun.com/doc/819-2241/fstat-2?a=view]|
|{{fstatvfs64}}|[{{fstatvfs}}(2)|http://docs.sun.com/doc/819-2241/fstatvfs-2?a=view]|
|{{getdents64}}|[{{getdents}}(2)|http://docs.sun.com/doc/819-2241/getdents-2?a=view]|
|{{getrlimit64}}|[{{getrlimit}}(2)|http://docs.sun.com/doc/819-2241/getrlimit-2?a=view]|
|{{lstat64}}|[{{lstat}}(2)|http://docs.sun.com/doc/819-2241/lstat-2?a=view]|
|{{mmap64}}|[{{mmap}}(2)|http://docs.sun.com/doc/819-2241/mmap-2?a=view]|
|{{open64}}|[{{open}}(2)|http://docs.sun.com/doc/819-2241/open-2?a=view]|
|{{pread64}}|[{{pread}}(2)|http://docs.sun.com/doc/819-2241/pread-2?a=view]|
|{{pwrite64}}|[{{pwrite}}(2)|http://docs.sun.com/doc/819-2241/pwrite-2?a=view]|
|{{setrlimit64}}|[{{setrlimit}}(2)|http://docs.sun.com/doc/819-2241/setrlimit-2?a=view]|
|{{stat64}}|[{{stat}}(2)|http://docs.sun.com/doc/819-2241/stat-2?a=view]|
|{{statvfs64}}|[{{statvfs}}(2)|http://docs.sun.com/doc/819-2241/statvfs-2?a=view]|
[Top|#top]
h3. {anchor:CHP-SYSCALL-5} Private System Calls
Some system calls are private implementation details of Solaris subsystems that span the user-kernel boundary. As such, these system calls do not have man pages in Section 2. Examples of system calls in this category include the {{signotify}} system call, which is used as part of the implementation of POSIX.4 message queues, and the {{utssys}} system call, which is used to implement [{{fuser}}(1M)|http://docs.sun.com/doc/819-2240/fuser-1m?a=view].
[Top|#top]
h2. {anchor:CHP-SYSCALL-6} Arguments
For {{entry}} probes, the arguments ({{arg0}} .. {{arg}}_n_) are the arguments to the system call. For {{return}} probes, both {{arg0}} and {{arg1}} contain the return value. A non-zero value in the D variable {{errno}} indicates system call failure.
[Top|#top]
h2. {anchor:CHP-SYSCALL-STABILITY} Stability
The {{syscall}} provider uses DTrace's stability mechanism to describe its stabilities as shown in the following table. For more information about the stability mechanism, refer to [Chapter 39, Stability|Stability].
||Element||Name stability||Data stability||Dependency class||
|Provider|Evolving|Evolving|Common|
|Module|Private|Private|Unknown|
|Function|Unstable|Unstable|ISA|
|Name|Evolving|Evolving|Common|
|Arguments|Unstable|Unstable|ISA|
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:29:44 PM{excerpt}
h1. {anchor:CHP-SYSCALL} {{syscall}} Provider
The {{syscall}} provider makes available a probe at the entry to and return from every system call in the system. Because system calls are the primary interface between user-level applications and the operating system kernel, the {{syscall}} provider can offer tremendous insight into application behavior with respect to the system.
[Top|#top]
h2. {anchor:CHP-SYSCALL-1} Probes
{{syscall}} provides a pair of probes for each system call: an {{entry}} probe that fires before the system call is entered, and a {{return}} probe that fires after the system call has completed but before control has transferred back to user-level. For all {{syscall}} probes, the function name is set to be the name of the instrumented system call and the module name is undefined.\\
\\The names of the system calls as provided by the {{syscall}} provider may be found in the {{/etc/name_to_sysnum}} file. Often, the system call names provided by {{syscall}} correspond to names in Section 2 of the man pages. However, some probes provided by the {{syscall}} provider do not directly correspond to any documented system call. There common reasons for this discrepancy are described in this section.
[Top|#top]
h3. {anchor:CHP-SYSCALL-2} System Call Anachronisms
In some cases, the name of the system call as provided by the {{syscall}} provider is actually a reflection of an ancient implementation detail. For example, for reasons dating back to UNIX™ antiquity, the name of [{{exit}}(2)|http://docs.sun.com/doc/819-2241/exit-2?a=view] in {{/etc/name_to_sysnum}} is {{rexit}}. Similarly, the name of [{{time}}(2)|http://docs.sun.com/doc/819-2241/time-2?a=view] is {{gtime}}, and the name of both [{{execle}}(2)|http://docs.sun.com/doc/819-2241/execle-2?a=view] and [{{execve}}(2)|http://docs.sun.com/doc/819-2241/execve-2?a=view] is {{exece}}.
[Top|#top]
h3. {anchor:CHP-SYSCALL-3} Subcoded System Calls
Some system calls as presented in Section 2 are implemented as suboperations of an undocumented system call. For example, the system calls related to System V semaphores ([{{semctl}}(2)|http://docs.sun.com/doc/819-2241/semctl-2?a=view], [{{semget}}(2)|http://docs.sun.com/doc/819-2241/semget-2?a=view], [{{semids}}(2)|http://docs.sun.com/doc/819-2241/semids-2?a=view], [{{semop}}(2)|http://docs.sun.com/doc/819-2241/semop-2?a=view], and [{{semtimedop}}(2)|http://docs.sun.com/doc/819-2241/semtimedop-2?a=view]) are implemented as suboperations of a single system call, {{semsys}}. The {{semsys}} system call takes as its first argument an implementation-specific _subcode_ denoting the specific system call required: {{SEMCTL}}, {{SEMGET}}, {{SEMIDS}}, {{SEMOP}} or {{SEMTIMEDOP}}, respectively. As a result of overloading a single system call to implement multiple system calls, there is only a single pair of syscall probes for System V semaphores: {{syscall::semsys:entry}} and {{syscall::semsys:return}}.
[Top|#top]
h3. {anchor:CHP-SYSCALL-4} Large File System Calls
A 32-bit program that supports _large files_ that exceed four gigabytes in size must be able to process 64–bit file offsets. Because large files require use of large offsets, large files are manipulated through a parallel set of system interfaces, as described in [{{lf64}}(5)|http://docs.sun.com/doc/819-2252/lf64-5?a=view]. These interfaces are documented in {{lf64}}, but they do not have individual man pages. Each of these large file system call interfaces appears as its own {{syscall}} probe as shown in [Table 21–1|#TBL-SYSCALL].
h6. {anchor:TBL-SYSCALL} {{sycall}} Large File Probes
||Large File {{syscall}} Probe||System Call||
|{{creat64}}|[{{creat}}(2)|http://docs.sun.com/doc/819-2241/creat-2?a=view]|
|{{fstat64}}|[{{fstat}}(2)|http://docs.sun.com/doc/819-2241/fstat-2?a=view]|
|{{fstatvfs64}}|[{{fstatvfs}}(2)|http://docs.sun.com/doc/819-2241/fstatvfs-2?a=view]|
|{{getdents64}}|[{{getdents}}(2)|http://docs.sun.com/doc/819-2241/getdents-2?a=view]|
|{{getrlimit64}}|[{{getrlimit}}(2)|http://docs.sun.com/doc/819-2241/getrlimit-2?a=view]|
|{{lstat64}}|[{{lstat}}(2)|http://docs.sun.com/doc/819-2241/lstat-2?a=view]|
|{{mmap64}}|[{{mmap}}(2)|http://docs.sun.com/doc/819-2241/mmap-2?a=view]|
|{{open64}}|[{{open}}(2)|http://docs.sun.com/doc/819-2241/open-2?a=view]|
|{{pread64}}|[{{pread}}(2)|http://docs.sun.com/doc/819-2241/pread-2?a=view]|
|{{pwrite64}}|[{{pwrite}}(2)|http://docs.sun.com/doc/819-2241/pwrite-2?a=view]|
|{{setrlimit64}}|[{{setrlimit}}(2)|http://docs.sun.com/doc/819-2241/setrlimit-2?a=view]|
|{{stat64}}|[{{stat}}(2)|http://docs.sun.com/doc/819-2241/stat-2?a=view]|
|{{statvfs64}}|[{{statvfs}}(2)|http://docs.sun.com/doc/819-2241/statvfs-2?a=view]|
[Top|#top]
h3. {anchor:CHP-SYSCALL-5} Private System Calls
Some system calls are private implementation details of Solaris subsystems that span the user-kernel boundary. As such, these system calls do not have man pages in Section 2. Examples of system calls in this category include the {{signotify}} system call, which is used as part of the implementation of POSIX.4 message queues, and the {{utssys}} system call, which is used to implement [{{fuser}}(1M)|http://docs.sun.com/doc/819-2240/fuser-1m?a=view].
[Top|#top]
h2. {anchor:CHP-SYSCALL-6} Arguments
For {{entry}} probes, the arguments ({{arg0}} .. {{arg}}_n_) are the arguments to the system call. For {{return}} probes, both {{arg0}} and {{arg1}} contain the return value. A non-zero value in the D variable {{errno}} indicates system call failure.
[Top|#top]
h2. {anchor:CHP-SYSCALL-STABILITY} Stability
The {{syscall}} provider uses DTrace's stability mechanism to describe its stabilities as shown in the following table. For more information about the stability mechanism, refer to [Chapter 39, Stability|Stability].
||Element||Name stability||Data stability||Dependency class||
|Provider|Evolving|Evolving|Common|
|Module|Private|Private|Unknown|
|Function|Unstable|Unstable|ISA|
|Name|Evolving|Evolving|Common|
|Arguments|Unstable|Unstable|ISA|
{excerpt:hidden=true}Converted by tech dogg's sgml2wiki on Tue 20 Nov 2007 at 9:29:44 PM{excerpt}