title: sync_file_range(2)

summary: sync a file segment with disk

text:
# sync_file_range(2)

## NAME
sync_file_range - sync a file segment with disk

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#define _GNU_SOURCE         /* See feature_test_macros(7) */
#define _FILE_OFFSET_BITS 64
#include <fcntl.h>
```

```
int sync_file_range(int fd, off_t offset, off_t nbytes,
                    unsigned int flags);
```

## DESCRIPTION
sync_file_range() permits fine control when synchronizing the open file referred to by the file descriptor fd with disk.

offset is the starting byte of the file range to be synchronized. nbytes specifies the length of the range to be synchronized, in bytes; if nbytes is zero, then all bytes from offset through to the end of file are synchronized. Synchronization is in units of the system page size: offset is rounded down to a page boundary; (offset+nbytes-1) is rounded up to a page boundary.

The flags bit-mask argument can include any of the following values:

SYNC_FILE_RANGE_WAIT_BEFORE

Wait upon write-out of all pages in the specified range that have already been submitted to the device driver for write-out before performing any write.

SYNC_FILE_RANGE_WRITE

Initiate write-out of all dirty pages in the specified range which are not presently submitted write-out. Note that even this may block if you attempt to write more than request queue size.

SYNC_FILE_RANGE_WAIT_AFTER

Wait upon write-out of all pages in the range after performing any write.

Specifying flags as 0 is permitted, as a no-op.

### Warning
This system call is extremely dangerous and should not be used in portable programs. None of these operations writes out the file's metadata. Therefore, unless the application is strictly performing overwrites of already-instantiated disk blocks, there are no guarantees that the data will be available after a crash. There is no user interface to know if a write is purely an overwrite. On filesystems using copy-on-write semantics (e.g., btrfs) an overwrite of existing allocated blocks is impossible. When writing into preallocated space, many filesystems also require calls into the block allocator, which this system call does not sync out to disk. This system call does not flush disk write caches and thus does not provide any data integrity on systems with volatile disk write caches.

### Some details
SYNC_FILE_RANGE_WAIT_BEFORE and SYNC_FILE_RANGE_WAIT_AFTER will detect any I/O errors or ENOSPC conditions and will return these to the caller.

Useful combinations of the flags bits are:

SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE

Ensures that all pages in the specified range which were dirty when sync_file_range() was called are placed under write-out. This is a start-write-for-data-integrity operation.

SYNC_FILE_RANGE_WRITE

Start write-out of all dirty pages in the specified range which are not presently under write-out. This is an asynchronous flush-to-disk operation. This is not suitable for data integrity operations.

SYNC_FILE_RANGE_WAIT_BEFORE (or SYNC_FILE_RANGE_WAIT_AFTER)

Wait for completion of write-out of all pages in the specified range. This can be used after an earlier SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE operation to wait for completion of that operation, and obtain its result.

SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER

This is a write-for-data-integrity operation that will ensure that all pages in the specified range which were dirty when sync_file_range() was called are committed to disk.

## RETURN VALUE
On success, sync_file_range() returns 0; on failure -1 is returned and errno is set to indicate the error.

## ERRORS
EBADF

fd is not a valid file descriptor.

EINVAL

flags specifies an invalid bit; or offset or nbytes is invalid.

EIO

I/O error.

ENOMEM

Out of memory.

ENOSPC

Out of disk space.

ESPIPE

fd refers to something other than a regular file, a block device, or a directory.

## VERSIONS

### sync_file_range2()
Some architectures (e.g., PowerPC, ARM) need 64-bit arguments to be aligned in a suitable pair of registers. On such architectures, the call signature of sync_file_range() shown in the SYNOPSIS would force a register to be wasted as padding between the fd and offset arguments. (See syscall(2) for details.) Therefore, these architectures define a different system call that orders the arguments suitably:

```
int sync_file_range2(int fd, unsigned int flags,
                     off_t offset, off_t nbytes);
```

The behavior of this system call is otherwise exactly the same as sync_file_range().

## STANDARDS
Linux.

## HISTORY
Linux 2.6.17.

### sync_file_range2()
A system call with this signature first appeared on the ARM architecture in Linux 2.6.20, with the name arm_sync_file_range(). It was renamed in Linux 2.6.22, when the analogous system call was added for PowerPC. On architectures where glibc support is provided, glibc transparently wraps sync_file_range2() under the name sync_file_range().

## NOTES
_FILE_OFFSET_BITS should be defined to be 64 in code that takes the address of sync_file_range, if the code is intended to be portable to traditional 32-bit x86 and ARM platforms where off_t's width defaults to 32 bits.

## SEE ALSO
fdatasync(2), fsync(2), msync(2), sync(2)


syscall

package: man-pages

title: syscall(2)

summary: indirect system call

text:
# syscall(2)

## NAME
syscall - indirect system call

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/syscall.h>      /* Definition of SYS_* constants */
#include <unistd.h>
```

```
long syscall(long number, ...);
```

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

syscall():

```
    Since glibc 2.19:

        _DEFAULT_SOURCE

    Before glibc 2.19:

        _BSD_SOURCE || _SVID_SOURCE
```

## DESCRIPTION
syscall() is a small library function that invokes the system call whose assembly language interface has the specified number with the specified arguments. Employing syscall() is useful, for example, when invoking a system call that has no wrapper function in the C library.

syscall() saves CPU registers before making the system call, restores the registers upon return from the system call, and stores any error returned by the system call in errno(3).

Symbolic constants for system call numbers can be found in the header file <sys/syscall.h>.

## RETURN VALUE
The return value is defined by the system call being invoked. In general, a 0 return value indicates success. A -1 return value indicates an error, and an error number is stored in errno.

## ERRORS
ENOSYS

The requested system call number is not implemented.

Other errors are specific to the invoked system call.

## NOTES
syscall() first appeared in 4BSD.

### Architecture-specific requirements
Each architecture ABI has its own requirements on how system call arguments are passed to the kernel. For system calls that have a glibc wrapper (e.g., most system calls), glibc handles the details of copying arguments to the right registers in a manner suitable for the architecture. However, when using syscall() to make a system call, the caller might need to handle architecture-dependent details; this requirement is most commonly encountered on certain 32-bit architectures.

For example, on the ARM architecture Embedded ABI (EABI), a 64-bit value (e.g., long long) must be aligned to an even register pair. Thus, using syscall() instead of the wrapper provided by glibc, the readahead(2) system call would be invoked as follows on the ARM architecture with the EABI in little endian mode:

```
syscall(SYS_readahead, fd, 0,

        (unsigned int) (offset & 0xFFFFFFFF),

        (unsigned int) (offset >> 32),

        count);
```

Since the offset argument is 64 bits, and the first argument (fd) is passed in r0, the caller must manually split and align the 64-bit value so that it is passed in the r2/r3 register pair. That means inserting a dummy value into r1 (the second argument of 0). Care also must be taken so that the split follows endian conventions (according to the C ABI for the platform).

Similar issues can occur on MIPS with the O32 ABI, on PowerPC and parisc with the 32-bit ABI, and on Xtensa.

Note that while the parisc C ABI also uses aligned register pairs, it uses a shim layer to hide the issue from user space.

The affected system calls are fadvise64_64(2), ftruncate64(2), posix_fadvise(2), pread64(2), pwrite64(2), readahead(2), sync_file_range(2), and truncate64(2).

This does not affect syscalls that manually split and assemble 64-bit values such as _llseek(2), preadv(2), preadv2(2), pwritev(2), and pwritev2(2). Welcome to the wonderful world of historical baggage.

### Architecture calling conventions
Every architecture has its own way of invoking and passing arguments to the kernel. The details for various architectures are listed in the two tables below.

The first table lists the instruction used to transition to kernel mode (which might not be the fastest or best way to transition to the kernel, so you might have to refer to vdso(7)), the register used to indicate the system call number, the register(s) used to return the system call result, and the register used to signal an error.

Arch/ABI

Instruction

System

Ret

Ret

Error

Notes

call #

val

val2

alpha

callsys

v0

v0

a4

a3

1, 6

arc

trap0

r8

r0

-

-

arm/OABI

swi NR

-

r0

-

-

2

arm/EABI

swi 0x0

r7

r0

r1

-

arm64

svc #0

w8

x0

x1

-

blackfin

excpt 0x0

P0

R0

-

-

i386

int $0x80

eax

eax

edx

-

ia64

break 0x100000

r15

r8

r9

r10

1, 6

loongarch

syscall 0

a7

a0

-

-

m68k

trap #0

d0

d0

-

-

microblaze

brki r14,8

r12

r3

-

-

mips

syscall

v0

v0

v1

a3

1, 6

nios2

trap

r2

r2

-

r7

parisc

ble 0x100(%sr2, %r0)

r20

r28

-

-

powerpc

sc

r0

r3

-

r0

1

powerpc64

sc

r0

r3

-

cr0.SO

1

riscv

ecall

a7

a0

a1

-

s390

svc 0

r1

r2

r3

-

3

s390x

svc 0

r1

r2

r3

-

3

superh

trapa #31

r3

r0

r1

-

4, 6

sparc/32

t 0x10

g1

o0

o1

psr/csr

1, 6

sparc/64

t 0x6d

g1

o0

o1

psr/csr

1, 6

tile

swint1

R10

R00

-

R01

1

x86-64

syscall

rax

rax

rdx

-

5

x32

syscall

rax

rax

rdx

-

5

xtensa

syscall

a2

a2

-

-

Notes:

•

On a few architectures, a register is used as a boolean (0 indicating no error, and -1 indicating an error) to signal that the system call failed. The actual error value is still contained in the return register. On sparc, the carry bit (csr) in the processor status register (psr) is used instead of a full register. On powerpc64, the summary overflow bit (SO) in field 0 of the condition register (cr0) is used.

•

NR is the system call number.

•

For s390 and s390x, NR (the system call number) may be passed directly with svc NR if it is less than 256.

•

On SuperH additional trap numbers are supported for historic reasons, but trapa#31 is the recommended "unified" ABI.

•

The x32 ABI shares syscall table with x86-64 ABI, but there are some nuances:

•

In order to indicate that a system call is called under the x32 ABI, an additional bit, __X32_SYSCALL_BIT, is bitwise ORed with the system call number. The ABI used by a process affects some process behaviors, including signal handling or system call restarting.

•

Since x32 has different sizes for long and pointer types, layouts of some (but not all; struct timeval or struct rlimit are 64-bit, for example) structures are different. In order to handle this, additional system calls are added to the system call table, starting from number 512 (without the __X32_SYSCALL_BIT). For example, __NR_readv is defined as 19 for the x86-64 ABI and as __X32_SYSCALL_BIT | 515 for the x32 ABI. Most of these additional system calls are actually identical to the system calls used for providing i386 compat. There are some notable exceptions, however, such as preadv2(2), which uses struct iovec entities with 4-byte pointers and sizes ("compat_iovec" in kernel terms), but passes an 8-byte pos argument in a single register and not two, as is done in every other ABI.

•

Some architectures (namely, Alpha, IA-64, MIPS, SuperH, sparc/32, and sparc/64) use an additional register ("Retval2" in the above table) to pass back a second return value from the pipe(2) system call; Alpha uses this technique in the architecture-specific getxpid(2), getxuid(2), and getxgid(2) system calls as well. Other architectures do not use the second return value register in the system call interface, even if it is defined in the System V ABI.

The second table shows the registers used to pass the system call arguments.

Arch/ABI

arg1

arg2

arg3

arg4

arg5

arg6

arg7

Notes

alpha

a0

a1

a2

a3

a4

a5

-

arc

r0

r1

r2

r3

r4

r5

-

arm/OABI

r0

r1

r2

r3

r4

r5

r6

arm/EABI

r0

r1

r2

r3

r4

r5

r6

arm64

x0

x1

x2

x3

x4

x5

-

blackfin

R0

R1

R2

R3

R4

R5

-

i386

ebx

ecx

edx

esi

edi

ebp

-

ia64

out0

out1

out2

out3

out4

out5

-

loongarch

a0

a1

a2

a3

a4

a5

a6

m68k

d1

d2

d3

d4

d5

a0

-

microblaze

r5

r6

r7

r8

r9

r10

-

mips/o32

a0

a1

a2

a3

-

-

-

1

mips/n32,64

a0

a1

a2

a3

a4

a5

-

nios2

r4

r5

r6

r7

r8

r9

-

parisc

r26

r25

r24

r23

r22

r21

-

powerpc

r3

r4

r5

r6

r7

r8

r9

powerpc64

r3

r4

r5

r6

r7

r8

-

riscv

a0

a1

a2

a3

a4

a5

-

s390

r2

r3

r4

r5

r6

r7

-

s390x

r2

r3

r4

r5

r6

r7

-

superh

r4

r5

r6

r7

r0

r1

r2

sparc/32

o0

o1

o2

o3

o4

o5

-

sparc/64

o0

o1

o2

o3

o4

o5

-

tile

R00

R01

R02

R03

R04

R05

-

x86-64

rdi

rsi

rdx

r10

r8

r9

-

x32

rdi

rsi

rdx

r10

r8

r9

-

xtensa

a6

a3

a4

a5

a8

a9

-

Notes:

•

The mips/o32 system call convention passes arguments 5 through 8 on the user stack.

Note that these tables don't cover the entire calling convention—some architectures may indiscriminately clobber other registers not listed here.

## EXAMPLES

```
#define _GNU_SOURCE
#include <signal.h>
#include <sys/syscall.h>
#include <unistd.h>
int
main(void)
{

    pid_t tid;

    tid = syscall(SYS_gettid);

    syscall(SYS_tgkill, getpid(), tid, SIGHUP);
}
```

## SEE ALSO
_syscall(2), intro(2), syscalls(2), errno(3), vdso(7)

branch: sisyphus


syscalls

title: syscalls(2)

summary: Linux system calls

text:
# syscalls(2)

## NAME
syscalls - Linux system calls

## SYNOPSIS

```
Linux system calls.
```

## DESCRIPTION
The system call is the fundamental interface between an application and the Linux kernel.

### System calls and library wrapper functions
System calls are generally not invoked directly, but rather via wrapper functions in glibc (or perhaps some other library). For details of direct invocation of a system call, see intro(2). Often, but not always, the name of the wrapper function is the same as the name of the system call that it invokes. For example, glibc contains a function chdir() which invokes the underlying "chdir" system call.

Often the glibc wrapper function is quite thin, doing little work other than copying arguments to the right registers before invoking the system call, and then setting errno appropriately after the system call has returned. (These are the same steps that are performed by syscall(2), which can be used to invoke system calls for which no wrapper function is provided.) Note: system calls indicate a failure by returning a negative error number to the caller on architectures without a separate error register/flag, as noted in syscall(2); when this happens, the wrapper function negates the returned error number (to make it positive), copies it to errno, and returns -1 to the caller of the wrapper.

Sometimes, however, the wrapper function does some extra work before invoking the system call. For example, nowadays there are (for reasons described below) two related system calls, truncate(2) and truncate64(2), and the glibc truncate() wrapper function checks which of those system calls are provided by the kernel and determines which should be employed.

### System call list
Below is a list of the Linux system calls. In the list, the Kernel column indicates the kernel version for those system calls that were new in Linux 2.2, or have appeared since that kernel version. Note the following points:

•

Where no kernel version is indicated, the system call appeared in Linux 1.0 or earlier.

•

Where a system call is marked "1.2" this means the system call probably appeared in a Linux 1.1.x kernel version, and first appeared in a stable kernel with 1.2. (Development of the 1.2 kernel was initiated from a branch of kernel 1.0.6 via the 1.1.x unstable kernel series.)

•

Where a system call is marked "2.0" this means the system call probably appeared in a Linux 1.3.x kernel version, and first appeared in a stable kernel with Linux 2.0. (Development of the Linux 2.0 kernel was initiated from a branch of Linux 1.2.x, somewhere around Linux 1.2.10, via the Linux 1.3.x unstable kernel series.)

•

Where a system call is marked "2.2" this means the system call probably appeared in a Linux 2.1.x kernel version, and first appeared in a stable kernel with Linux 2.2.0. (Development of the Linux 2.2 kernel was initiated from a branch of kernel Linux 2.0.21 via the Linux 2.1.x unstable kernel series.)

•

Where a system call is marked "2.4" this means the system call probably appeared in a Linux 2.3.x kernel version, and first appeared in a stable kernel with Linux 2.4.0. (Development of the Linux 2.4 kernel was initiated from a branch of Linux 2.2.8 via the Linux 2.3.x unstable kernel series.)

•

Where a system call is marked "2.6" this means the system call probably appeared in a Linux 2.5.x kernel version, and first appeared in a stable kernel with Linux 2.6.0. (Development of Linux 2.6 was initiated from a branch of Linux 2.4.15 via the Linux 2.5.x unstable kernel series.)

•

Starting with Linux 2.6.0, the development model changed, and new system calls may appear in each Linux 2.6.x release. In this case, the exact version number where the system call appeared is shown. This convention continues with the Linux 3.x kernel series, which followed on from Linux 2.6.39; and the Linux 4.x kernel series, which followed on from Linux 3.19; and the Linux 5.x kernel series, which followed on from Linux 4.20.

•

In some cases, a system call was added to a stable kernel series after it branched from the previous stable kernel series, and then backported into the earlier stable kernel series. For example some system calls that appeared in Linux 2.6.x were also backported into a Linux 2.4.x release after Linux 2.4.15. When this is so, the version where the system call appeared in both of the major kernel series is listed.

The list of system calls that are available as at Linux 5.14 (or in a few cases only on older kernels) is as follows:

System call

Kernel

Notes

_llseek(2)

1.2

_newselect(2)

2.0

_sysctl(2)

2.0

Removed in 5.5

accept(2)

2.0

See notes on socketcall(2)

accept4(2)

2.6.28

access(2)

1.0

acct(2)

1.0

add_key(2)

2.6.10

adjtimex(2)

1.0

alarm(2)

1.0

alloc_hugepages(2)

2.5.36

Removed in 2.5.44

arc_gettls(2)

3.9

ARC only

arc_settls(2)

3.9

ARC only

arc_usr_cmpxchg(2)

4.9

ARC only

arch_prctl(2)

2.6

x86_64, x86 since 4.12

atomic_barrier(2)

2.6.34

m68k only

atomic_cmpxchg_32(2)

2.6.34

m68k only

bdflush(2)

1.2

Deprecated (does nothing) since 2.6

bind(2)

2.0

See notes on socketcall(2)

bpf(2)

3.18

brk(2)

1.0

breakpoint(2)

2.2

ARM OABI only, defined with __ARM_NR prefix

cacheflush(2)

1.2

Not on x86

capget(2)

2.2

capset(2)

2.2

chdir(2)

1.0

chmod(2)

1.0

chown(2)

2.2

See chown(2) for version details

chown32(2)

2.4

chroot(2)

1.0

clock_adjtime(2)

2.6.39

clock_getres(2)

2.6

clock_gettime(2)

2.6

clock_nanosleep(2)

2.6

clock_settime(2)

2.6

clone2(2)

2.4

IA-64 only

clone(2)

1.0

clone3(2)

5.3

close(2)

1.0

close_range(2)

5.9

connect(2)

2.0

See notes on socketcall(2)

copy_file_range(2)

4.5

creat(2)

1.0

create_module(2)

1.0

Removed in 2.6

delete_module(2)

1.0

dup(2)

1.0

dup2(2)

1.0

dup3(2)

2.6.27

epoll_create(2)

2.6

epoll_create1(2)

2.6.27

epoll_ctl(2)

2.6

epoll_pwait(2)

2.6.19

epoll_pwait2(2)

5.11

epoll_wait(2)

2.6

eventfd(2)

2.6.22

eventfd2(2)

2.6.27

execv(2)

2.0

SPARC/SPARC64 only, for compatibility with SunOS

execve(2)

1.0

execveat(2)

3.19

exit(2)

1.0

exit_group(2)

2.6

faccessat(2)

2.6.16

faccessat2(2)

5.8

fadvise64(2)

2.6

fadvise64_64(2)

2.6

fallocate(2)

2.6.23

fanotify_init(2)

2.6.37

fanotify_mark(2)

2.6.37

fchdir(2)

1.0

fchmod(2)

1.0

fchmodat(2)

2.6.16

fchown(2)

1.0

fchown32(2)

2.4

fchownat(2)

2.6.16

fcntl(2)

1.0

fcntl64(2)

2.4

fdatasync(2)

2.0

fgetxattr(2)

2.6; 2.4.18

finit_module(2)

3.8

flistxattr(2)

2.6; 2.4.18

flock(2)

2.0

fork(2)

1.0

free_hugepages(2)

2.5.36

Removed in 2.5.44

fremovexattr(2)

2.6; 2.4.18

fsconfig(2)

5.2

fsetxattr(2)

2.6; 2.4.18

fsmount(2)

5.2

fsopen(2)

5.2

fspick(2)

5.2

fstat(2)

1.0

fstat64(2)

2.4

fstatat64(2)

2.6.16

fstatfs(2)

1.0

fstatfs64(2)

2.6

fsync(2)

1.0

ftruncate(2)

1.0

ftruncate64(2)

2.4

futex(2)

2.6

futimesat(2)

2.6.16

get_kernel_syms(2)

1.0

Removed in 2.6

get_mempolicy(2)

2.6.6

get_robust_list(2)

2.6.17

get_thread_area(2)

2.6

get_tls(2)

4.15

ARM OABI only, has __ARM_NR prefix

getcpu(2)

2.6.19

getcwd(2)

2.2

getdents(2)

2.0

getdents64(2)

2.4

getdomainname(2)

2.2

SPARC, SPARC64; available as osf_getdomainname(2) on Alpha since Linux 2.0

getdtablesize(2)

2.0

SPARC (removed in 2.6.26), available on Alpha as osf_getdtablesize(2)

getegid(2)

1.0

getegid32(2)

2.4

geteuid(2)

1.0

geteuid32(2)

2.4

getgid(2)

1.0

getgid32(2)

2.4

getgroups(2)

1.0

getgroups32(2)

2.4

gethostname(2)

2.0

Alpha, was available on SPARC up to Linux 2.6.26

getitimer(2)

1.0

getpeername(2)

2.0

See notes on socketcall(2)

getpagesize(2)

2.0

Not on x86

getpgid(2)

1.0

getpgrp(2)

1.0

getpid(2)

1.0

getppid(2)

1.0

getpriority(2)

1.0

getrandom(2)

3.17

getresgid(2)

2.2

getresgid32(2)

2.4

getresuid(2)

2.2

getresuid32(2)

2.4

getrlimit(2)

1.0

getrusage(2)

1.0

getsid(2)

2.0

getsockname(2)

2.0

See notes on socketcall(2)

getsockopt(2)

2.0

See notes on socketcall(2)

gettid(2)

2.4.11

gettimeofday(2)

1.0

getuid(2)

1.0

getuid32(2)

2.4

getunwind(2)

2.4.8

IA-64 only; deprecated

getxattr(2)

2.6; 2.4.18

getxgid(2)

2.0

Alpha only; see NOTES

getxpid(2)

2.0

Alpha only; see NOTES

getxuid(2)

2.0

Alpha only; see NOTES

init_module(2)

1.0

inotify_add_watch(2)

2.6.13

inotify_init(2)

2.6.13

inotify_init1(2)

2.6.27

inotify_rm_watch(2)

2.6.13

io_cancel(2)

2.6

io_destroy(2)

2.6

io_getevents(2)

2.6

io_pgetevents(2)

4.18

io_setup(2)

2.6

io_submit(2)

2.6

io_uring_enter(2)

5.1

io_uring_register(2)

5.1

io_uring_setup(2)

5.1

ioctl(2)

1.0

ioperm(2)

1.0

iopl(2)

1.0

ioprio_get(2)

2.6.13

ioprio_set(2)

2.6.13

ipc(2)

1.0

kcmp(2)

3.5

kern_features(2)

3.7

SPARC64 only

kexec_file_load(2)

3.17

kexec_load(2)

2.6.13

keyctl(2)

2.6.10

kill(2)

1.0

landlock_add_rule(2)

5.13

landlock_create_ruleset(2)

5.13

landlock_restrict_self(2)

5.13

lchown(2)

1.0

See chown(2) for version details

lchown32(2)

2.4

lgetxattr(2)

2.6; 2.4.18

link(2)

1.0

linkat(2)

2.6.16

listen(2)

2.0

See notes on socketcall(2)

listxattr(2)

2.6; 2.4.18

llistxattr(2)

2.6; 2.4.18

lookup_dcookie(2)

2.6

lremovexattr(2)

2.6; 2.4.18

lseek(2)

1.0

lsetxattr(2)

2.6; 2.4.18

lstat(2)

1.0

lstat64(2)

2.4

madvise(2)

2.4

mbind(2)

2.6.6

memory_ordering(2)

2.2

SPARC64 only

membarrier(2)

3.17

memfd_create(2)

3.17

memfd_secret(2)

5.14

migrate_pages(2)

2.6.16

mincore(2)

2.4

mkdir(2)

1.0

mkdirat(2)

2.6.16

mknod(2)

1.0

mknodat(2)

2.6.16

mlock(2)

2.0

mlock2(2)

4.4

mlockall(2)

2.0

mmap(2)

1.0

mmap2(2)

2.4

modify_ldt(2)

1.0

mount(2)

1.0

move_mount(2)

5.2

move_pages(2)

2.6.18

mprotect(2)

1.0

mq_getsetattr(2)

2.6.6

mq_notify(2)

2.6.6

mq_open(2)

2.6.6

mq_timedreceive(2)

2.6.6

mq_timedsend(2)

2.6.6

mq_unlink(2)

2.6.6

mremap(2)

2.0

msgctl(2)

2.0

See notes on ipc(2)

msgget(2)

2.0

See notes on ipc(2)

msgrcv(2)

2.0

See notes on ipc(2)

msgsnd(2)

2.0

See notes on ipc(2)

msync(2)

2.0

munlock(2)

2.0

munlockall(2)

2.0

munmap(2)

1.0

name_to_handle_at(2)

2.6.39

nanosleep(2)

2.0

newfstatat(2)

2.6.16

See stat(2)

nfsservctl(2)

2.2

Removed in 3.1

nice(2)

1.0

old_adjtimex(2)

2.0

Alpha only; see NOTES

old_getrlimit(2)

2.4

Old variant of getrlimit(2) that used a different value for RLIM_INFINITY

oldfstat(2)

1.0

oldlstat(2)

1.0

oldolduname(2)

1.0

oldstat(2)

1.0

oldumount(2)

2.4.116

Name of the old umount(2) syscall on Alpha

olduname(2)

1.0

open(2)

1.0

open_by_handle_at(2)

2.6.39

open_tree(2)

5.2

openat(2)

2.6.16

openat2(2)

5.6

or1k_atomic(2)

3.1

OpenRISC 1000 only

pause(2)

1.0

pciconfig_iobase(2)

2.2.15; 2.4

Not on x86

pciconfig_read(2)

2.0.26; 2.2

Not on x86

pciconfig_write(2)

2.0.26; 2.2

Not on x86

perf_event_open(2)

2.6.31

Was perf_counter_open() in 2.6.31; renamed in 2.6.32

personality(2)

1.2

perfctr(2)

2.2

SPARC only; removed in 2.6.34

perfmonctl(2)

2.4

IA-64 only; removed in 5.10

pidfd_getfd(2)

5.6

pidfd_send_signal(2)

5.1

pidfd_open(2)

5.3

pipe(2)

1.0

pipe2(2)

2.6.27

pivot_root(2)

2.4

pkey_alloc(2)

4.8

pkey_free(2)

4.8

pkey_mprotect(2)

4.8

poll(2)

2.0.36; 2.2

ppoll(2)

2.6.16

prctl(2)

2.2

pread64(2)

Added as "pread" in 2.2; renamed "pread64" in 2.6

preadv(2)

2.6.30

preadv2(2)

4.6

prlimit64(2)

2.6.36

process_madvise(2)

5.10

process_vm_readv(2)

3.2

process_vm_writev(2)

3.2

pselect6(2)

2.6.16

ptrace(2)

1.0

pwrite64(2)

Added as "pwrite" in 2.2; renamed "pwrite64" in 2.6

pwritev(2)

2.6.30

pwritev2(2)

4.6

query_module(2)

2.2

Removed in 2.6

quotactl(2)

1.0

quotactl_fd(2)

5.14

read(2)

1.0

readahead(2)

2.4.13

readdir(2)

1.0

readlink(2)

1.0

readlinkat(2)

2.6.16

readv(2)

2.0

reboot(2)

1.0

recv(2)

2.0

See notes on socketcall(2)

recvfrom(2)

2.0

See notes on socketcall(2)

recvmsg(2)

2.0

See notes on socketcall(2)

recvmmsg(2)

2.6.33

remap_file_pages(2)

2.6

Deprecated since 3.16

removexattr(2)

2.6; 2.4.18

rename(2)

1.0

renameat(2)

2.6.16

renameat2(2)

3.15

request_key(2)

2.6.10

restart_syscall(2)

2.6

riscv_flush_icache(2)

4.15

RISC-V only

rmdir(2)

1.0

rseq(2)

4.18

rt_sigaction(2)

2.2

rt_sigpending(2)

2.2

rt_sigprocmask(2)

2.2

rt_sigqueueinfo(2)

2.2

rt_sigreturn(2)

2.2

rt_sigsuspend(2)

2.2

rt_sigtimedwait(2)

2.2

rt_tgsigqueueinfo(2)

2.6.31

rtas(2)

2.6.2

PowerPC/PowerPC64 only

s390_runtime_instr(2)

3.7

s390 only

s390_pci_mmio_read(2)

3.19

s390 only

s390_pci_mmio_write(2)

3.19

s390 only

s390_sthyi(2)

4.15

s390 only

s390_guarded_storage(2)

4.12

s390 only

sched_get_affinity(2)

2.6

Name of sched_getaffinity (2) on SPARC and SPARC64

sched_get_priority_max(2)

2.0

sched_get_priority_min(2)

2.0

sched_getaffinity(2)

2.6

sched_getattr(2)

3.14

sched_getparam(2)

2.0

sched_getscheduler(2)

2.0

sched_rr_get_interval(2)

2.0

sched_set_affinity(2)

2.6

Name of sched_setaffinity (2) on SPARC and SPARC64

sched_setaffinity(2)

2.6

sched_setattr(2)

3.14

sched_setparam(2)

2.0

sched_setscheduler(2)

2.0

sched_yield(2)

2.0

seccomp(2)

3.17

select(2)

1.0

semctl(2)

2.0

See notes on ipc(2)

semget(2)

2.0

See notes on ipc(2)

semop(2)

2.0

See notes on ipc(2)

semtimedop(2)

2.6; 2.4.22

send(2)

2.0

See notes on socketcall(2)

sendfile(2)

2.2

sendfile64(2)

2.6; 2.4.19

sendmmsg(2)

3.0

sendmsg(2)

2.0

See notes on socketcall(2)

sendto(2)

2.0

See notes on socketcall(2)

set_mempolicy(2)

2.6.6

set_robust_list(2)

2.6.17

set_thread_area(2)

2.6

set_tid_address(2)

2.6

set_tls(2)

2.6.11

ARM OABI/EABI only (constant has __ARM_NR prefix)

setdomainname(2)

1.0

setfsgid(2)

1.2

setfsgid32(2)

2.4

setfsuid(2)

1.2

setfsuid32(2)

2.4

setgid(2)

1.0

setgid32(2)

2.4

setgroups(2)

1.0

setgroups32(2)

2.4

sethae(2)

2.0

Alpha only; see NOTES

sethostname(2)

1.0

setitimer(2)

1.0

setns(2)

3.0

setpgid(2)

1.0

setpgrp(2)

2.0

Alternative name for setpgid(2) on Alpha

setpriority(2)

1.0

setregid(2)

1.0

setregid32(2)

2.4

setresgid(2)

2.2

setresgid32(2)

2.4

setresuid(2)

2.2

setresuid32(2)

2.4

setreuid(2)

1.0

setreuid32(2)

2.4

setrlimit(2)

1.0

setsid(2)

1.0

setsockopt(2)

2.0

See notes on socketcall(2)

settimeofday(2)

1.0

setuid(2)

1.0

setuid32(2)

2.4

setup(2)

1.0

Removed in 2.2

setxattr(2)

2.6; 2.4.18

sgetmask(2)

1.0

shmat(2)

2.0

See notes on ipc(2)

shmctl(2)

2.0

See notes on ipc(2)

shmdt(2)

2.0

See notes on ipc(2)

shmget(2)

2.0

See notes on ipc(2)

shutdown(2)

2.0

See notes on socketcall(2)

sigaction(2)

1.0

sigaltstack(2)

2.2

signal(2)

1.0

signalfd(2)

2.6.22

signalfd4(2)

2.6.27

sigpending(2)

1.0

sigprocmask(2)

1.0

sigreturn(2)

1.0

sigsuspend(2)

1.0

socket(2)

2.0

See notes on socketcall(2)

socketcall(2)

1.0

socketpair(2)

2.0

See notes on socketcall(2)

spill(2)

2.6.13

Xtensa only

splice(2)

2.6.17

spu_create(2)

2.6.16

PowerPC/PowerPC64 only

spu_run(2)

2.6.16

PowerPC/PowerPC64 only

ssetmask(2)

1.0

stat(2)

1.0

stat64(2)

2.4

statfs(2)

1.0

statfs64(2)

2.6

statx(2)

4.11

stime(2)

1.0

subpage_prot(2)

2.6.25

PowerPC/PowerPC64 only

swapcontext(2)

2.6.3

PowerPC/PowerPC64 only

switch_endian(2)

4.1

PowerPC64 only

swapoff(2)

1.0

swapon(2)

1.0

symlink(2)

1.0

symlinkat(2)

2.6.16

sync(2)

1.0

sync_file_range(2)

2.6.17

sync_file_range2(2)

2.6.22

syncfs(2)

2.6.39

sys_debug_setcontext(2)

2.6.11

PowerPC only

syscall(2)

1.0

Still available on ARM OABI and MIPS O32 ABI

sysfs(2)

1.2

sysinfo(2)

1.0

syslog(2)

1.0

sysmips(2)

2.6.0

MIPS only

tee(2)

2.6.17

tgkill(2)

2.6

time(2)

1.0

timer_create(2)

2.6

timer_delete(2)

2.6

timer_getoverrun(2)

2.6

timer_gettime(2)

2.6

timer_settime(2)

2.6

timerfd_create(2)

2.6.25

timerfd_gettime(2)

2.6.25

timerfd_settime(2)

2.6.25

times(2)

1.0

tkill(2)

2.6; 2.4.22

truncate(2)

1.0

truncate64(2)

2.4

ugetrlimit(2)

2.4

umask(2)

1.0

umount(2)

1.0

umount2(2)

2.2

uname(2)

1.0

unlink(2)

1.0

unlinkat(2)

2.6.16

unshare(2)

2.6.16

uselib(2)

1.0

ustat(2)

1.0

userfaultfd(2)

4.3

usr26(2)

2.4.8.1

ARM OABI only

usr32(2)

2.4.8.1

ARM OABI only

utime(2)

1.0

utimensat(2)

2.6.22

utimes(2)

2.2

utrap_install(2)

2.2

SPARC64 only

vfork(2)

2.2

vhangup(2)

1.0

vm86old(2)

1.0

Was "vm86"; renamed in 2.0.28/2.2

vm86(2)

2.0.28; 2.2

vmsplice(2)

2.6.17

wait4(2)

1.0

waitid(2)

2.6.10

waitpid(2)

1.0

write(2)

1.0

writev(2)

2.0

xtensa(2)

2.6.13

Xtensa only

On many platforms, including x86-32, socket calls are all multiplexed (via glibc wrapper functions) through socketcall(2) and similarly System V IPC calls are multiplexed through ipc(2).

Although slots are reserved for them in the system call table, the following system calls are not implemented in the standard kernel: afs_syscall(2), break(2), ftime(2), getpmsg(2), gtty(2), idle(2), lock(2), madvise1(2), mpx(2), phys(2), prof(2), profil(2), putpmsg(2), security(2), stty(2), tuxcall(2), ulimit(2), and vserver(2) (see also unimplemented(2)). However, ftime(3), profil(3), and ulimit(3) exist as library routines. The slot for phys(2) is in use since Linux 2.1.116 for umount(2); phys(2) will never be implemented. The getpmsg(2) and putpmsg(2) calls are for kernels patched to support STREAMS, and may never be in the standard kernel.

There was briefly set_zone_reclaim(2), added in Linux 2.6.13, and removed in Linux 2.6.16; this system call was never available to user space.

### System calls on removed ports
Some system calls only ever existed on Linux architectures that have since been removed from the kernel:

AVR32 (port removed in Linux 4.12)

•

pread(2)

•

pwrite(2)

Blackfin (port removed in Linux 4.17)

•

bfin_spinlock(2) (added in Linux 2.6.22)

•

dma_memcpy(2) (added in Linux 2.6.22)

•

pread(2) (added in Linux 2.6.22)

•

pwrite(2) (added in Linux 2.6.22)

•

sram_alloc(2) (added in Linux 2.6.22)

•

sram_free(2) (added in Linux 2.6.22)

Metag (port removed in Linux 4.17)

•

metag_get_tls(2) (add in Linux 3.9)

•

metag_set_fpu_flags(2) (add in Linux 3.9)

•

metag_set_tls(2) (add in Linux 3.9)

•

metag_setglobalbit(2) (add in Linux 3.9)

Tile (port removed in Linux 4.17)

•

cmpxchg_badaddr(2) (added in Linux 2.6.36)

## NOTES
Roughly speaking, the code belonging to the system call with number __NR_xxx defined in /usr/include/asm/unistd.h can be found in the Linux kernel source in the routine sys_xxx(). There are many exceptions, however, mostly because older system calls were superseded by newer ones, and this has been treated somewhat unsystematically. On platforms with proprietary operating-system emulation, such as sparc, sparc64, and alpha, there are many additional system calls; mips64 also contains a full set of 32-bit system calls.

Over time, changes to the interfaces of some system calls have been necessary. One reason for such changes was the need to increase the size of structures or scalar values passed to the system call. Because of these changes, certain architectures (notably, longstanding 32-bit architectures such as i386) now have various groups of related system calls (e.g., truncate(2) and truncate64(2)) which perform similar tasks, but which vary in details such as the size of their arguments. (As noted earlier, applications are generally unaware of this: the glibc wrapper functions do some work to ensure that the right system call is invoked, and that ABI compatibility is preserved for old binaries.) Examples of systems calls that exist in multiple versions are the following:

•

By now there are three different versions of stat(2): sys_stat() (slot __NR_oldstat), sys_newstat() (slot __NR_stat), and sys_stat64() (slot __NR_stat64), with the last being the most current. A similar story applies for lstat(2) and fstat(2).

•

Similarly, the defines __NR_oldolduname, __NR_olduname, and __NR_uname refer to the routines sys_olduname(), sys_uname(), and sys_newuname().

•

In Linux 2.0, a new version of vm86(2) appeared, with the old and the new kernel routines being named sys_vm86old() and sys_vm86().

•

In Linux 2.4, a new version of getrlimit(2) appeared, with the old and the new kernel routines being named sys_old_getrlimit() (slot __NR_getrlimit) and sys_getrlimit() (slot __NR_ugetrlimit).

•

Linux 2.4 increased the size of user and group IDs from 16 to 32 bits. To support this change, a range of system calls were added (e.g., chown32(2), getuid32(2), getgroups32(2), setresuid32(2)), superseding earlier calls of the same name without the "32" suffix.

•

Linux 2.4 added support for applications on 32-bit architectures to access large files (i.e., files for which the sizes and file offsets can't be represented in 32 bits.) To support this change, replacements were required for system calls that deal with file offsets and sizes. Thus the following system calls were added: fcntl64(2), getdents64(2), stat64(2), statfs64(2), truncate64(2), and their analogs that work with file descriptors or symbolic links. These system calls supersede the older system calls which, except in the case of the "stat" calls, have the same name without the "64" suffix.

On newer platforms that only have 64-bit file access and 32-bit UIDs/GIDs (e.g., alpha, ia64, s390x, x86-64), there is just a single version of the UID/GID and file access system calls. On platforms (typically, 32-bit platforms) where the *64 and *32 calls exist, the other versions are obsolete.

•

The rt_sig* calls were added in Linux 2.2 to support the addition of real-time signals (see signal(7)). These system calls supersede the older system calls of the same name without the "rt_" prefix.

•

The select(2) and mmap(2) system calls use five or more arguments, which caused problems in the way argument passing on the i386 used to be set up. Thus, while other architectures have sys_select() and sys_mmap() corresponding to __NR_select and __NR_mmap, on i386 one finds old_select() and old_mmap() (routines that use a pointer to an argument block) instead. These days passing five arguments is not a problem any more, and there is a __NR__newselect that corresponds directly to sys_select() and similarly __NR_mmap2. s390x is the only 64-bit architecture that has old_mmap().

### Architecture-specific details: Alpha
getxgid(2)

returns a pair of GID and effective GID via registers r0 and r20; it is provided instead of getgid(2) and getegid(2).

getxpid(2)

returns a pair of PID and parent PID via registers r0 and r20; it is provided instead of getpid(2) and getppid(2).

old_adjtimex(2)

is a variant of adjtimex(2) that uses struct timeval32, for compatibility with OSF/1.

getxuid(2)

returns a pair of GID and effective GID via registers r0 and r20; it is provided instead of getuid(2) and geteuid(2).

sethae(2)

is used for configuring the Host Address Extension register on low-cost Alphas in order to access address space beyond first 27 bits.

## SEE ALSO
ausyscall(1), intro(2), syscall(2), unimplemented(2), errno(3), libc(7), vdso(7)


sysctl

title: sysctl(2)

summary: read/write system parameters

text:
# sysctl(2)

## NAME
sysctl - read/write system parameters

## SYNOPSIS

```
#include <unistd.h>
#include <linux/sysctl.h>
```

```
[[deprecated]] int _sysctl(struct __sysctl_args *args);
```

## DESCRIPTION
This system call no longer exists on current kernels! See NOTES.

The _sysctl() call reads and/or writes kernel parameters. For example, the hostname, or the maximum number of open files. The argument has the form

```
struct __sysctl_args {

    int    *name;    /* integer vector describing variable */

    int     nlen;    /* length of this vector */

    void   *oldval;  /* 0 or address where to store old value */

    size_t *oldlenp; /* available room for old value,

                        overwritten by actual size of old value */

    void   *newval;  /* 0 or address of new value */

    size_t  newlen;  /* size of new value */
};
```

This call does a search in a tree structure, possibly resembling a directory tree under /proc/sys, and if the requested item is found calls some appropriate routine to read or modify the value.

## RETURN VALUE
Upon successful completion, _sysctl() returns 0. Otherwise, a value of -1 is returned and errno is set to indicate the error.

## ERRORS
EACCES, EPERM

No search permission for one of the encountered "directories", or no read permission where oldval was nonzero, or no write permission where newval was nonzero.

EFAULT

The invocation asked for the previous value by setting oldval non-NULL, but allowed zero room in oldlenp.

ENOTDIR

name was not found.

## STANDARDS
Linux.

## HISTORY
Linux 1.3.57. Removed in Linux 5.5, glibc 2.32.

It originated in 4.4BSD. Only Linux has the /proc/sys mirror, and the object naming schemes differ between Linux and 4.4BSD, but the declaration of the sysctl() function is the same in both.

## NOTES
Use of this system call was long discouraged: since Linux 2.6.24, uses of this system call result in warnings in the kernel log, and in Linux 5.5, the system call was finally removed. Use the /proc/sys interface instead.

Note that on older kernels where this system call still exists, it is available only if the kernel was configured with the CONFIG_SYSCTL_SYSCALL option. Furthermore, glibc does not provide a wrapper for this system call, necessitating the use of syscall(2).

## BUGS
The object names vary between kernel versions, making this system call worthless for applications.

Not all available objects are properly documented.

It is not yet possible to change operating system by writing to /proc/sys/kernel/ostype.

## EXAMPLES

```
#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/syscall.h>
#include <unistd.h>
#include <linux/sysctl.h>
#define ARRAY_SIZE(arr)  (sizeof(arr) / sizeof((arr)[0]))
int _sysctl(struct __sysctl_args *args);
#define OSNAMESZ 100
int
main(void)
{

    int                   name[] = { CTL_KERN, KERN_OSTYPE };

    char                  osname[OSNAMESZ];

    size_t                osnamelth;

    struct __sysctl_args  args;

    memset(&args, 0, sizeof(args));

    args.name = name;

    args.nlen = ARRAY_SIZE(name);

    args.oldval = osname;

    args.oldlenp = &osnamelth;

    osnamelth = sizeof(osname);

    if (syscall(SYS__sysctl, &args) == -1) {

        perror("_sysctl");

        exit(EXIT_FAILURE);

    }

    printf("This machine is running %*s\n", (int) osnamelth, osname);

    exit(EXIT_SUCCESS);
}
```

## SEE ALSO
proc(5)


sysfs

title: sysfs(2)

summary: get filesystem type information

text:
# sysfs(2)

## NAME
sysfs - get filesystem type information

## SYNOPSIS

```
[[deprecated]] int sysfs(int option, const char *fsname);
[[deprecated]] int sysfs(int option, unsigned int fs_index, char *buf);
[[deprecated]] int sysfs(int option);
```

## DESCRIPTION
Note: if you are looking for information about the sysfs filesystem that is normally mounted at /sys, see sysfs(5).

The (obsolete) sysfs() system call returns information about the filesystem types currently present in the kernel. The specific form of the sysfs() call and the information returned depends on the option in effect:

1

Translate the filesystem identifier string fsname into a filesystem type index.

2

Translate the filesystem type index fs_index into a null-terminated filesystem identifier string. This string will be written to the buffer pointed to by buf. Make sure that buf has enough space to accept the string.

3

Return the total number of filesystem types currently present in the kernel.

The numbering of the filesystem type indexes begins with zero.

## RETURN VALUE
On success, sysfs() returns the filesystem index for option 1, zero for option 2, and the number of currently configured filesystems for option 3. On error, -1 is returned, and errno is set to indicate the error.

## ERRORS
EFAULT

Either fsname or buf is outside your accessible address space.

EINVAL

fsname is not a valid filesystem type identifier; fs_index is out-of-bounds; option is invalid.

## STANDARDS
None.

## HISTORY
SVr4.

This System-V derived system call is obsolete; don't use it. On systems with /proc, the same information can be obtained via /proc; use that interface instead.

## BUGS
There is no libc or glibc support. There is no way to guess how large buf should be.

## SEE ALSO
proc(5), sysfs(5)


sysinfo

title: sysinfo(2)

summary: return system information

text:
# sysinfo(2)

## NAME
sysinfo - return system information

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/sysinfo.h>
```

```
int sysinfo(struct sysinfo *info);
```

## DESCRIPTION
sysinfo() returns certain statistics on memory and swap usage, as well as the load average.

Until Linux 2.3.16, sysinfo() returned information in the following structure:

```
struct sysinfo {

    long uptime;             /* Seconds since boot */

    unsigned long loads[3];  /* 1, 5, and 15 minute load averages */

    unsigned long totalram;  /* Total usable main memory size */

    unsigned long freeram;   /* Available memory size */

    unsigned long sharedram; /* Amount of shared memory */

    unsigned long bufferram; /* Memory used by buffers */

    unsigned long totalswap; /* Total swap space size */

    unsigned long freeswap;  /* Swap space still available */

    unsigned short procs;    /* Number of current processes */

    char _f[22];             /* Pads structure to 64 bytes */
};
```

In the above structure, the sizes of the memory and swap fields are given in bytes.

Since Linux 2.3.23 (i386) and Linux 2.3.48 (all architectures) the structure is:

```
struct sysinfo {

    long uptime;             /* Seconds since boot */

    unsigned long loads[3];  /* 1, 5, and 15 minute load averages */

    unsigned long totalram;  /* Total usable main memory size */

    unsigned long freeram;   /* Available memory size */

    unsigned long sharedram; /* Amount of shared memory */

    unsigned long bufferram; /* Memory used by buffers */

    unsigned long totalswap; /* Total swap space size */

    unsigned long freeswap;  /* Swap space still available */

    unsigned short procs;    /* Number of current processes */

    unsigned long totalhigh; /* Total high memory size */

    unsigned long freehigh;  /* Available high memory size */

    unsigned int mem_unit;   /* Memory unit size in bytes */

    char _f[20-2*sizeof(long)-sizeof(int)];

                             /* Padding to 64 bytes */
};
```

In the above structure, sizes of the memory and swap fields are given as multiples of mem_unit bytes.

## RETURN VALUE
On success, sysinfo() returns zero. On error, -1 is returned, and errno is set to indicate the error.

## ERRORS
EFAULT

info is not a valid address.

## STANDARDS
Linux.

## HISTORY
Linux 0.98.pl6.

## NOTES
All of the information provided by this system call is also available via /proc/meminfo and /proc/loadavg.

## SEE ALSO
proc(5)


syslog

title: syslog(2)

text:
# syslog(2)

## NAME
syslog, klogctl - read and/or clear kernel message ring buffer; set console_loglevel

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/klog.h>        /* Definition of SYSLOG_* constants */
#include <sys/syscall.h>     /* Definition of SYS_* constants */
#include <unistd.h>
```

```
int syscall(SYS_syslog, int type, char *bufp, int len);
```

```
/* The glibc interface */
#include <sys/klog.h>
```

```
int klogctl(int type, char *bufp, int len);
```

## DESCRIPTION
Note: Probably, you are looking for the C library function syslog(), which talks to syslogd(8); see syslog(3) for details.

This page describes the kernel syslog() system call, which is used to control the kernel printk() buffer; the glibc wrapper function for the system call is called klogctl().

### The kernel log buffer
The kernel has a cyclic buffer of length LOG_BUF_LEN in which messages given as arguments to the kernel function printk() are stored (regardless of their log level). In early kernels, LOG_BUF_LEN had the value 4096; from Linux 1.3.54, it was 8192; from Linux 2.1.113, it was 16384; since Linux 2.4.23/2.6, the value is a kernel configuration option (CONFIG_LOG_BUF_SHIFT, default value dependent on the architecture). Since Linux 2.6.6, the size can be queried with command type 10 (see below).

### Commands
The type argument determines the action taken by this function. The list below specifies the values for type. The symbolic names are defined in the kernel source, but are not exported to user space; you will either need to use the numbers, or define the names yourself.

SYSLOG_ACTION_CLOSE (0)

Close the log. Currently a NOP.

SYSLOG_ACTION_OPEN (1)

Open the log. Currently a NOP.

SYSLOG_ACTION_READ (2)

Read from the log. The call waits until the kernel log buffer is nonempty, and then reads at most len bytes into the buffer pointed to by bufp. The call returns the number of bytes read. Bytes read from the log disappear from the log buffer: the information can be read only once. This is the function executed by the kernel when a user program reads /proc/kmsg.

SYSLOG_ACTION_READ_ALL (3)

Read all messages remaining in the ring buffer, placing them in the buffer pointed to by bufp. The call reads the last len bytes from the log buffer (nondestructively), but will not read more than was written into the buffer since the last "clear ring buffer" command (see command 5 below)). The call returns the number of bytes read.

SYSLOG_ACTION_READ_CLEAR (4)

Read and clear all messages remaining in the ring buffer. The call does precisely the same as for a type of 3, but also executes the "clear ring buffer" command.

SYSLOG_ACTION_CLEAR (5)

The call executes just the "clear ring buffer" command. The bufp and len arguments are ignored.

This command does not really clear the ring buffer. Rather, it sets a kernel bookkeeping variable that determines the results returned by commands 3 (SYSLOG_ACTION_READ_ALL) and 4 (SYSLOG_ACTION_READ_CLEAR). This command has no effect on commands 2 (SYSLOG_ACTION_READ) and 9 (SYSLOG_ACTION_SIZE_UNREAD).

SYSLOG_ACTION_CONSOLE_OFF (6)

The command saves the current value of console_loglevel and then sets console_loglevel to minimum_console_loglevel, so that no messages are printed to the console. Before Linux 2.6.32, the command simply sets console_loglevel to minimum_console_loglevel. See the discussion of /proc/sys/kernel/printk, below.

The bufp and len arguments are ignored.

SYSLOG_ACTION_CONSOLE_ON (7)

If a previous SYSLOG_ACTION_CONSOLE_OFF command has been performed, this command restores console_loglevel to the value that was saved by that command. Before Linux 2.6.32, this command simply sets console_loglevel to default_console_loglevel. See the discussion of /proc/sys/kernel/printk, below.

The bufp and len arguments are ignored.

SYSLOG_ACTION_CONSOLE_LEVEL (8)

The call sets console_loglevel to the value given in len, which must be an integer between 1 and 8 (inclusive). The kernel silently enforces a minimum value of minimum_console_loglevel for len. See the log level section for details. The bufp argument is ignored.

SYSLOG_ACTION_SIZE_UNREAD (9) (since Linux 2.4.10)

The call returns the number of bytes currently available to be read from the kernel log buffer via command 2 (SYSLOG_ACTION_READ). The bufp and len arguments are ignored.

SYSLOG_ACTION_SIZE_BUFFER (10) (since Linux 2.6.6)

This command returns the total size of the kernel log buffer. The bufp and len arguments are ignored.

All commands except 3 and 10 require privilege. In Linux kernels before Linux 2.6.37, command types 3 and 10 are allowed to unprivileged processes; since Linux 2.6.37, these commands are allowed to unprivileged processes only if /proc/sys/kernel/dmesg_restrict has the value 0. Before Linux 2.6.37, "privileged" means that the caller has the CAP_SYS_ADMIN capability. Since Linux 2.6.37, "privileged" means that the caller has either the CAP_SYS_ADMIN capability (now deprecated for this purpose) or the (new) CAP_SYSLOG capability.

### /proc/sys/kernel/printk
/proc/sys/kernel/printk is a writable file containing four integer values that influence kernel printk() behavior when printing or logging error messages. The four values are:

console_loglevel

Only messages with a log level lower than this value will be printed to the console. The default value for this field is DEFAULT_CONSOLE_LOGLEVEL (7), but it is set to 4 if the kernel command line contains the word "quiet", 10 if the kernel command line contains the word "debug", and to 15 in case of a kernel fault (the 10 and 15 are just silly, and equivalent to 8). The value of console_loglevel can be set (to a value in the range 1–8) by a syslog() call with a type of 8.

default_message_loglevel

This value will be used as the log level for printk() messages that do not have an explicit level. Up to and including Linux 2.6.38, the hard-coded default value for this field was 4 (KERN_WARNING); since Linux 2.6.39, the default value is defined by the kernel configuration option CONFIG_DEFAULT_MESSAGE_LOGLEVEL, which defaults to 4.

minimum_console_loglevel

The value in this field is the minimum value to which console_loglevel can be set.

default_console_loglevel

This is the default value for console_loglevel.

### The log level
Every printk() message has its own log level. If the log level is not explicitly specified as part of the message, it defaults to default_message_loglevel. The conventional meaning of the log level is as follows:

Kernel constant

Level value

Meaning

KERN_EMERG

0

System is unusable

KERN_ALERT

1

Action must be taken immediately

KERN_CRIT

2

Critical conditions

KERN_ERR

3

Error conditions

KERN_WARNING

4

Warning conditions

KERN_NOTICE

5

Normal but significant condition

KERN_INFO

6

Informational

KERN_DEBUG

7

Debug-level messages

The kernel printk() routine will print a message on the console only if it has a log level less than the value of console_loglevel.

## RETURN VALUE
For type equal to 2, 3, or 4, a successful call to syslog() returns the number of bytes read. For type 9, syslog() returns the number of bytes currently available to be read on the kernel log buffer. For type 10, syslog() returns the total size of the kernel log buffer. For other values of type, 0 is returned on success.

In case of error, -1 is returned, and errno is set to indicate the error.

## ERRORS
EINVAL

Bad arguments (e.g., bad type; or for type 2, 3, or 4, buf is NULL, or len is less than zero; or for type 8, the level is outside the range 1 to 8).

ENOSYS

This syslog() system call is not available, because the kernel was compiled with the CONFIG_PRINTK kernel-configuration option disabled.

EPERM

An attempt was made to change console_loglevel or clear the kernel message ring buffer by a process without sufficient privilege (more precisely: without the CAP_SYS_ADMIN or CAP_SYSLOG capability).

ERESTARTSYS

System call was interrupted by a signal; nothing was read. (This can be seen only during a trace.)

## STANDARDS
Linux.

## HISTORY
From the very start, people noted that it is unfortunate that a system call and a library routine of the same name are entirely different animals.

## SEE ALSO
dmesg(1), syslog(3), capabilities(7)


tee

title: tee(2)

summary: duplicating pipe content

text:
# tee(2)

## NAME
tee - duplicating pipe content

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#define _GNU_SOURCE         /* See feature_test_macros(7) */
#include <fcntl.h>
```

```
ssize_t tee(int fd_in, int fd_out, size_t len, unsigned int flags);
```

## DESCRIPTION
tee() duplicates up to len bytes of data from the pipe referred to by the file descriptor fd_in to the pipe referred to by the file descriptor fd_out. It does not consume the data that is duplicated from fd_in; therefore, that data can be copied by a subsequent splice(2).

flags is a bit mask that is composed by ORing together zero or more of the following values:

SPLICE_F_MOVE

Currently has no effect for tee(); see splice(2).

SPLICE_F_NONBLOCK

Do not block on I/O; see splice(2) for further details.

SPLICE_F_MORE

Currently has no effect for tee(), but may be implemented in the future; see splice(2).

SPLICE_F_GIFT

Unused for tee(); see vmsplice(2).

## RETURN VALUE
Upon successful completion, tee() returns the number of bytes that were duplicated between the input and output. A return value of 0 means that there was no data to transfer, and it would not make sense to block, because there are no writers connected to the write end of the pipe referred to by fd_in.

On error, tee() returns -1 and errno is set to indicate the error.

## ERRORS
EAGAIN

SPLICE_F_NONBLOCK was specified in flags or one of the file descriptors had been marked as nonblocking (O_NONBLOCK), and the operation would block.

EINVAL

fd_in or fd_out does not refer to a pipe; or fd_in and fd_out refer to the same pipe.

ENOMEM

Out of memory.

## STANDARDS
Linux.

## HISTORY
Linux 2.6.17, glibc 2.5.

## NOTES
Conceptually, tee() copies the data between the two pipes. In reality no real data copying takes place though: under the covers, tee() assigns data to the output by merely grabbing a reference to the input.

## EXAMPLES
The example below implements a basic tee(1) program using the tee() system call. Here is an example of its use:

```
$ date | ./a.out out.log | cat
Tue Oct 28 10:06:00 CET 2014
$ cat out.log
Tue Oct 28 10:06:00 CET 2014
```

### Program source

```
#define _GNU_SOURCE
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
int
main(int argc, char *argv[])
{

    int      fd;

    ssize_t  len, slen;

    if (argc != 2) {

        fprintf(stderr, "Usage: %s <file>\n", argv[0]);

        exit(EXIT_FAILURE);

    }

    fd = open(argv[1], O_WRONLY | O_CREAT | O_TRUNC, 0644);

    if (fd == -1) {

        perror("open");

        exit(EXIT_FAILURE);

    }

    for (;;) {

        /*

         * tee stdin to stdout.

         */

        len = tee(STDIN_FILENO, STDOUT_FILENO,

                  INT_MAX, SPLICE_F_NONBLOCK);

        if (len < 0) {

            if (errno == EAGAIN)

                continue;

            perror("tee");

            exit(EXIT_FAILURE);

        }

        if (len == 0)

            break;

        /*

         * Consume stdin by splicing it to a file.

         */

        while (len > 0) {

            slen = splice(STDIN_FILENO, NULL, fd, NULL,

                          len, SPLICE_F_MOVE);

            if (slen < 0) {

                perror("splice");

                exit(EXIT_FAILURE);

            }

            len -= slen;

        }

    }

    close(fd);

    exit(EXIT_SUCCESS);
}
```

## SEE ALSO
splice(2), vmsplice(2), pipe(7)


time

title: time(2)

summary: get time in seconds

text:
# time(2)

## NAME
time - get time in seconds

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <time.h>
```

```
time_t time(time_t *_Nullable tloc);
```

## DESCRIPTION
time() returns the time as the number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).

If tloc is non-NULL, the return value is also stored in the memory pointed to by tloc.

## RETURN VALUE
On success, the value of time in seconds since the Epoch is returned. On error, ((time_t) -1) is returned, and errno is set to indicate the error.

## ERRORS
EFAULT

tloc points outside your accessible address space (but see BUGS).

On systems where the C library time() wrapper function invokes an implementation provided by the vdso(7) (so that there is no trap into the kernel), an invalid address may instead trigger a SIGSEGV signal.

## VERSIONS
POSIX.1 defines seconds since the Epoch using a formula that approximates the number of seconds between a specified time and the Epoch. This formula takes account of the facts that all years that are evenly divisible by 4 are leap years, but years that are evenly divisible by 100 are not leap years unless they are also evenly divisible by 400, in which case they are leap years. This value is not the same as the actual number of seconds between the time and the Epoch, because of leap seconds and because system clocks are not required to be synchronized to a standard reference. The intention is that the interpretation of seconds since the Epoch values be consistent; see POSIX.1-2008 Rationale A.4.15 for further rationale.

On Linux, a call to time() with tloc specified as NULL cannot fail with the error EOVERFLOW, even on ABIs where time_t is a signed 32-bit integer and the clock reaches or exceeds 2**31 seconds (2038-01-19 03:14:08 UTC, ignoring leap seconds). (POSIX.1 permits, but does not require, the EOVERFLOW error in the case where the seconds since the Epoch will not fit in time_t.) Instead, the behavior on Linux is undefined when the system time is out of the time_t range. Applications intended to run after 2038 should use ABIs with time_t wider than 32 bits.

### C library/kernel differences
On some architectures, an implementation of time() is provided in the vdso(7).

## STANDARDS
C11, POSIX.1-2008.

## HISTORY
SVr4, 4.3BSD, C89, POSIX.1-2001.

## BUGS
Error returns from this system call are indistinguishable from successful reports that the time is a few seconds before the Epoch, so the C library wrapper function never sets errno as a result of this call.

The tloc argument is obsolescent and should always be NULL in new code. When tloc is NULL, the call cannot fail.

## SEE ALSO
date(1), gettimeofday(2), ctime(3), ftime(3), time(7), vdso(7)


title: timer_create(2)

summary: create a POSIX per-process timer

text:
# timer_create(2)

## NAME
timer_create - create a POSIX per-process timer

## LIBRARY
Real-time library (librt, -lrt)

## SYNOPSIS

```
#include <signal.h>           /* Definition of SIGEV_* constants */
#include <time.h>
```

```
int timer_create(clockid_t clockid,
                 struct sigevent *_Nullable restrict sevp,
                 timer_t *restrict timerid);
```

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

timer_create():

```
    _POSIX_C_SOURCE >= 199309L
```

## DESCRIPTION
timer_create() creates a new per-process interval timer. The ID of the new timer is returned in the buffer pointed to by timerid, which must be a non-null pointer. This ID is unique within the process, until the timer is deleted. The new timer is initially disarmed.

The clockid argument specifies the clock that the new timer uses to measure time. It can be specified as one of the following values:

CLOCK_REALTIME

A settable system-wide real-time clock.

CLOCK_MONOTONIC

A nonsettable monotonically increasing clock that measures time from some unspecified point in the past that does not change after system startup.

CLOCK_PROCESS_CPUTIME_ID (since Linux 2.6.12)

A clock that measures (user and system) CPU time consumed by (all of the threads in) the calling process.

CLOCK_THREAD_CPUTIME_ID (since Linux 2.6.12)

A clock that measures (user and system) CPU time consumed by the calling thread.

CLOCK_BOOTTIME (Since Linux 2.6.39)

Like CLOCK_MONOTONIC, this is a monotonically increasing clock. However, whereas the CLOCK_MONOTONIC clock does not measure the time while a system is suspended, the CLOCK_BOOTTIME clock does include the time during which the system is suspended. This is useful for applications that need to be suspend-aware. CLOCK_REALTIME is not suitable for such applications, since that clock is affected by discontinuous changes to the system clock.

CLOCK_REALTIME_ALARM (since Linux 3.0)

This clock is like CLOCK_REALTIME, but will wake the system if it is suspended. The caller must have the CAP_WAKE_ALARM capability in order to set a timer against this clock.

CLOCK_BOOTTIME_ALARM (since Linux 3.0)

This clock is like CLOCK_BOOTTIME, but will wake the system if it is suspended. The caller must have the CAP_WAKE_ALARM capability in order to set a timer against this clock.

CLOCK_TAI (since Linux 3.10)

A system-wide clock derived from wall-clock time but ignoring leap seconds.

See clock_getres(2) for some further details on the above clocks.

As well as the above values, clockid can be specified as the clockid returned by a call to clock_getcpuclockid(3) or pthread_getcpuclockid(3).

The sevp argument points to a sigevent structure that specifies how the caller should be notified when the timer expires. For the definition and general details of this structure, see sigevent(7).

The sevp.sigev_notify field can have the following values:

SIGEV_NONE

Don't asynchronously notify when the timer expires. Progress of the timer can be monitored using timer_gettime(2).

SIGEV_SIGNAL

Upon timer expiration, generate the signal sigev_signo for the process. See sigevent(7) for general details. The si_code field of the siginfo_t structure will be set to SI_TIMER. At any point in time, at most one signal is queued to the process for a given timer; see timer_getoverrun(2) for more details.

SIGEV_THREAD

Upon timer expiration, invoke sigev_notify_function as if it were the start function of a new thread. See sigevent(7) for details.

SIGEV_THREAD_ID (Linux-specific)

As for SIGEV_SIGNAL, but the signal is targeted at the thread whose ID is given in sigev_notify_thread_id, which must be a thread in the same process as the caller. The sigev_notify_thread_id field specifies a kernel thread ID, that is, the value returned by clone(2) or gettid(2). This flag is intended only for use by threading libraries.

Specifying sevp as NULL is equivalent to specifying a pointer to a sigevent structure in which sigev_notify is SIGEV_SIGNAL, sigev_signo is SIGALRM, and sigev_value.sival_int is the timer ID.

## RETURN VALUE
On success, timer_create() returns 0, and the ID of the new timer is placed in *timerid. On failure, -1 is returned, and errno is set to indicate the error.

## ERRORS
EAGAIN

Temporary error during kernel allocation of timer structures.

EINVAL

Clock ID, sigev_notify, sigev_signo, or sigev_notify_thread_id is invalid.

ENOMEM

Could not allocate memory.

ENOTSUP

The kernel does not support creating a timer against this clockid.

EPERM

clockid was CLOCK_REALTIME_ALARM or CLOCK_BOOTTIME_ALARM but the caller did not have the CAP_WAKE_ALARM capability.

## VERSIONS

### C library/kernel differences
Part of the implementation of the POSIX timers API is provided by glibc. In particular:

•

Much of the functionality for SIGEV_THREAD is implemented within glibc, rather than the kernel. (This is necessarily so, since the thread involved in handling the notification is one that must be managed by the C library POSIX threads implementation.) Although the notification delivered to the process is via a thread, internally the NPTL implementation uses a sigev_notify value of SIGEV_THREAD_ID along with a real-time signal that is reserved by the implementation (see nptl(7)).

•

The implementation of the default case where evp is NULL is handled inside glibc, which invokes the underlying system call with a suitably populated sigevent structure.

•

The timer IDs presented at user level are maintained by glibc, which maps these IDs to the timer IDs employed by the kernel.

## STANDARDS
POSIX.1-2008.

## HISTORY
Linux 2.6. POSIX.1-2001.

Prior to Linux 2.6, glibc provided an incomplete user-space implementation (CLOCK_REALTIME timers only) using POSIX threads, and before glibc 2.17, the implementation falls back to this technique on systems running kernels older than Linux 2.6.

## NOTES
A program may create multiple interval timers using timer_create().

Timers are not inherited by the child of a fork(2), and are disarmed and deleted during an execve(2).

The kernel preallocates a "queued real-time signal" for each timer created using timer_create(). Consequently, the number of timers is limited by the RLIMIT_SIGPENDING resource limit (see setrlimit(2)).

The timers created by timer_create() are commonly known as "POSIX (interval) timers". The POSIX timers API consists of the following interfaces:

timer_create()

Create a timer.

timer_settime(2)

Arm (start) or disarm (stop) a timer.

timer_gettime(2)

Fetch the time remaining until the next expiration of a timer, along with the interval setting of the timer.

timer_getoverrun(2)

Return the overrun count for the last timer expiration.

timer_delete(2)

Disarm and delete a timer.

Since Linux 3.10, the /proc/pid/timers file can be used to list the POSIX timers for the process with PID pid. See proc(5) for further information.

Since Linux 4.10, support for POSIX timers is a configurable option that is enabled by default. Kernel support can be disabled via the CONFIG_POSIX_TIMERS option.

## EXAMPLES
The program below takes two arguments: a sleep period in seconds, and a timer frequency in nanoseconds. The program establishes a handler for the signal it uses for the timer, blocks that signal, creates and arms a timer that expires with the given frequency, sleeps for the specified number of seconds, and then unblocks the timer signal. Assuming that the timer expired at least once while the program slept, the signal handler will be invoked, and the handler displays some information about the timer notification. The program terminates after one invocation of the signal handler.

In the following example run, the program sleeps for 1 second, after creating a timer that has a frequency of 100 nanoseconds. By the time the signal is unblocked and delivered, there have been around ten million overruns.

```
$ ./a.out 1 100
Establishing handler for signal 34
Blocking signal 34
timer ID is 0x804c008
Sleeping for 1 seconds
Unblocking signal 34
Caught signal 34

    sival_ptr = 0xbfb174f4;     *sival_ptr = 0x804c008

    overrun count = 10004886
```

### Program source

```
#include <signal.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
#include <unistd.h>
#define CLOCKID CLOCK_REALTIME
#define SIG SIGRTMIN
#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \

                        } while (0)
static void
print_siginfo(siginfo_t *si)
{

    int      or;

    timer_t  *tidp;

    tidp = si->si_value.sival_ptr;

    printf("    sival_ptr = %p; ", si->si_value.sival_ptr);

    printf("    *sival_ptr = %#jx\n", (uintmax_t) *tidp);

    or = timer_getoverrun(*tidp);

    if (or == -1)

        errExit("timer_getoverrun");

    else

        printf("    overrun count = %d\n", or);
}
static void
handler(int sig, siginfo_t *si, void *uc)
{

    /* Note: calling printf() from a signal handler is not safe

       (and should not be done in production programs), since

       printf() is not async-signal-safe; see signal-safety(7).

       Nevertheless, we use printf() here as a simple way of

       showing that the handler was called. */

    printf("Caught signal %d\n", sig);

    print_siginfo(si);

    signal(sig, SIG_IGN);
}
int
main(int argc, char *argv[])
{

    timer_t            timerid;

    sigset_t           mask;

    long long          freq_nanosecs;

    struct sigevent    sev;

    struct sigaction   sa;

    struct itimerspec  its;

    if (argc != 3) {

        fprintf(stderr, "Usage: %s <sleep-secs> <freq-nanosecs>\n",

                argv[0]);

        exit(EXIT_FAILURE);

    }

    /* Establish handler for timer signal. */

    printf("Establishing handler for signal %d\n", SIG);

    sa.sa_flags = SA_SIGINFO;

    sa.sa_sigaction = handler;

    sigemptyset(&sa.sa_mask);

    if (sigaction(SIG, &sa, NULL) == -1)

        errExit("sigaction");

    /* Block timer signal temporarily. */

    printf("Blocking signal %d\n", SIG);

    sigemptyset(&mask);

    sigaddset(&mask, SIG);

    if (sigprocmask(SIG_SETMASK, &mask, NULL) == -1)

        errExit("sigprocmask");

    /* Create the timer. */

    sev.sigev_notify = SIGEV_SIGNAL;

    sev.sigev_signo = SIG;

    sev.sigev_value.sival_ptr = &timerid;

    if (timer_create(CLOCKID, &sev, &timerid) == -1)

        errExit("timer_create");

    printf("timer ID is %#jx\n", (uintmax_t) timerid);

    /* Start the timer. */

    freq_nanosecs = atoll(argv[2]);

    its.it_value.tv_sec = freq_nanosecs / 1000000000;

    its.it_value.tv_nsec = freq_nanosecs % 1000000000;

    its.it_interval.tv_sec = its.it_value.tv_sec;

    its.it_interval.tv_nsec = its.it_value.tv_nsec;

    if (timer_settime(timerid, 0, &its, NULL) == -1)

         errExit("timer_settime");

    /* Sleep for a while; meanwhile, the timer may expire

       multiple times. */

    printf("Sleeping for %d seconds\n", atoi(argv[1]));

    sleep(atoi(argv[1]));

    /* Unlock the timer signal, so that timer notification

       can be delivered. */

    printf("Unblocking signal %d\n", SIG);

    if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == -1)

        errExit("sigprocmask");

    exit(EXIT_SUCCESS);
}
```

## SEE ALSO
clock_gettime(2), setitimer(2), timer_delete(2), timer_getoverrun(2), timer_settime(2), timerfd_create(2), clock_getcpuclockid(3), pthread_getcpuclockid(3), pthreads(7), sigevent(7), signal(7), time(7)


title: timer_delete(2)

summary: delete a POSIX per-process timer

text:
# timer_delete(2)

## NAME
timer_delete - delete a POSIX per-process timer

## LIBRARY
Real-time library (librt, -lrt)

## SYNOPSIS

```
#include <time.h>
```

```
int timer_delete(timer_t timerid);
```

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

timer_delete():

```
    _POSIX_C_SOURCE >= 199309L
```

## DESCRIPTION
timer_delete() deletes the timer whose ID is given in timerid. If the timer was armed at the time of this call, it is disarmed before being deleted. The treatment of any pending signal generated by the deleted timer is unspecified.

## RETURN VALUE
On success, timer_delete() returns 0. On failure, -1 is returned, and errno is set to indicate the error.

## ERRORS
EINVAL

timerid is not a valid timer ID.

## STANDARDS
POSIX.1-2008.

## HISTORY
Linux 2.6. POSIX.1-2001.

## SEE ALSO
clock_gettime(2), timer_create(2), timer_getoverrun(2), timer_settime(2), time(7)


title: timer_getoverrun(2)

text:
# timer_getoverrun(2)

## NAME
timer_getoverrun - get overrun count for a POSIX per-process timer

## LIBRARY
Real-time library (librt, -lrt)

## SYNOPSIS

```
#include <time.h>
```

```
int timer_getoverrun(timer_t timerid);
```

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

timer_getoverrun():

```
    _POSIX_C_SOURCE >= 199309L
```

## DESCRIPTION
timer_getoverrun() returns the "overrun count" for the timer referred to by timerid. An application can use the overrun count to accurately calculate the number of timer expirations that would have occurred over a given time interval. Timer overruns can occur both when receiving expiration notifications via signals (SIGEV_SIGNAL), and via threads (SIGEV_THREAD).

When expiration notifications are delivered via a signal, overruns can occur as follows. Regardless of whether or not a real-time signal is used for timer notifications, the system queues at most one signal per timer. (This is the behavior specified by POSIX.1. The alternative, queuing one signal for each timer expiration, could easily result in overflowing the allowed limits for queued signals on the system.) Because of system scheduling delays, or because the signal may be temporarily blocked, there can be a delay between the time when the notification signal is generated and the time when it is delivered (e.g., caught by a signal handler) or accepted (e.g., using sigwaitinfo(2)). In this interval, further timer expirations may occur. The timer overrun count is the number of additional timer expirations that occurred between the time when the signal was generated and when it was delivered or accepted.

Timer overruns can also occur when expiration notifications are delivered via invocation of a thread, since there may be an arbitrary delay between an expiration of the timer and the invocation of the notification thread, and in that delay interval, additional timer expirations may occur.

## RETURN VALUE
On success, timer_getoverrun() returns the overrun count of the specified timer; this count may be 0 if no overruns have occurred. On failure, -1 is returned, and errno is set to indicate the error.

## ERRORS
EINVAL

timerid is not a valid timer ID.

## VERSIONS
When timer notifications are delivered via signals (SIGEV_SIGNAL), on Linux it is also possible to obtain the overrun count via the si_overrun field of the siginfo_t structure (see sigaction(2)). This allows an application to avoid the overhead of making a system call to obtain the overrun count, but is a nonportable extension to POSIX.1.

POSIX.1 discusses timer overruns only in the context of timer notifications using signals.

## STANDARDS
POSIX.1-2008.

## HISTORY
Linux 2.6. POSIX.1-2001.

## BUGS
POSIX.1 specifies that if the timer overrun count is equal to or greater than an implementation-defined maximum, DELAYTIMER_MAX, then timer_getoverrun() should return DELAYTIMER_MAX. However, before Linux 4.19, if the timer overrun value exceeds the maximum representable integer, the counter cycles, starting once more from low values. Since Linux 4.19, timer_getoverrun() returns DELAYTIMER_MAX (defined as INT_MAX in <limits.h>) in this case (and the overrun value is reset to 0).

## EXAMPLES
See timer_create(2).

## SEE ALSO
clock_gettime(2), sigaction(2), signalfd(2), sigwaitinfo(2), timer_create(2), timer_delete(2), timer_settime(2), signal(7), time(7)


title: timer_settime(2)

summary: arm/disarm and fetch

text:
# timer_settime(2)

## NAME
timer_settime, timer_gettime - arm/disarm and fetch state of POSIX per-process timer

## LIBRARY
Real-time library (librt, -lrt)

## SYNOPSIS

```
#include <time.h>
```

```
int timer_gettime(timer_t timerid, struct itimerspec *curr_value);
int timer_settime(timer_t timerid, int flags,
                  const struct itimerspec *restrict new_value,
                  struct itimerspec *_Nullable restrict old_value);
```

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

timer_settime(), timer_gettime():

```
    _POSIX_C_SOURCE >= 199309L
```

## DESCRIPTION
timer_settime() arms or disarms the timer identified by timerid. The new_value argument is pointer to an itimerspec structure that specifies the new initial value and the new interval for the timer. The itimerspec structure is described in itimerspec(3type).

Each of the substructures of the itimerspec structure is a timespec(3) structure that allows a time value to be specified in seconds and nanoseconds. These time values are measured according to the clock that was specified when the timer was created by timer_create(2).

If new_value->it_value specifies a nonzero value (i.e., either subfield is nonzero), then timer_settime() arms (starts) the timer, setting it to initially expire at the given time. (If the timer was already armed, then the previous settings are overwritten.) If new_value->it_value specifies a zero value (i.e., both subfields are zero), then the timer is disarmed.

The new_value->it_interval field specifies the period of the timer, in seconds and nanoseconds. If this field is nonzero, then each time that an armed timer expires, the timer is reloaded from the value specified in new_value->it_interval. If new_value->it_interval specifies a zero value, then the timer expires just once, at the time specified by it_value.

By default, the initial expiration time specified in new_value->it_value is interpreted relative to the current time on the timer's clock at the time of the call. This can be modified by specifying TIMER_ABSTIME in flags, in which case new_value->it_value is interpreted as an absolute value as measured on the timer's clock; that is, the timer will expire when the clock value reaches the value specified by new_value->it_value. If the specified absolute time has already passed, then the timer expires immediately, and the overrun count (see timer_getoverrun(2)) will be set correctly.

If the value of the CLOCK_REALTIME clock is adjusted while an absolute timer based on that clock is armed, then the expiration of the timer will be appropriately adjusted. Adjustments to the CLOCK_REALTIME clock have no effect on relative timers based on that clock.

If old_value is not NULL, then it points to a buffer that is used to return the previous interval of the timer (in old_value->it_interval) and the amount of time until the timer would previously have next expired (in old_value->it_value).

timer_gettime() returns the time until next expiration, and the interval, for the timer specified by timerid, in the buffer pointed to by curr_value. The time remaining until the next timer expiration is returned in curr_value->it_value; this is always a relative value, regardless of whether the TIMER_ABSTIME flag was used when arming the timer. If the value returned in curr_value->it_value is zero, then the timer is currently disarmed. The timer interval is returned in curr_value->it_interval. If the value returned in curr_value->it_interval is zero, then this is a "one-shot" timer.

## RETURN VALUE
On success, timer_settime() and timer_gettime() return 0. On error, -1 is returned, and errno is set to indicate the error.

## ERRORS
These functions may fail with the following errors:

EFAULT

new_value, old_value, or curr_value is not a valid pointer.

EINVAL

timerid is invalid.

timer_settime() may fail with the following errors:

EINVAL

new_value.it_value is negative; or new_value.it_value.tv_nsec is negative or greater than 999,999,999.

## STANDARDS
POSIX.1-2008.

## HISTORY
Linux 2.6. POSIX.1-2001.

## EXAMPLES
See timer_create(2).

## SEE ALSO
timer_create(2), timer_getoverrun(2), timespec(3), time(7)


title: timerfd_create(2)

text:
# timerfd_create(2)

## NAME
timerfd_create, timerfd_settime, timerfd_gettime - timers that notify via file descriptors

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/timerfd.h>
```

```
int timerfd_create(int clockid, int flags);
```

```
int timerfd_settime(int fd, int flags,
                    const struct itimerspec *new_value,
                    struct itimerspec *_Nullable old_value);
int timerfd_gettime(int fd, struct itimerspec *curr_value);
```

## DESCRIPTION
These system calls create and operate on a timer that delivers timer expiration notifications via a file descriptor. They provide an alternative to the use of setitimer(2) or timer_create(2), with the advantage that the file descriptor may be monitored by select(2), poll(2), and epoll(7).

The use of these three system calls is analogous to the use of timer_create(2), timer_settime(2), and timer_gettime(2). (There is no analog of timer_getoverrun(2), since that functionality is provided by read(2), as described below.)

### timerfd_create()
timerfd_create() creates a new timer object, and returns a file descriptor that refers to that timer. The clockid argument specifies the clock that is used to mark the progress of the timer, and must be one of the following:

CLOCK_REALTIME

A settable system-wide real-time clock.

CLOCK_MONOTONIC

A nonsettable monotonically increasing clock that measures time from some unspecified point in the past that does not change after system startup.

CLOCK_BOOTTIME (Since Linux 3.15)

Like CLOCK_MONOTONIC, this is a monotonically increasing clock. However, whereas the CLOCK_MONOTONIC clock does not measure the time while a system is suspended, the CLOCK_BOOTTIME clock does include the time during which the system is suspended. This is useful for applications that need to be suspend-aware. CLOCK_REALTIME is not suitable for such applications, since that clock is affected by discontinuous changes to the system clock.

CLOCK_REALTIME_ALARM (since Linux 3.11)

This clock is like CLOCK_REALTIME, but will wake the system if it is suspended. The caller must have the CAP_WAKE_ALARM capability in order to set a timer against this clock.

CLOCK_BOOTTIME_ALARM (since Linux 3.11)

This clock is like CLOCK_BOOTTIME, but will wake the system if it is suspended. The caller must have the CAP_WAKE_ALARM capability in order to set a timer against this clock.

See clock_getres(2) for some further details on the above clocks.

The current value of each of these clocks can be retrieved using clock_gettime(2).

Starting with Linux 2.6.27, the following values may be bitwise ORed in flags to change the behavior of timerfd_create():

TFD_NONBLOCK

Set the O_NONBLOCK file status flag on the open file description (see open(2)) referred to by the new file descriptor. Using this flag saves extra calls to fcntl(2) to achieve the same result.

TFD_CLOEXEC

Set the close-on-exec (FD_CLOEXEC) flag on the new file descriptor. See the description of the O_CLOEXEC flag in open(2) for reasons why this may be useful.

In Linux versions up to and including 2.6.26, flags must be specified as zero.

### timerfd_settime()
timerfd_settime() arms (starts) or disarms (stops) the timer referred to by the file descriptor fd.

The new_value argument specifies the initial expiration and interval for the timer. The itimerspec structure used for this argument is described in itimerspec(3type).

new_value.it_value specifies the initial expiration of the timer, in seconds and nanoseconds. Setting either field of new_value.it_value to a nonzero value arms the timer. Setting both fields of new_value.it_value to zero disarms the timer.

Setting one or both fields of new_value.it_interval to nonzero values specifies the period, in seconds and nanoseconds, for repeated timer expirations after the initial expiration. If both fields of new_value.it_interval are zero, the timer expires just once, at the time specified by new_value.it_value.

By default, the initial expiration time specified in new_value is interpreted relative to the current time on the timer's clock at the time of the call (i.e., new_value.it_value specifies a time relative to the current value of the clock specified by clockid). An absolute timeout can be selected via the flags argument.

The flags argument is a bit mask that can include the following values:

TFD_TIMER_ABSTIME

Interpret new_value.it_value as an absolute value on the timer's clock. The timer will expire when the value of the timer's clock reaches the value specified in new_value.it_value.

TFD_TIMER_CANCEL_ON_SET

If this flag is specified along with TFD_TIMER_ABSTIME and the clock for this timer is CLOCK_REALTIME or CLOCK_REALTIME_ALARM, then mark this timer as cancelable if the real-time clock undergoes a discontinuous change (settimeofday(2), clock_settime(2), or similar). When such changes occur, a current or future read(2) from the file descriptor will fail with the error ECANCELED.

If the old_value argument is not NULL, then the itimerspec structure that it points to is used to return the setting of the timer that was current at the time of the call; see the description of timerfd_gettime() following.

### timerfd_gettime()
timerfd_gettime() returns, in curr_value, an itimerspec structure that contains the current setting of the timer referred to by the file descriptor fd.

The it_value field returns the amount of time until the timer will next expire. If both fields of this structure are zero, then the timer is currently disarmed. This field always contains a relative value, regardless of whether the TFD_TIMER_ABSTIME flag was specified when setting the timer.

The it_interval field returns the interval of the timer. If both fields of this structure are zero, then the timer is set to expire just once, at the time specified by curr_value.it_value.

### Operating on a timer file descriptor
The file descriptor returned by timerfd_create() supports the following additional operations:

read(2)

If the timer has already expired one or more times since its settings were last modified using timerfd_settime(), or since the last successful read(2), then the buffer given to read(2) returns an unsigned 8-byte integer (uint64_t) containing the number of expirations that have occurred. (The returned value is in host byte order—that is, the native byte order for integers on the host machine.)

If no timer expirations have occurred at the time of the read(2), then the call either blocks until the next timer expiration, or fails with the error EAGAIN if the file descriptor has been made nonblocking (via the use of the fcntl(2) F_SETFL operation to set the O_NONBLOCK flag).

A read(2) fails with the error EINVAL if the size of the supplied buffer is less than 8 bytes.

If the associated clock is either CLOCK_REALTIME or CLOCK_REALTIME_ALARM, the timer is absolute (TFD_TIMER_ABSTIME), and the flag TFD_TIMER_CANCEL_ON_SET was specified when calling timerfd_settime(), then read(2) fails with the error ECANCELED if the real-time clock undergoes a discontinuous change. (This allows the reading application to discover such discontinuous changes to the clock.)

If the associated clock is either CLOCK_REALTIME or CLOCK_REALTIME_ALARM, the timer is absolute (TFD_TIMER_ABSTIME), and the flag TFD_TIMER_CANCEL_ON_SET was not specified when calling timerfd_settime(), then a discontinuous negative change to the clock (e.g., clock_settime(2)) may cause read(2) to unblock, but return a value of 0 (i.e., no bytes read), if the clock change occurs after the time expired, but before the read(2) on the file descriptor.

poll(2), select(2) (and similar)

The file descriptor is readable (the select(2) readfds argument; the poll(2) POLLIN flag) if one or more timer expirations have occurred.

The file descriptor also supports the other file-descriptor multiplexing APIs: pselect(2), ppoll(2), and epoll(7).

ioctl(2)

The following timerfd-specific command is supported:

TFD_IOC_SET_TICKS (since Linux 3.17)

Adjust the number of timer expirations that have occurred. The argument is a pointer to a nonzero 8-byte integer (uint64_t*) containing the new number of expirations. Once the number is set, any waiter on the timer is woken up. The only purpose of this command is to restore the expirations for the purpose of checkpoint/restore. This operation is available only if the kernel was configured with the CONFIG_CHECKPOINT_RESTORE option.

close(2)

When the file descriptor is no longer required it should be closed. When all file descriptors associated with the same timer object have been closed, the timer is disarmed and its resources are freed by the kernel.

### fork(2) semantics
After a fork(2), the child inherits a copy of the file descriptor created by timerfd_create(). The file descriptor refers to the same underlying timer object as the corresponding file descriptor in the parent, and read(2)s in the child will return information about expirations of the timer.

### execve(2) semantics
A file descriptor created by timerfd_create() is preserved across execve(2), and continues to generate timer expirations if the timer was armed.

## RETURN VALUE
On success, timerfd_create() returns a new file descriptor. On error, -1 is returned and errno is set to indicate the error.

timerfd_settime() and timerfd_gettime() return 0 on success; on error they return -1, and set errno to indicate the error.

## ERRORS
timerfd_create() can fail with the following errors:

EINVAL

The clockid is not valid.

EINVAL

flags is invalid; or, in Linux 2.6.26 or earlier, flags is nonzero.

EMFILE

The per-process limit on the number of open file descriptors has been reached.

ENFILE

The system-wide limit on the total number of open files has been reached.

ENODEV

Could not mount (internal) anonymous inode device.

ENOMEM

There was insufficient kernel memory to create the timer.

EPERM

clockid was CLOCK_REALTIME_ALARM or CLOCK_BOOTTIME_ALARM but the caller did not have the CAP_WAKE_ALARM capability.

timerfd_settime() and timerfd_gettime() can fail with the following errors:

EBADF

fd is not a valid file descriptor.

EFAULT

new_value, old_value, or curr_value is not a valid pointer.

EINVAL

fd is not a valid timerfd file descriptor.

timerfd_settime() can also fail with the following errors:

ECANCELED

See NOTES.

EINVAL

new_value is not properly initialized (one of the tv_nsec falls outside the range zero to 999,999,999).

EINVAL

flags is invalid.

## STANDARDS
Linux.

## HISTORY
Linux 2.6.25, glibc 2.8.

## NOTES
Suppose the following scenario for CLOCK_REALTIME or CLOCK_REALTIME_ALARM timer that was created with timerfd_create():

(1)

The timer has been started (timerfd_settime()) with the TFD_TIMER_ABSTIME and TFD_TIMER_CANCEL_ON_SET flags;

(2)

A discontinuous change (e.g., settimeofday(2)) is subsequently made to the CLOCK_REALTIME clock; and

(3)

the caller once more calls timerfd_settime() to rearm the timer (without first doing a read(2) on the file descriptor).

In this case the following occurs:

•

The timerfd_settime() returns -1 with errno set to ECANCELED. (This enables the caller to know that the previous timer was affected by a discontinuous change to the clock.)

•

The timer is successfully rearmed with the settings provided in the second timerfd_settime() call. (This was probably an implementation accident, but won't be fixed now, in case there are applications that depend on this behaviour.)

## BUGS
Currently, timerfd_create() supports fewer types of clock IDs than timer_create(2).

## EXAMPLES
The following program creates a timer and then monitors its progress. The program accepts up to three command-line arguments. The first argument specifies the number of seconds for the initial expiration of the timer. The second argument specifies the interval for the timer, in seconds. The third argument specifies the number of times the program should allow the timer to expire before terminating. The second and third command-line arguments are optional.

The following shell session demonstrates the use of the program:

```
$ a.out 3 1 100
0.000: timer started
3.000: read: 1; total=1
4.000: read: 1; total=2
^Z                  # type control-Z to suspend the program
[1]+  Stopped                 ./timerfd3_demo 3 1 100
$ fg                # Resume execution after a few seconds
a.out 3 1 100
9.660: read: 5; total=7
10.000: read: 1; total=8
11.000: read: 1; total=9
^C                  # type control-C to suspend the program
```

### Program source

```
#include <err.h>
#include <inttypes.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/timerfd.h>
#include <time.h>
#include <unistd.h>
static void
print_elapsed_time(void)
{

    int                     secs, nsecs;

    static int              first_call = 1;

    struct timespec         curr;

    static struct timespec  start;

    if (first_call) {

        first_call = 0;

        if (clock_gettime(CLOCK_MONOTONIC, &start) == -1)

            err(EXIT_FAILURE, "clock_gettime");

    }

    if (clock_gettime(CLOCK_MONOTONIC, &curr) == -1)

        err(EXIT_FAILURE, "clock_gettime");

    secs = curr.tv_sec - start.tv_sec;

    nsecs = curr.tv_nsec - start.tv_nsec;

    if (nsecs < 0) {

        secs--;

        nsecs += 1000000000;

    }

    printf("%d.%03d: ", secs, (nsecs + 500000) / 1000000);
}
int
main(int argc, char *argv[])
{

    int                fd;

    ssize_t            s;

    uint64_t           exp, tot_exp, max_exp;

    struct timespec    now;

    struct itimerspec  new_value;

    if (argc != 2 && argc != 4) {

        fprintf(stderr, "%s init-secs [interval-secs max-exp]\n",

                argv[0]);

        exit(EXIT_FAILURE);

    }

    if (clock_gettime(CLOCK_REALTIME, &now) == -1)

        err(EXIT_FAILURE, "clock_gettime");

    /* Create a CLOCK_REALTIME absolute timer with initial

       expiration and interval as specified in command line. */

    new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]);

    new_value.it_value.tv_nsec = now.tv_nsec;

    if (argc == 2) {

        new_value.it_interval.tv_sec = 0;

        max_exp = 1;

    } else {

        new_value.it_interval.tv_sec = atoi(argv[2]);

        max_exp = atoi(argv[3]);

    }

    new_value.it_interval.tv_nsec = 0;

    fd = timerfd_create(CLOCK_REALTIME, 0);

    if (fd == -1)

        err(EXIT_FAILURE, "timerfd_create");

    if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == -1)

        err(EXIT_FAILURE, "timerfd_settime");

    print_elapsed_time();

    printf("timer started\n");

    for (tot_exp = 0; tot_exp < max_exp;) {

        s = read(fd, &exp, sizeof(uint64_t));

        if (s != sizeof(uint64_t))

            err(EXIT_FAILURE, "read");

        tot_exp += exp;

        print_elapsed_time();

        printf("read: %" PRIu64 "; total=%" PRIu64 "\n", exp, tot_exp);

    }

    exit(EXIT_SUCCESS);
}
```

## SEE ALSO
eventfd(2), poll(2), read(2), select(2), setitimer(2), signalfd(2), timer_create(2), timer_gettime(2), timer_settime(2), timespec(3), epoll(7), time(7)


times

title: times(2)

summary: get process times

text:
# times(2)

## NAME
times - get process times

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/times.h>
```

```
clock_t times(struct tms *buf);
```

## DESCRIPTION
times() stores the current process times in the struct tms that buf points to. The struct tms is as defined in <sys/times.h>:

```
struct tms {

    clock_t tms_utime;  /* user time */

    clock_t tms_stime;  /* system time */

    clock_t tms_cutime; /* user time of children */

    clock_t tms_cstime; /* system time of children */
};
```

The tms_utime field contains the CPU time spent executing instructions of the calling process. The tms_stime field contains the CPU time spent executing inside the kernel while performing tasks on behalf of the calling process.

The tms_cutime field contains the sum of the tms_utime and tms_cutime values for all waited-for terminated children. The tms_cstime field contains the sum of the tms_stime and tms_cstime values for all waited-for terminated children.

Times for terminated children (and their descendants) are added in at the moment wait(2) or waitpid(2) returns their process ID. In particular, times of grandchildren that the children did not wait for are never seen.

All times reported are in clock ticks.

## RETURN VALUE
times() returns the number of clock ticks that have elapsed since an arbitrary point in the past. The return value may overflow the possible range of type clock_t. On error, (clock_t) -1 is returned, and errno is set to indicate the error.

## ERRORS
EFAULT

tms points outside the process's address space.

## VERSIONS
On Linux, the buf argument can be specified as NULL, with the result that times() just returns a function result. However, POSIX does not specify this behavior, and most other UNIX implementations require a non-NULL value for buf.

## STANDARDS
POSIX.1-2008.

## HISTORY
POSIX.1-2001, SVr4, 4.3BSD.

In POSIX.1-1996 the symbol CLK_TCK (defined in <time.h>) is mentioned as obsolescent. It is obsolete now.

Before Linux 2.6.9, if the disposition of SIGCHLD is set to SIG_IGN, then the times of terminated children are automatically included in the tms_cstime and tms_cutime fields, although POSIX.1-2001 says that this should happen only if the calling process wait(2)s on its children. This nonconformance is rectified in Linux 2.6.9 and later.

On Linux, the “arbitrary point in the past” from which the return value of times() is measured has varied across kernel versions. On Linux 2.4 and earlier, this point is the moment the system was booted. Since Linux 2.6, this point is (2^32/HZ) - 300 seconds before system boot time. This variability across kernel versions (and across UNIX implementations), combined with the fact that the returned value may overflow the range of clock_t, means that a portable application would be wise to avoid using this value. To measure changes in elapsed time, use clock_gettime(2) instead.

SVr1-3 returns long and the struct members are of type time_t although they store clock ticks, not seconds since the Epoch. V7 used long for the struct members, because it had no type time_t yet.

## NOTES
The number of clock ticks per second can be obtained using:

```
sysconf(_SC_CLK_TCK);
```

Note that clock(3) also returns a value of type clock_t, but this value is measured in units of CLOCKS_PER_SEC, not the clock ticks used by times().

## BUGS
A limitation of the Linux system call conventions on some architectures (notably i386) means that on Linux 2.6 there is a small time window (41 seconds) soon after boot when times() can return -1, falsely indicating that an error occurred. The same problem can occur when the return value wraps past the maximum value that can be stored in clock_t.

## SEE ALSO
time(1), getrusage(2), wait(2), clock(3), sysconf(3), time(7)